mne_bids.BIDSPath¶

class mne_bids.BIDSPath(subject=None, session=None, task=None, acquisition=None, run=None, processing=None, recording=None, space=None, split=None, root=None, suffix=None, extension=None, datatype=None, check=True)[source]¶

A BIDS path object.

BIDS filename prefixes have one or more pieces of metadata in them. They must follow a particular order, which is followed by this function. This will generate the prefix for a BIDS filename that can be used with many subsequent files, or you may also give a suffix that will then complete the file name.

BIDSPath allows dynamic updating of its entities in place, and operates similar to pathlib.Path. In addition, it can query multiple paths with matching BIDS entities via the match method.

Note that not all parameters are applicable to each suffix of data. For example, electrode location TSV files do not need a “task” field.

Parameters

subjectstr | None: The subject ID. Corresponds to “sub”.
sessionstr | None: The session for a item. Corresponds to “ses”.
taskstr | None: The task for a item. Corresponds to “task”.
acquisition: str | None: The acquisition parameters for the item. Corresponds to “acq”.
runint | None: The run number for this item. Corresponds to “run”.
processingstr | None: The processing label for this item. Corresponds to “proc”.
recordingstr | None: The recording name for this item. Corresponds to “rec”.
spacestr | None: The coordinate space for an anatomical file. Corresponds to “space”.
splitint | None: The split of the continuous recording file for .fif data. Corresponds to “split”.
suffixstr | None: The filename suffix. This is the entity after the last _ before the extension. E.g., 'channels'. The following filename suffix’s are accepted: ‘meg’, ‘markers’, ‘eeg’, ‘ieeg’, ‘T1w’, ‘participants’, ‘scans’, ‘electrodes’, ‘coordsystem’, ‘channels’, ‘events’, ‘headshape’, ‘digitizer’, ‘behav’, ‘phsyio’, ‘stim’
extensionstr | None: The extension of the filename. E.g., '.json'.
datatypestr: The “data type” of folder being created at the end of the folder hierarchy. E.g., 'anat', 'func', 'eeg', 'meg', 'ieeg', etc.
rootstr | pathlib.Path | None: The root for the filename to be created. E.g., a path to the folder in which you wish to create a file with this name.
checkbool: If True enforces the entities to be valid according to the current BIDS standard. Defaults to True.

Examples

>>> bids_path = BIDSPath(subject='test', session='two', task='mytask',
                             suffix='ieeg', extension='.edf')
>>> print(bids_path.basename)
sub-test_ses-two_task-mytask_ieeg.edf
>>> bids_path
BIDSPath(root: None,
basename: sub-test_ses-two_task-mytask_ieeg.edf)
>>> # copy and update multiple entities at once
>>> new_bids_path = bids_path.copy().update(subject='test2',
                                               session='one')
