mne_bids.get_entity_vals#

mne_bids.get_entity_vals(root, entity_key, *, ignore_subjects='emptyroom', ignore_sessions=None, ignore_tasks=None, ignore_acquisitions=None, ignore_runs=None, ignore_processings=None, ignore_spaces=None, ignore_recordings=None, ignore_splits=None, ignore_descriptions=None, ignore_modalities=None, ignore_datatypes=None, ignore_dirs=('derivatives', 'sourcedata'), ignore_suffixes=None, include_match=None, with_key=False, verbose=None)[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:
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_acquisitionsstr | array_like of str | None

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

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_recordingsstr | array_like of str | None

Recording(s) to ignore. If None, include all recordings.

ignore_splitsstr | array_like of str | None

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

ignore_descriptionsstr | array_like of str | None

Description(s) to ignore. If None, include all descriptions.

Added in version 0.11.

ignore_modalitiesstr | array_like of str | None

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

Added in version 0.9.

ignore_suffixesstr | array_like of str | None

Suffixes to ignore. If None, include all suffixes. This can be helpful for ignoring non-data sidecars such as *_scans.tsv or *_coordsystem.json.

Added in version 0.17.

include_matchstr | array_like of str | None

Glob-style pattern(s) of directories to include in the search (i.e., each must end with "/"). None (the default) is equivalent to "**/" (search within any subdirectory of the BIDS root).

Added in version 0.17.

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

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#

Read BIDS datasets

Read BIDS datasets