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.

Every command, every flag.

BIDS Manager ships five console scripts plus the GUI entry. Every verb accepts -v for INFO logging and -vv for DEBUG; documented inline only for the verbs where it changes behavior. Synopses below mirror what --help prints on a fresh install of bids-manager on PyPI.

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 + an entities JSON column carrying the BidsGuess. Re-runnable, diff-able, openable in any spreadsheet tool.

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

Positional arguments

dicom_root

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

output_tsv

Destination path for the inventory TSV. Conventionally placed inside the raw root so relative paths resolve cleanly later.

Options

--jobs N, -j N

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

--dataset NAME

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

--probe-convert

After the metadata walk, run dcm2niix as a probe on every DICOM series (one invocation per SeriesInstanceUID) into a hidden <output_tsv_parent>/.tmp/ staging tree, harvest what was produced, then remove the staging tree. Adds probe_n_files / probe_n_nifti / probe_n_volumes / probe_extensions columns to the TSV and surfaces conversion anomalies (e.g. a BOLD series that split into two NIfTIs because of an operator-aborted volume) in proposed_issues. Slow but most accurate; recommended for first scans.

--no-bids-guess

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

--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 JSON sidecar (BIDS-required). Typical values: 50 (Europe / most of the world), 60 (Americas / parts of Asia). Per-row TSV value wins over this.

--montage NAME

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

bidsmgr-rebuild

Reconciles the inventory TSV's entities JSON column with its derived display cells (proposed_basename, session, task, run). The entities column is the source of truth for the BIDS basename; 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

