Tutorial

Walk the BIDS Manager GUI and CLI workflow on real data.

One end-to-end walkthrough. You'll watch the GUI step through scanning, curating, converting, enriching and validating a real MRI dataset, then see the same four stages run from the command line. Step at your own pace, or download one of the four sample datasets and follow along on your own machine.

CLI reference

Every command, every flag.

BIDS Manager ships seven console scripts plus the GUI entry. Every verb accepts -v for INFO logging and -vv for DEBUG. Synopses below mirror what --help prints on a fresh install of bids-manager on PyPI. The project-first verbs (bidsmgr-create, bidsmgr-project) and the --project flag are additive: every classic positional form still works.

bidsmgr-create

Creates and scaffolds a BIDS dataset workspace (or adopts an existing BIDS folder). Writes dataset_description.json, a README, and a .bidsignore, and initialises the project bundle. The folder name is the dataset slug the other verbs use.

bidsmgr-create <output_dir> [options]

Positional arguments

output_dir

Dataset folder to create or adopt.

Options

--name NAME

Human-readable dataset Name for dataset_description.json (defaults to the folder name).

--description TEXT

Optional project description recorded in the project bundle.

bidsmgr-scan

Walks a raw input folder, reads metadata from inside every file (DICOM tags, EDF / FIF headers), classifies each series with the schema-driven chain, and writes a single inventory TSV with one row per series plus an entities JSON column carrying the BidsGuess. With --project the inventory is saved as a versioned, resumable scan inside the project instead of a loose TSV.

bidsmgr-scan <dicom_root> [<output_tsv>] [options]

Positional arguments

dicom_root

Directory containing the raw recordings (any depth). DICOM, EDF, BDF, BrainVision, FIF, CTF, EEG / MEG, and Siemens CMRR physio are all detected automatically.

output_tsv

Destination path for the inventory TSV. Omit when using --project.

Options

--project DIR

Scan into a project dataset folder (created by bidsmgr-create or the GUI; created / adopted if absent). The inventory is saved as a new versioned scan under <project>/.bidsmgr/project/scans/, so it is resumable in the GUI and never overwrites an earlier scan. --dataset defaults to the project folder name.

--jobs N, -j N

Parallel worker threads used to read file headers. Defaults to 80% of the host CPU count.

--probe-convert

After the metadata walk, run dcm2niix as a probe on every DICOM series (one invocation per SeriesInstanceUID) into a hidden staging tree, harvest what was produced, then remove it. Adds probe_n_files / probe_n_nifti / probe_n_volumes / probe_extensions columns and surfaces conversion anomalies in proposed_issues. The staging tree is always removed, including on error. Slow but most accurate.

--no-bids-guess

Skip the dcm2niix BidsGuess classifier and fall back to the legacy regex-only layer. For comparison / debug.

--dataset NAME

BIDS dataset slug stamped into every row's dataset column. The converter writes each distinct value to <bids_parent>/<dataset>/. Defaults to a slugified form of the raw root's folder name.

--line-freq HZ

EEG / MEG only. Power-line frequency in Hz, stamped into every EEG / MEG row's line_freq column (goes into PowerLineFrequency in the sidecar). Typical values: 50 (most of the world), 60 (Americas / parts of Asia). Per-row TSV value wins.

--montage NAME

EEG / MEG only. Name of a built-in mne montage (e.g. standard_1005, biosemi64) stamped into every EEG / MEG row's montage column. The converter applies it before write_raw_bids, filling electrodes.tsv + coordsystem.json. Per-row TSV value wins.

--rules-file JSON

Path to a JSON file of user scan rules: classifier hints (extend the classifier) and series exclusions (mark matching series include=0), matched by sequence name or path. The same schema the GUI Settings Scan rules tab persists.

bidsmgr-rebuild

Reconciles the inventory TSV's entities JSON column with its derived display cells (proposed_basename, session, task, run). bidsmgr-convert runs this automatically in memory before reading rows, so manual calls are mostly for diff-style preview.

bidsmgr-rebuild <tsv> [options]

Positional arguments

tsv

Inventory TSV produced by bidsmgr-scan.

Options

--from {entities,columns}

Source of truth for this rebuild. Default entities regenerates the display cells from the entities JSON; columns does the reverse (use after editing task / run / session cells in a spreadsheet).

--dry-run

Print the diff but don't write the TSV back.

bidsmgr-convert

