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, with_key=False)[source]

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
rootstr | pathlib.Path

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 | iterable | None

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

ignore_sessionsstr | iterable | None

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

ignore_tasksstr | iterable | None

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

ignore_runsstr | iterable | None

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

ignore_processingsstr | iterable | None

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

ignore_spacesstr | iterable | None

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

ignore_acquisitionsstr | iterable | None

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

ignore_splitsstr | iterable | None

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

ignore_modalitiesstr | iterable | None

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

ignore_datatypesstr | iterable | None

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

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'].

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']

Examples using mne_bids.get_entity_vals

mne_bids.get_entities_from_fname mne_bids.get_datatypes