BidsTabularDictionary¶

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

A dictionary of tabular files keyed to BIDS entities.

column_dict

Dictionary with an entity key and a list of column names for the file as the value.

Type:: dict

rowcount_dict

Dictionary with an entity key and a count of number of rows for the file as the value.

Type:: dict

Methods

`BidsTabularDictionary.__init__`(...[, entities])	Create a dictionary of full paths.
`BidsTabularDictionary.count_diffs`(other_dict)	Return keys in which the number of rows differ.
`BidsTabularDictionary.create_file_dict`(...)	Create new dict based on key indices.
`BidsTabularDictionary.get_file_path`(key)	Return the file path corresponding to key.
`BidsTabularDictionary.get_info`(key)	Return a dict with key, row count, and column count.
`BidsTabularDictionary.get_new_dict`(name, files)	Create a new BidsTabularDictionary.
`BidsTabularDictionary.iter_files`()	Iterator over the files in this dictionary.
`BidsTabularDictionary.key_diffs`(other_dict)	Return the symmetric key difference with another file dictionary.
`BidsTabularDictionary.make_dict`(files, entities)	Make a dictionary from files or a dict.
`BidsTabularDictionary.make_file_dict`(file_list)	Return a dictionary of files using entity keys.
`BidsTabularDictionary.make_key`(key_string[, ...])	Create a key from specified entities.
`BidsTabularDictionary.make_new`(name, files)	Create a dictionary with these files.
`BidsTabularDictionary.make_query`([query_dict])	Return a dictionary of files matching query.
`BidsTabularDictionary.match_query`(...)	Return True if query has a match in dictionary.
`BidsTabularDictionary.output_files`([title, ...])	Return a string with the output of the list.
`BidsTabularDictionary.report_diffs`(tsv_dict)	Reports and logs the contents and differences between this tabular dictionary and another.
`BidsTabularDictionary.set_tsv_info`()
`BidsTabularDictionary.split_by_entity`(entity)	Split this dictionary based on an entity.

Attributes

`BidsTabularDictionary.file_dict`	Dictionary of keys and paths.
`BidsTabularDictionary.file_list`	Paths of the files in the list.
`BidsTabularDictionary.key_list`	The dictionary keys.
`BidsTabularDictionary.name`	Name of this dictionary.

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

Create a dictionary of full paths.

Parameters:

collection_name (str) – Name of the collection.
files (list, dict) – Contains the full paths or BidsFile representation of files of interest.
entities (tuple) – List of indices into base file names of pieces to assemble for the key.

Notes

Used for cross listing BIDS style files for different studies.

BidsTabularDictionary.count_diffs(other_dict)[source]¶

Return keys in which the number of rows differ.

Parameters:: other_dict (FileDictionary) – A file dictionary object.
Returns:: A list containing 3-element tuples.
Return type:: list

Notes

The returned tuples consist of
- str: The key representing the file.
- int: Number of rows in the file in this dictionary.
- int: Number of rows in the file in the other dictionary.

BidsTabularDictionary.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.

BidsTabularDictionary.get_file_path(key)¶

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.

BidsTabularDictionary.get_info(key)[source]¶

Return a dict with key, row count, and column count.

Parameters:: key (str) – The key for file whose information is to be returned.
Returns:: A dictionary with key, row_count, and columns entries.
Return type:: dict

BidsTabularDictionary.get_new_dict(name, files)[source]¶

Create a new BidsTabularDictionary.

Parameters:

name (str) – Name of the new object.
files (list, dict) – List or dictionary specifying the files to include.

Returns:

The object contains just the specified files.

Return type:

BidsTabularDictionary

Notes

The created object uses the entities from this object

BidsTabularDictionary.iter_files()[source]¶

Iterator over the files in this dictionary.

Yields:: tuple – - str: The next key. - BidsTabularFile: The next object. - int: Number of rows. - list: List of column names.

BidsTabularDictionary.key_diffs(other_dict)¶

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

BidsTabularDictionary.make_dict(files, entities)¶

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 BidsTabularDictionary.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 BidsTabularDictionary.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

BidsTabularDictionary.make_new(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:

BidsTabularDictionary

BidsTabularDictionary.make_query(query_dict={'sub': '*'})¶

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 BidsTabularDictionary.match_query(query_dict, entity_dict)¶

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.

BidsTabularDictionary.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.

BidsTabularDictionary.report_diffs(tsv_dict, logger=None)[source]¶

Reports and logs the contents and differences between this tabular dictionary and another.

Parameters:

tsv_dict (BidsTabularDictionary) – A dictionary representing BIDS-keyed tsv files.
logger (HedLogger) – A HedLogger object for reporting the values by key.

Returns:

A string with the differences.

Return type:

str

BidsTabularDictionary.set_tsv_info()[source]¶

BidsTabularDictionary.split_by_entity(entity)¶

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.

BidsTabularDictionary.file_dict¶: Dictionary of keys and paths.

BidsTabularDictionary.file_list¶: Paths of the files in the list.

BidsTabularDictionary.key_list¶: The dictionary keys.

BidsTabularDictionary.name¶: Name of this dictionary.