Reads the inventory and converts every keeper row to BIDS using the right backend per modality (dcm2niix for DICOM, mne-bids for EEG / MEG / iEEG, bidsphysio for Siemens CMRR physio). Stages each subject privately, then atomic-renames into the BIDS root. Re-running merges new subjects and sessions in safely. With --project it converts the project's active scan version into its locked root, replaying the curation edits recorded in the GUI.

bidsmgr-convert [<tsv>] [<bids_parent>] [options]

Positional arguments

tsv

Inventory TSV produced by bidsmgr-scan. Omit when using --project.

bids_parent

Parent directory; each distinct dataset value becomes a sibling BIDS root underneath. Omit when using --project (output is the project).

Options

--project DIR

Convert the project dataset's active (latest) scan version into its locked root. Resolves the inventory, output, and recording metadata from <project>/.bidsmgr/project, replaying the GUI curation edits. Supersedes the positionals.

--version ID

With --project, convert a specific scan version instead of the latest (version id or index; see bidsmgr-project).

--dataset NAME

Limit conversion to rows whose dataset cell equals this value.

--jobs N, -j N

Number of backend invocations to run in parallel. Defaults to 80% of the host CPU count.

--on-existing {skip,update,replace,error}

Policy when an incoming subject already exists on disk. New sessions and datatypes always merge in; this governs colliding files: skip keep existing (default), update replace only changed files, replace back up + replace colliding files, error abort the subject if anything would collide.

--overwrite

Alias for --on-existing replace.

--recording-meta PATH

EEG / MEG enrichment JSON. Its dataset defaults supply line_freq / montage for blank inventory cells, and its richer fields fill the sidecar reference / ground / filters / device / institution, retype auxiliary channels, and map event codes to labels. Optional; omitting it leaves PowerLineFrequency=50 by default.

--force-edf

Re-encode EEG / iEEG recordings to EDF on write instead of keeping the source format. Harmonises a study to one BIDS-native format and makes a non-BIDS-native but mne-readable source convertible. MEG / NIRS are unaffected.

--keep-residuals

Keep dcm2niix residual / secondary outputs. By default the converter drops the derived single-volume duplicates dcm2niix splits off one input series (e.g. ..._bolda alongside ..._bold), which have no valid BIDS suffix.

--raw-root PATH

Folder the original scan was run against. Used as the first candidate when resolving EEG / MEG rows' relative source_file paths. If omitted, the TSV's parent directory is tried.

--dcm2niix PATH

Override the default dcm2niix binary. Defaults to the one bundled with the bids-manager wheel.

--dry-run

Print the per-row conversion plan; write nothing.

bidsmgr-metadata

Post-conversion metadata engine. Walks a BIDS root and fills every required field the schema can infer (Manufacturer, MagneticFieldStrength, EchoTime, RepetitionTime, etc.) from the converted files. Writes dataset_description.json, enriches every sidecar (including participants.tsv demographics and optional phenotype tables), and leaves a metadata_report.json audit log.

bidsmgr-metadata [<target>] [options]

Positional arguments

target

BIDS root, or a parent containing one or more BIDS roots (the parent form is what bidsmgr-convert writes into). Omit when using --project.

Options

--project DIR

Run on a project dataset folder: the target is the project root and the inventory is resolved from its active scan version (so demographics / phenotype / participants flow through). Supersedes the positional target.

--version ID

With --project, take the inventory from a specific scan version instead of the latest.

--dataset NAME

When target is a parent, limit the run to this single dataset name.

--inventory-tsv PATH

Inventory TSV produced by bidsmgr-scan. Used to enrich participants.tsv with demographics; without it those columns default to n/a.

--participants PATH

Participants spreadsheet (TSV / CSV / XLSX / ODS) keyed by a participant_id column. Its age / sex / handedness columns override the inventory-derived demographics.

--phenotype PATH

Phenotype measure table keyed by participant_id. Repeat for each instrument; each is written to phenotype/<measure>.tsv + JSON.

--fill-todos

For every sidecar with a missing required or recommended field (and for missing recommended fields of dataset_description.json), write the literal string "TODO". Existing values are never overwritten, so you can sweep through later in the Editor.

--name NAME

Dataset Name (defaults to the BIDS root directory name).

--bids-version VERSION

BIDS spec version for dataset_description.json. Defaults to the bundled schema's version.

--license, --author (repeatable), --acknowledgements, --how-to-acknowledge, --funding (repeatable), --ethics-approvals (repeatable), --references-and-links (repeatable), --dataset-doi

Optional dataset_description.json fields. The repeatable ones take one value per flag.

--no-report

Skip writing .bidsmgr/metadata_report.json (written by default so the GUI and CI tooling can pick it up).

bidsmgr-validate

