Skip to main content

BIDSPath

Namespace: BIDSLIB  ·  Library: BIDS Library

Python equivalent

mne_bids.BIDSPath in MNE-Python.

#include <bids/bids_path.h>

class BIDSLIB::BIDSPath

Manages BIDS-compliant file paths.

A BIDSPath encodes the BIDS entities (subject, session, task, acquisition, run, etc.) together with a datatype, suffix, extension, and root directory to produce fully qualified file paths that conform to the BIDS specification.

BIDS-compliant path and filename construction.

src/examples/ex_bids/main.cpp
BIDSPath ieeg(root, "01", "01", "rest", "ieeg", "ieeg", ".vhdr"); // root, sub, ses, task, datatype, suffix, ext
const QString vhdr = ieeg.filePath();                             // <root>/sub-01/ses-01/ieeg/sub-01_ses-01_task-rest_ieeg.vhdr
const QString channelsTsv = ieeg.channelsTsvPath().filePath();    // sibling sidecars share the entities

Public Methods​

BIDSPath()​

Constructs an empty BIDSPath.

BIDSPath(sRoot, sSubject, sSession, sTask, sDatatype, sSuffix, sExtension)​

Constructs a BIDSPath with the most common entities.

Parameters:

  • sRoot : const QString & Root directory of the BIDS dataset.

  • sSubject : const QString & Subject label (without "sub-" prefix).

  • sSession : const QString & Session label (without "ses-" prefix). Can be empty.

  • sTask : const QString & Task label. Can be empty.

  • sDatatype : const QString & BIDS datatype (e.g. "ieeg", "eeg", "meg", "anat").

  • sSuffix : const QString & Filename suffix (e.g. "ieeg", "channels", "electrodes").

  • sExtension : const QString & File extension including dot (e.g. ".vhdr", ".tsv", ".json").

BIDSPath(other)​

Copy constructor.

Parameters:

  • other : const BIDSPath & BIDSPath to copy.

~BIDSPath()​

Destructor.

setRoot(sRoot)​

Set the BIDS dataset root directory.

Parameters:

  • sRoot : const QString & Root directory of the BIDS dataset.

setSubject(sSubject)​

Set the subject label (without "sub-" prefix).

Parameters:

  • sSubject : const QString & Subject label without the "sub-" prefix.

setSession(sSession)​

Set the session label (without "ses-" prefix).

Parameters:

  • sSession : const QString & Session label without the "ses-" prefix; empty to omit the entity.

setTask(sTask)​

Set the task label.

Parameters:

  • sTask : const QString & Task label; empty to omit the entity.

setAcquisition(sAcquisition)​

Set the acquisition label.

Parameters:

  • sAcquisition : const QString & Acquisition label; empty to omit the entity.

setRun(sRun)​

Set the run index (will be zero-padded to 2 digits).

Parameters:

  • sRun : const QString & Run index as a numeric string (e.g. "1" becomes "01"); empty to omit the entity.

setProcessing(sProcessing)​

Set the processing label.

Parameters:

  • sProcessing : const QString & Processing label; empty to omit the entity.

setSpace(sSpace)​

Set the space label.

Parameters:

  • sSpace : const QString & Space label (e.g. a coordinate system name); empty to omit the entity.

setRecording(sRecording)​

Set the recording label.

Parameters:

  • sRecording : const QString & Recording label; empty to omit the entity.

setSplit(sSplit)​

Set the split index.

Parameters:

  • sSplit : const QString & Split index as a numeric string, zero-padded to 2 digits; empty to omit the entity.

setDescription(sDescription)​

Set the description label.

Parameters:

  • sDescription : const QString & Description label; empty to omit the entity.

setDatatype(sDatatype)​

Set the BIDS datatype (e.g.

"ieeg", "eeg", "meg", "anat").

Parameters:

  • sDatatype : const QString & BIDS datatype, used as the innermost directory name.

setSuffix(sSuffix)​

Set the filename suffix (e.g.

"ieeg", "channels", "electrodes", "coordsystem").

Parameters:

  • sSuffix : const QString & Filename suffix appended after the entities.

setExtension(sExtension)​

Set the file extension including dot (e.g.

".vhdr", ".tsv", ".json").

Parameters:

  • sExtension : const QString & File extension including the leading dot.

root()​

BIDS dataset root path.

Returns:

  • QString — Root directory of the BIDS dataset, or an empty string if unset.

subject()​

Subject label (without "sub-").