Path to an 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. Pass columns to do the reverse: regenerate the entities JSON from individual cells (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 under a private .tmp_bidsmgr/sub-XXX/ tree, then atomic-renames into the BIDS root on success. Each distinct dataset value in the TSV becomes its own BIDS root under <bids_parent>/.

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

Positional arguments

tsv

Inventory TSV produced by bidsmgr-scan.

bids_parent

Parent directory; each distinct dataset value in the TSV becomes a sibling BIDS root underneath.

Options

--dataset NAME

Limit conversion to rows whose dataset cell equals this value. Useful for re-running a single dataset out of a multi-dataset inventory.

--jobs N, -j N

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

--overwrite

Replace existing sub-<id>/ folders. Their previous contents are moved to <bids_root>/.bidsmgr/backup/ before the new tree lands. Without this flag, an existing subject folder is left alone and a warning is logged.

--dry-run

Print the per-row conversion plan; write nothing.

--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 (the GUI's default puts the TSV inside the raw root, so this is usually unnecessary).

--dcm2niix PATH

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

--line-freq HZ

Default power-line frequency for EEG / MEG / iEEG rows that don't carry their own value. Default 50; use 60 in the Americas / parts of Asia. Pass 0 to leave unset and let the recording's own value apply.

--montage NAME

Apply a built-in mne montage to every EEG / MEG row before writing. Fills electrodes.tsv + coordsystem.json. Use only if all rows share the same channel layout; otherwise edit the inventory's per-row montage column instead.

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 and / or the inventory TSV. Writes dataset_description.json, enriches every sidecar, and leaves a metadata_report.json audit log under .bidsmgr/.

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). Every BIDS root underneath is processed in turn unless --dataset narrows it.

Options

--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 (PatientAge, PatientSex). Without it those columns default to n/a.

--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" as the value. Existing values are never overwritten. Lets you sweep through the BIDS root and fill the placeholders by hand later in the Editor.

--name NAME

Dataset Name written to dataset_description.json. Defaults to the BIDS root directory name.

--bids-version VERSION

BIDS spec version written to dataset_description.json. Default 1.10.0.

--license TEXT

License field for dataset_description.json.

--author NAME

Author entry. Repeat the flag for each author.

--acknowledgements TEXT

Acknowledgements text for the dataset description.

--how-to-acknowledge TEXT

Required citation text for downstream users.

--funding TEXT

Funding source. Repeat for each entry.

--ethics-approvals TEXT

Ethics approval. Repeat for each entry.

--references-and-links TEXT

Reference or link. Repeat for each entry.

--dataset-doi DOI

DOI for the dataset; written to DatasetDOI.

--no-report

Skip writing <bids_root>/.bidsmgr/metadata_report.json. By default the JSON report is always written so the GUI and CI tooling can pick it up after the run.

bidsmgr-validate

Two-layer validator. Layer 1 (always) is the schema-driven audit: per-file sidecar checks against bidsschematools 1.2.2 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. Mirrors bidsmgr-metadata's shape.

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 against the BIDS spec and is slower on large trees.

--strict-warn

Treat warnings as errors for the exit code. By default the command exits with status 1 only when there is at least one error; with this flag, any warning also fails the run.

--html

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

--no-report

Skip writing <bids_root>/.bidsmgr/validation_report.json.

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.bidsmgr

Open (or create, if absent) a .bidsmgr project bundle. Every edit the user makes in the GUI appends to its event log; the bundle persists overrides + inventory + decisions across sessions.

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.

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. Four console scripts run the same scan, convert, enrich, validate sequence. Numbers below come from the primary MRI dataset (33 inventory rows; 12 auto-skipped; 21 keepers).

1. Scan the raw folder.

Walks the input tree, reads metadata from inside every file (DICOM tags, EDF headers, FIF info), runs the schema-driven classifier on every row, and writes a single inventory TSV you can spreadsheet-edit before any conversion runs. --probe-convert runs one dcm2niix probe per series so the inventory carries the same BidsGuess the converter will see.

# Walk raw_root, write inventory.tsv with one row per series.
bidsmgr-scan <raw_root> <inventory.tsv> --probe-convert -j 4

# 33 rows, 12 pre-marked bids_guess_skip=true (scouts, Phoenix reports).
# Takes ~25 s on the primary MRI dataset on a Mac.

2. Convert each row using the right backend.

Reads the inventory, dispatches each row to the right backend per modality (dcm2niix for MRI, mne-bids for EEG / MEG, bidsphysio for Siemens CMRR physio), stages per subject under .tmp_bidsmgr/, then commits atomically.

# Convert inventory.tsv into bids_parent/. Same engine the GUI uses.
bidsmgr-convert <inventory.tsv> <bids_parent> --raw-root <raw_root> -j 4

# Writes 21 NIfTI files + sidecar JSONs + events / channels TSVs.
# Per-subject staging, atomic os.rename on success.

3. Auto-fill required sidecar fields.

Runs the post-conversion metadata engine. Walks the freshly written BIDS tree and fills every required field the schema can infer (Manufacturer, MagneticFieldStrength, EchoTime, RepetitionTime, etc.) directly from the converted files. Whatever the engine cannot infer is stamped with "TODO" for you to fill in the Editor.

# Auto-enrich sidecars; replace fillable TODOs where possible.
bidsmgr-metadata <bids_root> --fill-todos

# Fills dataset_description.json + every sidecar's required schema fields.
# 5 TODO placeholders remain on this dataset (License, Authors, Instructions, TaskDescription).

4. Validate against the BIDS schema.

Two-layer validator: structural rules (filename grammar, required files) plus per-file schema checks against bidsschematools 1.2.2. Prints a severity-coloured summary; the same checks power the Editor's validation pane.

# Validate the BIDS dataset; emit HTML report with --html.
bidsmgr-validate <bids_root>

# Primary MRI dataset result: 55 ok / 7 warn / 0 err.
# All 7 warnings are bidsmgr.todo_placeholder (fillable in the Editor in one pass).

The GUI runs the same engine. Use whichever interface fits the task: visual review for one-off datasets, scripts for cohort runs. Full CLI surface (every flag, every verb) is documented in the repository README.