Two-layer validator. Layer 1 (always) is the schema-driven audit: per-file sidecar checks plus the BIDS Manager-specific rules (TODO placeholders, IntendedFor consistency, fmap pair completeness). Layer 2 (opt-in via --strict) adds the official bidsschematools structural pass.

bidsmgr-validate <target> [options]

Positional arguments

target

BIDS root, or a parent containing one or more BIDS roots.

Options

--dataset NAME

When target is a parent, limit to this single dataset name.

--strict

Also run Layer 2: bidsschematools structural validation. Adds path-shape checks and is slower on large trees.

--strict-warn

Treat warnings as errors for the exit code. By default the command exits non-zero only when there is at least one error.

--html

In addition to the JSON report, write a self-contained HTML report at .bidsmgr/validation_report.html. Inline CSS, safe to share or archive. Issues are colour-coded and grouped by scope (dataset / folder / file).

--no-report

Skip writing .bidsmgr/validation_report.json.

bidsmgr-project

Inspects a project dataset and lists its versioned scans. The active scan is the latest, marked with an asterisk. Useful for finding a version id to pass to bidsmgr-convert --version or bidsmgr-metadata --version.

bidsmgr-project <dataset> [--list]

Positional arguments

dataset

Project dataset folder.

Options

--list

List the scan versions (the default action).

bidsmgr (GUI)

Launches the desktop GUI. The Converter and Editor views drive the same engine the CLI exposes, so anything you can do here can be scripted.

bidsmgr [options]

Options

--theme {dark,light}

Initial colour theme. If omitted, the last theme the user selected in-app is restored (default dark on first run).

--project PATH

Open (or create / adopt) a BIDS dataset project at this directory and land in the Converter bound to it (same as the Welcome tab's Open / Create). The output is locked to the dataset. Note: this is a dataset directory, not a bundle file.

The canonical source for every flag is --help on each verb. If a flag here ever drifts out of date, the argparse definitions in the repository are authoritative.

CLI walkthrough

The same workflow, from the command line.

The GUI you just walked is a window onto the same engine you can drive from a script. The project-first flow is five commands: create a project, scan into it, convert, enrich, validate. Numbers below come from the primary MRI dataset (33 inventory rows; 12 auto-skipped; 21 keepers).

1. Create a dataset project.

Scaffolds dataset_description.json, a README, and a .bidsignore, and initialises the project bundle. The folder name is the dataset slug; the BIDS output is locked to it from here on.

# Create the project the scan / convert / metadata steps below write into.
bidsmgr-create <dataset_dir> --name "Oldenburg neuroimaging unit"

2. Scan the raw folder into the project.

Walks the input tree, reads metadata from inside every file, runs the schema-driven classifier, and saves a versioned, resumable scan inside the project. --probe-convert runs one dcm2niix probe per series so the inventory carries the same BidsGuess the converter will see.

# Save a versioned scan under the project; resumable in the GUI.
bidsmgr-scan <raw_root> --project <dataset_dir> --probe-convert -j 4

# 33 rows, 12 pre-marked bids_guess_skip=true (scouts, Phoenix reports).

3. Convert the active scan into the locked BIDS root.

Reads the project's latest scan, dispatches each row to the right backend per modality, stages per subject under .tmp_bidsmgr/, then commits atomically. Re-runs merge new subjects and sessions in safely.

# Convert the project's active version; output is the project itself.
bidsmgr-convert --project <dataset_dir> -j 4 --on-existing skip

# Writes 21 NIfTI files + sidecar JSONs + events / channels TSVs.

4. Auto-fill required sidecar fields.

Runs the post-conversion metadata engine over the project: fills every required field the schema can infer, plus participants.tsv demographics. For EEG / MEG it also fills reference, ground, filters, device, and event labels.

# Auto-enrich sidecars; stamp "TODO" on anything that needs a human.
bidsmgr-metadata --project <dataset_dir> --fill-todos

5. Validate against the BIDS schema.

Two-layer validator: schema-driven per-file checks plus the structural pass under --strict. Prints a severity-coloured summary; the same checks power the Editor's validation pane.

# Validate the dataset; add --strict for the structural pass, --html for a report.
bidsmgr-validate <dataset_dir>

# Primary MRI dataset result: 55 ok / 7 warn / 0 err.
# The 7 warnings are TODO placeholders, fillable in the Editor in one pass.

Prefer the classic form? Every verb still takes positionals: bidsmgr-scan <raw> <inv.tsv>, bidsmgr-convert <inv.tsv> <bids_parent>, and so on. --project is additive. The full surface (every flag, every verb) is in the reference above.