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.