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, description=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 acquisition session. Corresponds to “ses”.

taskstr | None

The experimental task. Corresponds to “task”.

acquisition: str | None

The acquisition parameters. Corresponds to “acq”.

runint | None

The run number. Corresponds to “run”.

processingstr | None

The processing label. Corresponds to “proc”.

recordingstr | None

The recording name. Corresponds to “rec”.

spacestr | None

The coordinate space for anatomical and sensor location files (e.g., *_electrodes.tsv, *_markers.mrk). Corresponds to “space”. Note that valid values for space must come from a list of BIDS keywords as described in the BIDS specification.

splitint | None

The split of the continuous recording file for .fif data. Corresponds to “split”.

descriptionstr | None

This corresponds to the BIDS entity desc. It is used to provide additional information for derivative data, e.g., preprocessed data may be assigned description='cleaned'.

Added in version 0.11.

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’, ‘beh’, ‘physio’, ‘stim’

extensionstr | None

The extension of the filename. E.g., '.json'.

datatypestr

The BIDS data type, e.g., 'anat', 'func', 'eeg', 'meg', 'ieeg'.

rootpath-like | None

The root directory of the BIDS dataset.

checkbool

If True, enforces BIDS conformity. Defaults to True.

Attributes:
entitiesdict

Return dictionary of the BIDS entities.

datatypestr | None

The BIDS data type, e.g.

basenamestr

Path basename.

rootpathlib.Path

The root directory of the BIDS dataset.

directorypathlib.Path

Get the BIDS parent directory.

fpathpathlib.Path

Full filepath for this BIDS file.

checkbool

Whether to enforce BIDS conformity.

Methods

copy()

Copy the instance.

find_empty_room([use_sidecar_only, verbose])

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

find_matching_sidecar([suffix, extension, ...])

Get the matching sidecar JSON path.

get_empty_room_candidates()

Get the list of empty-room candidates for the given file.

match(*[, ignore_json, ignore_nosub, check])

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

mkdir([exist_ok])

Create the directory structure of the BIDS path.

rm(*[, safe_remove, verbose])

Safely delete a set of files from a BIDS dataset.

update(*[, check])

Update inplace BIDS entity key/value pairs in object.

Notes

BIDS entities are generally separated with a "_" character, while entity key/value pairs are separated with a "-" character. There are checks performed to make sure that there are no '-', '_', or '/' characters contained in any entity keys or values.

To represent a filename such as dataset_description.json, one can set check=False, and pass suffix='dataset_description' and extension='.json'.

BIDSPath can also be used to represent file and folder names of data types that are not yet supported through MNE-BIDS, but are recognized by BIDS. For example, one can set datatype to dwi or func and pass check=False to represent diffusion-weighted imaging and functional MRI paths.

Examples

Generate a BIDSPath object and inspect it

