mne_bids.get_entity_vals

mne_bids.get_entity_vals(root, entity_key, *, ignore_subjects='emptyroom', ignore_sessions=None, ignore_tasks=None, ignore_runs=None, ignore_processings=None, ignore_spaces=None, ignore_acquisitions=None, ignore_splits=None, ignore_modalities=None, ignore_datatypes=None, ignore_dirs=('derivatives', 'sourcedata'), with_key=False, verbose=None)

Get list of values associated with an entity_key in a BIDS dataset.

BIDS file names are organized by key-value pairs called “entities” [1]. With this function, you can get all values for an entity indexed by its key.

Parameters

rootpath-like

Path to the “root” directory from which to start traversing to gather BIDS entities from file- and folder names. This will commonly be the BIDS root, but it may also be a subdirectory inside of a BIDS dataset, e.g., the sub-X directory of a hypothetical subject X.

Note

This function searches the names of all files and directories nested within root. Depending on the size of your dataset and storage system, searching the entire BIDS dataset may take a considerable amount of time (seconds up to several minutes). If you find yourself running into such performance issues, consider limiting the search to only a subdirectory in the dataset, e.g., to a single subject or session only.

entity_keystr

The name of the entity key to search for.

ignore_subjectsstr | array-like of str | None

Subject(s) to ignore. By default, entities from the emptyroom mock-subject are not returned. If None, include all subjects.

ignore_sessionsstr | array-like of str | None

Session(s) to ignore. If None, include all sessions.

ignore_tasksstr | array-like of str | None

Task(s) to ignore. If None, include all tasks.

ignore_runsstr | array-like of str | None

Run(s) to ignore. If None, include all runs.

ignore_processingsstr | array-like of str | None

Processing(s) to ignore. If None, include all processings.

ignore_spacesstr | array-like of str | None

Space(s) to ignore. If None, include all spaces.

ignore_acquisitionsstr | array-like of str | None

Acquisition(s) to ignore. If None, include all acquisitions.

ignore_splitsstr | array-like of str | None

Split(s) to ignore. If None, include all splits.

ignore_modalitiesstr | array-like of str | None

Modalities(s) to ignore. If None, include all modalities.

ignore_datatypesstr | array-like of str | None

Datatype(s) to ignore. If None, include all datatypes (i.e. anat, ieeg, eeg, meg, func, etc.)

ignore_dirsstr | array-like of str | None

Directories nested directly within root to ignore. If None, include all directories in the search.

New in version 0.9.

with_keybool

If True, returns the full entity with the key and the value. This will for example look like ['sub-001', 'sub-002']. If False (default), just returns the entity values. This will for example look like ['001', '002'].

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns

entity_valslist of str

List of the values associated with an entity_key in the BIDS dataset pointed to by root.

Notes

This function will scan the entire root, except for a derivatives subfolder placed directly under root.

References

1

https://bids-specification.rtfd.io/en/latest/02-common-principles.html#file-name-structure # noqa: E501

Examples

>>> root = Path('./mne_bids/tests/data/tiny_bids').absolute()
>>> entity_key = 'subject'
>>> get_entity_vals(root, entity_key)
['01']
>>> get_entity_vals(root, entity_key, with_key=True)
['sub-01']

previous

mne_bids.get_entities_from_fname

next

mne_bids.get_datatypes