>>> print(new_bids_path.basename)
sub-test2_ses-one_task-mytask_ieeg.edf
>>> # printing the BIDSPath will show relative path when
>>> # root is not set
>>> print(new_bids_path)
sub-test2/ses-one/ieeg/sub-test2_ses-one_task-mytask_ieeg.edf
>>> new_bids_path.update(suffix='channels', extension='.tsv')
>>> # setting suffix without an identifiable datatype will
>>> # result in a wildcard at the datatype directory level
>>> print(new_bids_path)
sub-test2/ses-one/*/sub-test2_ses-one_task-mytask_channels.tsv
>>> # set a root for the BIDS dataset
>>> new_bids_path.update(root='/bids_dataset')
>>> print(new_bids_path.root)
/bids_dataset
>>> print(new_bids_path.basename)
sub-test2_ses-one_task-mytask_ieeg.edf
>>> print(new_bids_path)
/bids_dataset/sub-test2/ses-one/ieeg/sub-test2_ses-one_task-mytask_ieeg.edf
>>> print(new_bids_path.directory)
/bids_dataset/sub-test2/ses-one/ieeg/

Attributes

entitiesdict: Return dictionary of the BIDS entities.
datatypestr | None: The data type, i.e., one of 'meg', 'eeg', 'ieeg', 'anat'.
basenamestr: Path basename.
rootpathlib.Path: The root of the BIDS path.
directorypathlib.Path: Get the BIDS parent directory.
fpathpathlib.Path: Full filepath for this BIDS file.
checkbool: If True, enforces the entities to be valid according to the BIDS specification. The check is performed on instantiation and any update function calls (and may be overridden in the latter).

Methods

`copy`()	Copy the instance.
`find_empty_room`()	Find the corresponding empty-room file of an MEG recording.
`match`()	Get a list of all matching paths in the root directory.
`mkdir`([exist_ok])	Create the directory structure of the BIDS path.
`update`(*[, check])	Update inplace BIDS entity key/value pairs in object.

property basename¶: Path basename.

copy()[source]¶

Copy the instance.

Returns

bidspathinstance of BIDSPath: The copied bidspath.

property directory¶

Get the BIDS parent directory.

If subject, session and datatype are set, then they will be used to construct the directory location. For example, if subject='01', session='02' and datatype='ieeg', then the directory would be:

<root>/sub-01/ses-02/ieeg

Returns

data_pathpathlib.Path: The path of the BIDS directory.

property entities¶: Return dictionary of the BIDS entities.

find_empty_room()[source]¶

Find the corresponding empty-room file of an MEG recording.

This will only work if the .root attribute of the mne_bids.BIDSPath instance has been set.

Returns

BIDSPath | None: The path corresponding to the best-matching empty-room measurement. Returns None if none was found.

property fpath¶

Full filepath for this BIDS file.

Getting the file path consists of the entities passed in and will get the relative (or full if root is passed) path.

Returns

bids_fpathpathlib.Path: Either the relative, or full path to the dataset.

match()[source]¶

Get a list of all matching paths in the root directory.

Performs a recursive search, starting in .root (if set), based on BIDSPath.entities object. Ignores .json files.

Returns

bids_pathslist of BIDSPath: The matching paths.

property meg_calibration_fpath¶

Find the matching Elekta/Neuromag/MEGIN fine-calibration file.

This requires that at least root and subject are set, and that datatype is either 'meg' or None.

Returns

pathpathlib.Path | None: The path of the fine-calibration file, or None if it couldn’t be found.

property meg_crosstalk_fpath¶

Find the matching Elekta/Neuromag/MEGIN crosstalk file.

This requires that at least root and subject are set, and that datatype is either 'meg' or None.

Returns

pathpathlib.Path | None: The path of the crosstalk file, or None if it couldn’t be found.

mkdir(exist_ok=True)[source]¶

Create the directory structure of the BIDS path.

Parameters

exist_okbool: If False, raise an exception if the directory already exists. Otherwise, do nothing (default).

Returns

selfinstance of BIDSPath: The BIDSPath object.

update(*, check=None, **kwargs)[source]¶

Update inplace BIDS entity key/value pairs in object.

run and split are auto-parsed to have two numbers when passed in. For example, if run=1, then it will become run='01'.

Also performs error checks on various entities to adhere to the BIDS specification. Specifically: - suffix should be one of: anat, eeg, ieeg, meg - extension should be one of the accepted file extensions in the file path: .con, .sqd, .fif, .pdf, .ds, .vhdr, .edf, .bdf, .set, .edf, .set, .mef, .nwb - suffix should be one acceptable file suffixes in: meg, markers, eeg, ieeg, T1w, participants, scans, electrodes, channels, coordsystem, events, headshape, digitizer, behav, phsyio, stim

Parameters

checkNone | bool: If a boolean, controls whether to enforce the entities to be valid according to the BIDS specification. This will set the .check attribute accordingly. If None, rely on the existing .check attribute instead, which is set upon BIDSPath instantiation. Defaults to None.
**kwargsdict: It can contain updates for valid BIDS path entities: ‘subject’, ‘session’, ‘task’, ‘acquisition’, ‘processing’, ‘run’, ‘recording’, ‘space’, ‘suffix’ or updates for ‘root’ or ‘datatype’.

Returns

bidspathinstance of BIDSPath: The updated instance of BIDSPath.

Examples

If one creates a bids basename using mne_bids.BIDSPath():

>>> bids_path = BIDSPath(subject='test', session='two',
                             task='mytask', suffix='channels',
                             extension='.tsv')
>>> print(bids_path.basename)
sub-test_ses-two_task-mytask_channels.tsv
>>> # Then, one can update this `BIDSPath` object in place
>>> bids_path.update(acquisition='test', suffix='ieeg',
                     extension='.vhdr', task=None)
>>> print(bids_path.basename)
sub-test_ses-two_acq-test_ieeg.vhdr

mne_bids.BIDSPath¶

Examples using mne_bids.BIDSPath¶

Examples using `mne_bids.BIDSPath`¶