>>> bids_path = BIDSPath(subject='test', session='two', task='mytask',
...                      suffix='ieeg', extension='.edf', datatype='ieeg')
>>> print(bids_path.basename)
sub-test_ses-two_task-mytask_ieeg.edf
>>> bids_path
BIDSPath(
root: None
datatype: ieeg
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 a BIDSPath will show a relative path when root is not set

>>> print(new_bids_path)
sub-test2/ses-one/ieeg/sub-test2_ses-one_task-mytask_ieeg.edf

Setting suffix without an identifiable datatype will make BIDSPath try to guess the datatype

>>> new_bids_path = new_bids_path.update(suffix='channels',
...                                      extension='.tsv')
>>> print(new_bids_path)
sub-test2/ses-one/ieeg/sub-test2_ses-one_task-mytask_channels.tsv

You can set a new root for the BIDS dataset. Let’s see what the different properties look like for our object:

>>> new_bids_path = new_bids_path.update(root='/bids_dataset')
>>> print(new_bids_path.root.as_posix())
/bids_dataset
>>> print(new_bids_path.basename)
sub-test2_ses-one_task-mytask_channels.tsv
>>> print(new_bids_path)
/bids_dataset/sub-test2/ses-one/ieeg/sub-test2_ses-one_task-mytask_channels.tsv
>>> print(new_bids_path.directory.as_posix())
/bids_dataset/sub-test2/ses-one/ieeg
__hash__ = None#
property acquisition: str | None#

The acquisition parameters.

property basename#

Path basename.

copy()[source]#

Copy the instance.

Returns:
bidspathBIDSPath

The copied bidspath.

property datatype: str | None#

The BIDS data type, e.g. 'anat', 'meg', 'eeg'.

property description: str | None#

The description entity.

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.

property extension: str | None#

The extension of the filename, including a leading period.

find_empty_room(use_sidecar_only=False, *, verbose=None)[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.

Parameters:
use_sidecar_onlybool

Whether to only check the AssociatedEmptyRoom entry in the sidecar JSON file or not. If False, first look for the entry, and if unsuccessful, try to find the best-matching empty-room recording in the dataset based on the measurement date.

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:
BIDSPath | None

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

find_matching_sidecar(suffix=None, extension=None, *, on_error='raise')[source]#

Get the matching sidecar JSON path.

Parameters:
suffixstr | None

The filename suffix. This is the entity after the last _ before the extension. E.g., 'ieeg'.

extensionstr | None

The extension of the filename. E.g., '.json'.

on_error‘raise’ | ‘warn’ | ‘ignore’

If no matching sidecar file was found and this is set to 'raise', raise a RuntimeError. If 'warn', emit a warning, and if 'ignore', neither raise an exception nor a warning, and return None in both cases.

Returns:
sidecar_pathpathlib.Path | None

The path to the sidecar JSON file.

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.

get_empty_room_candidates()[source]#

Get the list of empty-room candidates for the given file.

Returns:
candidateslist of BIDSPath

The candidate files that will be checked if the sidecar does not contain an “AssociatedEmptyRoom” entry.

Notes

Added in version 0.12.0.

match(*, ignore_json=True, ignore_nosub=False, check=False)[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.

Parameters:
ignore_jsonbool

If True, ignores json files. Defaults to True.

ignore_nosubbool

If True, ignores all files that are not of the form root/sub-*. Defaults to False.

checkbool

If True, only returns paths that conform to BIDS. If False (default), the .check attribute of the returned mne_bids.BIDSPath object will be set to True for paths that do conform to BIDS, and to False for those that don’t.

Returns:
bids_pathslist of mne_bids.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:
selfBIDSPath

The BIDSPath object.

property processing: str | None#

The processing label.

property recording: str | None#

The recording name.

rm(*, safe_remove=True, verbose=None)[source]#

Safely delete a set of files from a BIDS dataset.

Deleting a scan that conforms to the bids-validator will remove the respective row in *_scans.tsv, the corresponding sidecar files, and the data file itself.

Deleting all files of a subject will update the *_participants.tsv file.

Parameters:
safe_removebool

If False, directly delete and update the files. Otherwise, displays the list of operations planned and asks for user confirmation before executing them (default).

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:
selfBIDSPath

The BIDSPath object.

Examples

Remove one specific run:

>>> bids_path = BIDSPath(subject='01', session='01', run="01",  
...                      root='/bids_dataset').rm()  
Please, confirm you want to execute the following operations:
Delete:
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-01_channels.tsv
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-01_events.json
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-01_events.tsv
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-01_meg.fif
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-01_meg.json
Update:
/bids_dataset/sub-01/ses-01/sub-01_ses-01_scans.tsv
I confirm [y/N]>? y

Remove all the files of a specific subject:

>>> bids_path = BIDSPath(subject='01', root='/bids_dataset',  
...                      check=False).rm()  
Please, confirm you want to execute the following operations:
Delete:
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_acq-calibration_meg.dat
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_acq-crosstalk_meg.fif
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_coordsystem.json
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-02_channels.tsv
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-02_events.json
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-02_events.tsv
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-02_meg.fif
/bids_dataset/sub-01/ses-01/meg/sub-01_ses-01_run-02_meg.json
/bids_dataset/sub-01/ses-01/sub-01_ses-01_scans.tsv
/bids_dataset/sub-01
Update:
/bids_dataset/participants.tsv
I confirm [y/N]>? y
property root: Path | None#

The root directory of the BIDS dataset.

property run: str | None#

The run number.

property session: str | None#

The acquisition session.

property space: str | None#

The coordinate space for an anatomical or sensor position file.

property split: str | None#

The split of the continuous recording file for .fif data.

property subject: str | None#

The subject ID.

property suffix: str | None#

The filename suffix.

property task: str | None#

The experimental task.

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

Update inplace BIDS entity key/value pairs in object.

run and split are auto-converted to have two digits. For example, if run=1, then it will nbecome run='01'.

Also performs error checks on various entities to adhere to the BIDS specification. Specifically: - datatype 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 of the acceptable file suffixes in: meg, markers, eeg, ieeg, T1w, participants, scans, electrodes, channels, coordsystem, events, headshape, digitizer, beh, physio, stim - Depending on the modality of the data (EEG, MEG, iEEG), space should be a valid string according to Appendix VIII in the BIDS specification.

Parameters:
checkNone | bool

If a boolean, controls whether to enforce BIDS conformity. This will set the .check attribute accordingly. If None, rely on the existing .check attribute instead, which is set upon mne_bids.BIDSPath instantiation. Defaults to None.

**kwargsdict

It can contain updates for valid BIDSPath entities: ‘subject’, ‘session’, ‘task’, ‘acquisition’, ‘processing’, ‘run’, ‘recording’, ‘space’, ‘suffix’, ‘split’, ‘extension’, or updates for ‘root’ or ‘datatype’.

Returns:
bidspathBIDSPath

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',
...                  datatype='ieeg',
...                  extension='.vhdr', task=None)
BIDSPath(
root: None
datatype: ieeg
basename: sub-test_ses-two_acq-test_ieeg.vhdr)
>>> print(bids_path.basename)
sub-test_ses-two_acq-test_ieeg.vhdr

Examples using mne_bids.BIDSPath#

01. Read BIDS datasets

01. Read BIDS datasets

02. Convert MNE sample data to BIDS format

02. Convert MNE sample data to BIDS format

03. Interactive data inspection and bad channel selection

03. Interactive data inspection and bad channel selection

04. Convert EEG data to BIDS format

04. Convert EEG data to BIDS format

05. BIDS conversion for group studies

05. BIDS conversion for group studies

07. Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS

07. Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS

08. Convert iEEG data to BIDS format

08. Convert iEEG data to BIDS format

09. Manually storing empty room data

09. Manually storing empty room data

10. An introduction to BIDSPath

10. An introduction to BIDSPath

11. Creating BIDS-compatible folder names and filenames

11. Creating BIDS-compatible folder names and filenames

12. Updating BIDS datasets

12. Updating BIDS datasets

13. Anonymizing a BIDS dataset

13. Anonymizing a BIDS dataset

13. Convert NIRS data to BIDS format

13. Convert NIRS data to BIDS format