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'), 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 subjectX
.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_key
str
The name of the entity key to search for.
- ignore_subjects
str
| array_like ofstr
|None
Subject(s) to ignore. By default, entities from the
emptyroom
mock-subject are not returned. IfNone
, include all subjects.- ignore_sessions
str
| array_like ofstr
|None
Session(s) to ignore. If
None
, include all sessions.- ignore_tasks
str
| array_like ofstr
|None
Task(s) to ignore. If
None
, include all tasks.- ignore_acquisitions
str
| array_like ofstr
|None
Acquisition(s) to ignore. If
None
, include all acquisitions.- ignore_runs
str
| array_like ofstr
|None
Run(s) to ignore. If
None
, include all runs.- ignore_processings
str
| array_like ofstr
|None
Processing(s) to ignore. If
None
, include all processings.- ignore_spaces
str
| array_like ofstr
|None
Space(s) to ignore. If
None
, include all spaces.- ignore_recordings
str
| array_like ofstr
|None
Recording(s) to ignore. If
None
, include all recordings.- ignore_splits
str
| array_like ofstr
|None
Split(s) to ignore. If
None
, include all splits.- ignore_descriptions
str
| array_like ofstr
|None
Description(s) to ignore. If
None
, include all descriptions.Added in version 0.11.
- ignore_modalities
str
| array_like ofstr
|None
Modalities(s) to ignore. If
None
, include all modalities.- ignore_datatypes
str
| array_like ofstr
|None
Datatype(s) to ignore. If
None
, include all datatypes (i.e.anat
,ieeg
,eeg
,meg
,func
, etc.)- ignore_dirs
str
| array_like ofstr
|None
Directories nested directly within
root
to ignore. IfNone
, include all directories in the search.Added in version 0.9.
- with_key
bool
If
True
, returns the full entity with the key and the value. This will for example look like['sub-001', 'sub-002']
. IfFalse
(default), just returns the entity values. This will for example look like['001', '002']
.- verbose
bool
|str
|int
|None
Control verbosity of the logging output. If
None
, use the default verbosity level. See the logging documentation andmne.verbose()
for details. Should only be passed as a keyword argument.
- Returns:
Notes
This function will scan the entire
root
, except for aderivatives
subfolder placed directly underroot
.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']