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.