BidsFileDictionary

class BidsFileDictionary(collection_name, files, entities=('sub', 'ses', 'task', 'run'))[source]

A dictionary of BidsFile keyed by entity pairs.

The keys are simplified entity key-value pairs and the values are BidsFile objects.

Methods

BidsFileDictionary.__init__(collection_name, ...)

Create the dictionary keyed to entities.

BidsFileDictionary.create_file_dict(...)

Create new dict based on key indices.

BidsFileDictionary.get_file_path(key)

Return the file path corresponding to key.

BidsFileDictionary.get_new_dict(name, files)

Create a dictionary with these files.

BidsFileDictionary.iter_files()

Iterator over the files in this dictionary.

BidsFileDictionary.key_diffs(other_dict)

Return the symmetric key difference with another file dictionary.

BidsFileDictionary.make_dict(files, entities)

Make a dictionary from files or a dict.

BidsFileDictionary.make_file_dict(file_list)

Return a dictionary of files using entity keys.

BidsFileDictionary.make_key(key_string[, ...])

Create a key from specified entities.

BidsFileDictionary.make_query([query_dict])

Return a dictionary of files matching query.

BidsFileDictionary.match_query(query_dict, ...)

Return True if query has a match in dictionary.

BidsFileDictionary.output_files([title, logger])

Return a string with the output of the list.

BidsFileDictionary.split_by_entity(entity)

Split this dictionary based on an entity.

Attributes

BidsFileDictionary.file_dict

Dictionary of keys and paths.

BidsFileDictionary.file_list

Paths of the files in the list.

BidsFileDictionary.key_list

The dictionary keys.

BidsFileDictionary.name

Name of this dictionary.

BidsFileDictionary.__init__(collection_name, files, entities=('sub', 'ses', 'task', 'run'))[source]

Create the dictionary keyed to entities.

Parameters:
  • collection_name (str) – Name of this collection.

  • files (list or dict) – Full paths of files to include.

  • entities (tuple) – Entity names to use in creating the keys.

Raises:

HedFileError

  • If files has inappropriate values.

Notes

  • This function is used for cross listing BIDS style files for different studies.

Examples

If entities is (‘sub’, ‘ses’, ‘task’, ‘run’), a typical key might be sub-001_ses-01_task-memory_run-01.

BidsFileDictionary.create_file_dict(file_list, key_indices, separator)

Create new dict based on key indices.

Parameters:
  • file_list (list) – Paths of the files to include.

  • key_indices (tuple) – A tuple of integers representing order of entities for key.

  • separator (str) – The separator used between entities to form the key.

BidsFileDictionary.get_file_path(key)[source]

Return the file path corresponding to key.

Parameters:

key (str) – The key to use to look up the file in this dictionary.

Returns:

The real path of the file being looked up.

Return type:

str

Notes

  • None is returned if the key is not present.

BidsFileDictionary.get_new_dict(name, files)[source]

Create a dictionary with these files.

Parameters:
  • name (str) – Name of this dictionary.

  • files (list or dict) – List or dictionary of files. These could be paths or objects.

Returns:

The newly created dictionary.

Return type:

BidsFileDictionary

Notes

  • The new dictionary uses the same type of entities for keys as this dictionary.

BidsFileDictionary.iter_files()[source]

Iterator over the files in this dictionary.

Yields:

tuple – - str: The next entity-based key. - BidsFile: The next BidsFile.

BidsFileDictionary.key_diffs(other_dict)[source]

Return the symmetric key difference with another file dictionary.

Parameters:

other_dict (FileDictionary) –

Returns:

The symmetric difference of the keys in this dictionary and the other one.

Return type:

list

BidsFileDictionary.make_dict(files, entities)[source]

Make a dictionary from files or a dict.

Parameters:
  • files (list or dict) – List or dictionary of file-like objs to use.

  • entities (tuple) – Tuple of entity names to use as keys, e.g. (‘sub’, ‘run’).

Returns:

A dictionary whose keys are entity keys and values are BidsFile objects.

Return type:

dict

Raises:

HedFileError

  • If incorrect format is passed or something not recognizable as a Bids file.

static BidsFileDictionary.make_file_dict(file_list, key_indices=(0, 2), separator='_')

Return a dictionary of files using entity keys.

Parameters:
  • file_list (list) – Paths to files to use.

  • key_indices (tuple) – Positions of entities to use for key.

  • separator (str) – Separator character used to construct key.

Returns:

Key is based on key indices and value is a full path.

Return type:

dict

static BidsFileDictionary.make_key(key_string, indices=(0, 2), separator='_')

Create a key from specified entities.

Parameters:
  • key_string (str) – The string from which to extract the key (usually a filename or path).

  • indices (tuple) – Positions of entity pairs to use as key.

  • separator (str) – Separator between entity pairs in the created key.

Returns:

The created key.

Return type:

str

BidsFileDictionary.make_query(query_dict={'sub': '*'})[source]

Return a dictionary of files matching query.

Parameters:

query_dict (dict) – A dictionary whose keys are entities and whose values are entity values to match.

Returns:

A dictionary entries in this dictionary that match the query.

Return type:

dict

Notes

  • A query dictionary key a valid BIDS entity name such as sub or task.

  • A query dictionary value may be a string or a list.

  • A query value string should contain a specific value of the entity or a ‘*’ indicating any value matches.

  • A query value list should be a list of valid values for the corresponding entity.

static BidsFileDictionary.match_query(query_dict, entity_dict)[source]

Return True if query has a match in dictionary.

Parameters:
  • query_dict (dict) – A dictionary representing a query about entities.

  • entity_dict (dict) – A dictionary containing the entity representation for a BIDS file.

Returns:

True if the query matches the entities representing the file.

Return type:

bool

Notes

  • A query is a dictionary whose keys are entity names and whose values are specific entity values or ‘*’.

Examples

{‘sub’, ‘001’, ‘run’, ‘*’} requests all runs from subject 001.

BidsFileDictionary.output_files(title=None, logger=None)

Return a string with the output of the list.

Parameters:
  • title (None, str) – Optional title.

  • logger (HedLogger) – Optional HED logger for recording.

Returns:

The dictionary in string form.

Return type:

str

Notes

  • The logger is updated if available.

BidsFileDictionary.split_by_entity(entity)[source]

Split this dictionary based on an entity.

Parameters:

entity (str) – Entity name (for example task).

Returns:

  • dict: A dictionary unique values of entity as keys and BidsFileDictionary objs as values.

  • dict: A BidsFileDictionary containing the files that don’t have entity in their names.

Return type:

tuple

Notes

  • This function is used for analysis where a single subject or single type of task is being analyzed.

BidsFileDictionary.file_dict

Dictionary of keys and paths.

BidsFileDictionary.file_list

Paths of the files in the list.

BidsFileDictionary.key_list

The dictionary keys.

BidsFileDictionary.name

Name of this dictionary.