Returns:

  • QString — Subject label without the "sub-" prefix, or an empty string if unset.

session()​

Session label (without "ses-").

Returns:

  • QString — Session label without the "ses-" prefix, or an empty string if unset.

task()​

Task label.

Returns:

  • QString — Task label, or an empty string if unset.

acquisition()​

Acquisition label.

Returns:

  • QString — Acquisition label, or an empty string if unset.

run()​

Run index.

Returns:

  • QString — Zero-padded run index, or an empty string if unset.

processing()​

Processing label.

Returns:

  • QString — Processing label, or an empty string if unset.

space()​

Space label.

Returns:

  • QString — Space label, or an empty string if unset.

recording()​

Recording label.

Returns:

  • QString — Recording label, or an empty string if unset.

split()​

Split index.

Returns:

  • QString — Zero-padded split index, or an empty string if unset.

description()​

Description label.

Returns:

  • QString — Description label, or an empty string if unset.

datatype()​

BIDS datatype string.

Returns:

  • QString — BIDS datatype (e.g. "ieeg"), or an empty string if unset.

suffix()​

Filename suffix.

Returns:

  • QString — Filename suffix, or an empty string if unset.

extension()​

File extension.

Returns:

  • QString — File extension including the leading dot, or an empty string if unset.

basename()​

Constructs the BIDS-compliant filename (without directory).

Format: sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_run-<index>] [_proc-<label>][_space-<label>][_recording-<label>][_split-<index>] [_desc-<label>]_<suffix><extension>

Returns:

  • QString — The BIDS filename.

directory()​

Constructs the directory path for this entity combination.

Format: <root>/sub-<label>[/ses-<label>]/<datatype>/

Returns:

  • QString — The BIDS directory path (with trailing separator).

filePath()​

Constructs the full file path: directory() + basename().

Returns:

  • QString — The complete file path.

withSuffix(sSuffix, sExtension)​

Returns a copy of this BIDSPath with updated suffix and extension.

Useful for deriving sidecar paths from a data path.

Parameters:

  • sSuffix : const QString & New suffix (e.g. "channels", "electrodes", "coordsystem").

  • sExtension : const QString & New extension (e.g. ".tsv", ".json").

Returns:

channelsTsvPath()​

Returns the path for the channels.tsv sidecar.

Returns:

electrodesTsvPath()​

Returns the path for the electrodes.tsv sidecar.

Returns:

coordsystemJsonPath()​

Returns the path for the coordsystem.json sidecar.

Returns:

eventsTsvPath()​

Returns the path for the events.tsv sidecar.

Returns:

sidecarJsonPath()​

Returns the path for the sidecar JSON metadata file (e.g.

*_ieeg.json, *_eeg.json).

Returns:

exists()​

Checks whether the file at filePath() exists on disk.

Returns:

  • bool — true if the file exists.

mkdirs()​

Creates the directory structure for this path (mkdir -p).

Returns:

  • bool — true if the directory exists or was created successfully.

match()​

Searches the BIDS root (all subject, session and datatype folders) for files whose entities, datatype, suffix and extension equal the ones set here; unset ones match anything, as in mne_bids.BIDSPath.match.

Returns:

  • QList< BIDSPath > — Matching paths, sorted by file path.

operator=(other)​

Static Methods​

isValidEntityValue(sValue)​

Validates entity values (no forbidden characters: -, _, /).

Parameters:

  • sValue : const QString & Entity value to validate.

Returns:

  • bool — true if the value is valid.

Example​

Used in examples​

ex_bids​

BIDS library: paths, sidecar TSVs, BrainVision/EDF readers and a raw-data round trip.

src/examples/ex_bids/main.cpp, line 93
BIDSPath ieeg(root, "01", "01", "rest", "ieeg", "ieeg", ".vhdr"); // root, sub, ses, task, datatype, suffix, ext
const QString vhdr = ieeg.filePath();                             // <root>/sub-01/ses-01/ieeg/sub-01_ses-01_task-rest_ieeg.vhdr
const QString channelsTsv = ieeg.channelsTsvPath().filePath();    // sibling sidecars share the entities
ok &= expect(ieeg.exists() && ieeg.basename() == "sub-01_ses-01_task-rest_ieeg.vhdr" && channelsTsv.endsWith("sub-01_ses-01_task-rest_channels.tsv"),
             "BIDSPath builds the entity filename and its channels.tsv sidecar");

Authors of this file​