Tutorial

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

One walkthrough from end to end. Seventeen steps take the GUI from an empty folder to a validated dataset, scanning, curating, converting, annotating and checking a real MRI dataset, and the section after them runs the same workflow from the command line. Read at your own pace, or download one of the six sample datasets and follow along on your own machine.

There is one more page, and it is a task rather than a route: defacing and skull stripping. Read it before an MRI or PET dataset leaves the people who collected it. It applies whichever route you took, because a face can be removed during the conversion or at any point afterwards.

Step 1

Create a project

Everything you do lives inside a project. A project is your dataset folder plus a hidden record of every scan you have run and every edit you have made, so you can close the application and pick the work up exactly where you left it.

On the Home tab choose Create, give the dataset a folder and a name, and BIDS Manager scaffolds dataset_description.json, a README and a .bidsignore for you. If you have worked on this dataset before, choose Open, or pick it from the recent list.

The name you type here is written into dataset_description.json as the dataset title. If you later change that name, BIDS Manager asks whether you meant to rename the project folder as well, or to keep the folder name and use the new one as the dataset title. It does not guess.

What you should see now: the Converter tab, with an empty inventory table and the project name in the header.

Before you scan

Two settings worth a look first.

The defaults are chosen so you can convert a dataset without opening Settings at all, and most of what is in there can wait. Two things are worth knowing before you start, because they are easier to set now than to change later. The gear is in the header.

Which version of BIDS you are working to

The first tab decides which version of the standard this session works to, and it reaches everything downstream: the fields the metadata forms ask for, the entities a filename may carry, the BIDSVersion written into dataset_description.json, and the rules validation judges the result by.

Leave it on the newest for a new dataset. Change it when you are adding to a dataset that was built against an older version, so the forms ask for that version's fields and validation does not report changes the standard made after your data was collected.

What happens automatically after a conversion

The Convert and post-convert tab holds the chain that runs after every conversion: generate the metadata, mark what could not be filled, validate, and write a report. It is all on by default, which is why the walkthrough below can go straight from converting to reading findings without a separate step.

The setting in the same tab that matters most is Existing subjects. The default, Skip, keeps what is already in the dataset and adds only what is new, so re-running a conversion is safe. The others exist for when you deliberately want to replace something.

Step 2

Point at your raw data

Press Scan and choose the folder holding your raw recordings. Point at the top of the tree, not at one subject. The scanner walks down through everything below it and works out subjects, sessions and series for itself.

You do not have to tell it what is in there, and you do not have to separate the modalities first. A folder holding MRI DICOM, EEG recordings and PET data all at once produces a single inventory with every recording in it.

Step 3

Run a scan

The scan opens every file it finds and reads the metadata inside it. Not the filenames: the headers. For DICOM that means the acquisition parameters, the study and series identifiers, the patient identifiers used to group subjects, and the timestamps. For EEG and MEG it means channel counts by type, sampling frequency, duration, and the recording date used to infer sessions.

It then classifies each recording, proposing a datatype and a suffix with a confidence score, and builds one row per recording.

Probe convert, and why to leave it on

With probe convert enabled, the scan additionally runs the converter once per series and reads the sidecar it produced. That is how BIDS Manager knows, before you have typed anything, which metadata fields the conversion is going to answer by itself. Those fields are then shown to you as already answered rather than asked for. It costs some scanning time and saves a great deal of typing.

What you should see now: the inventory table filled with rows, and the chips in the toolbar showing how many are valid, how many carry warnings, and how many were auto-skipped.

Step 4

Read the inventory

One row per recording, whatever produced it. A PET DICOM series, a Siemens physiological log, an EEGLAB file and a MEG FIF all arrive in the same table with the same columns, which is what lets you curate a multimodal study as one piece of work instead of four.

Before changing anything, read what the scan found. These are the columns that carry the most information.

Those are the columns shown by default. There are around forty in all, and Manage columns below the table shows, hides and reorders them; the layout is remembered. Channel counts, sampling rate, duration, patient details and the proposed-issues text are all there, hidden until you want them. Each carries a description of what it holds, so an unfamiliar one can be identified without leaving the dialog.

What the row colours mean

Rows are tinted so that problems are visible without opening anything. A red row has an error that will stop it converting or that needs your decision. An amber row carries a warning worth reading. A dimmed row is excluded. A teal row with a crossed-circle badge is an object with no image data inside it, such as a Siemens TENSOR map or a scanner report, which cannot be converted at all and has been excluded with the reason shown. Hover any row to see why it is marked.

Step 5

Curate: include, exclude, rename

This is the step the rest of the workflow depends on. Everything you decide here is what gets converted, and nothing is written to disk until you are finished.

Excluding what you do not want

The first column of the table is a tick box, and it is the only thing that decides whether a row becomes a file. Untick anything that should not be in the dataset: localisers, calibration scans, a run that was aborted and repeated. The scan already excluded what it could recognise as unconvertible, but only you know that the second T1w was the one worth keeping.

You can also work from the Filter / structure tree on the left, which shows the same recordings grouped by subject, session and datatype. Unticking a folder there unticks everything inside it, which is how you drop a whole session or a whole datatype without hunting for its rows in the table. It is one model shown two ways, so a change in either is a change in both.

Editing many rows at once

Select several rows and use Bulk edit to set the same value on all of them: a task label across fourteen runs, a session across a whole subject. This is the fastest way to fix a systematic naming problem.

It also removes an entity, and both the set and the remove are applied row by row. Select the whole study and ask for the acquisition label to go: it comes off the rows that have one and are allowed to lose it, and the rest are left alone rather than the edit being refused. A _bold keeps its task because the schema requires it; an anatomical row does not have to. The dialog says how many rows it will touch before you tick anything.

Finding the rows you need

The Filter pane narrows the table by subject, datatype, modality or status, which matters once an inventory runs to hundreds of rows. Manage columns lets you show, hide, reorder and resize columns, and every column carries a description of what it holds.

The table opens with subject, format, session, datatype, suffix, BIDS name and sequence first, which is the order a row reads in. If you have already arranged the columns to suit yourself, that arrangement is left alone; Reset defaults in the Manage columns dialog puts them back to that order whenever you want them back.

One row at a time

Select a row and the properties panel on the right shows its entities as editable fields, at the level BIDS sets: a red asterisk for required, an amber dot for recommended. Below them is the predicted path, so you can see the consequence of an edit immediately, and any validation messages for that row.

An entity that carries a value and is allowed to do without one has a × beside it that takes it off this recording. Clearing the field does the same thing, but nothing on screen said so: an empty box reads as not filled in yet rather than as an instruction. Required entities have no button, because there is nothing to offer.

Step 6

Resolve duplicate names

Two recordings must never end up with the same BIDS filename. If they do, the second is written over the first, and a scan disappears from your dataset without anything being reported.

BIDS Manager works out the destination of every included row before converting anything, and handles the two cases differently.

When BIDS has an answer, it is applied

If several recordings genuinely are repeats of the same thing, and the standard allows a run entity for that datatype, they are numbered run-1, run-2 and so on. The order is by acquisition time where the files record one, and by source path otherwise, so re-scanning the same folder gives the same numbers rather than shuffling filenames underneath you. The scan tells you it did this.

When it does not, the name turns red

A run number is the right answer for two repeats of one acquisition and the wrong answer for two different tasks, and nothing in the file can tell those apart. So where a run cannot be assigned, because the datatype does not allow one or because a run is already set and the names still clash, the predicted basename is shown in red and left alone.

Hover the row to see why. Then change whichever entity actually differs: a task label if they are different tasks, a session if they were acquired on different days, a run if they really are repeats. The red clears as soon as the clash is resolved, on both rows at once, because it is recomputed from the table as it stands rather than remembered from the scan.

A worked example. A workshop EEG tree gives each subject a rest folder and a video folder, both containing a recording named after the participant code. Both resolve to the same BIDS name. The right fix is not a run number: it is a task label, because they are different tasks. That distinction is exactly what BIDS Manager declines to guess.

Step 7

Fill the metadata template

Getting the files into the right folders is the quick part. Describing them correctly is the part that takes the time, and this step is where most of that work happens. Open Dataset metadata.

A section speaks for every file of its kind

This is the thing to understand before anything else. A section headed

every *_bold.json · in func/ · 61 files · for example sub-003_task-rest_bold.json

is not a form about sub-003. It is the statement you are making about all 61 functional runs in the dataset. Answer it once and it is written into every one of them. The real filename is shown only as an example of what the section covers.

What it does not ask you

The template does not ask for anything your data has already answered. Fields the conversion will fill by itself appear in a folded green block at the top of each section, headed Already answered by the conversion, showing the value that will be written.

That block is editable, and deliberately so. The converter reads those values out of your data, and when the data is wrong, or a legacy file carries nothing, this is the only place to correct it. Typing nothing there changes nothing.

Reading the form

Every field carries the standard's own description as a tooltip, on the label and on the box, so you do not need to keep the BIDS specification open beside you. Fields with a fixed vocabulary offer it as a dropdown you can still type into.

Values are typed, not just text

Whatever you type is converted into the shape the schema declares before it is written. A mains frequency reaches the sidecar as the number 50, not as the string "50", which BIDS would reject.

What the form looks like for your data

The dialog is built from the standard and from what your scan found, so it asks a different set of questions for each modality. Pick yours:

Step 8

Override an answer for one recording

The dataset template states what is true of every file of a kind. Two things are usually not true of every file: something that genuinely varies, and something that was wrong for one session only.

Select the row and answer in the properties panel instead. A per-recording answer always beats the dataset answer, for that recording alone. An inherited value is shown greyed, with a tooltip naming where it came from, so you can always tell what you set from what you are inheriting.

Editing an inherited field back to the dataset value clears the override rather than storing a duplicate, and changing the dataset answer re-flows into every row still inheriting it.

Where the answers are kept. Nothing is written into your BIDS dataset at this stage. Answers live beside the inventory until the metadata step applies them, which means you can change your mind freely, and re-run a conversion without losing them.

The same panel, on four kinds of recording

The panel is built from the schema for whatever row you selected, so it asks a different set of questions on each one. What stays the same is the shape: the entities that make the name, the path they produce, then the metadata, with the questions every modality shares kept separate from the ones only this modality has.

Step 9

Attach companion and blood files

Some of what belongs in a BIDS dataset never passes through the scanner. The events your stimulus software wrote, a behavioural log, the stimulus files themselves, a channel table somebody corrected by hand, the electrode positions a digitiser produced, and for PET the arterial blood curves. BIDS has a place for all of them, and the software cannot invent any of them, so this is the step where you say which file goes with which recording.

Every row can carry companions, whatever it holds. Companions are not an EEG feature or a PET feature. An MRI functional run has events, a behavioural session has a _beh.tsv and no image at all, and a physiological recording can arrive as a separate file. Select a row, then find COMPANION FILES in the properties panel on the right.

The six kinds, and when you would use each

Event codes, while you are here

A recording usually carries numeric trigger codes rather than labels, and only you know that code 3 was the target condition. You do not link a file for that: the recording metadata dialog takes the labels once for the whole dataset, and the conversion writes them into events.tsv and its sidecar, so every run gets the same vocabulary.

PET blood is a companion too, but it is converted

Blood curves have their own section, BLOOD SAMPLING, because they are the one companion that is not simply copied. A PMOD .bld export is read, merged and rewritten as a BIDS blood table, with the sample times converted to seconds. Three curves are linked separately: whole blood, plasma, and parent fraction.

For each, say whether the samples were drawn manually or by an autosampler. This is not a formality: hand-drawn and autosampled series have different time resolution, so BIDS writes them into separate files, and your choice decides which file each curve lands in.

After conversion you get sub-001_trc-FDG_run-1_recording-manual_blood.tsv and its sidecar, carrying the run's own entities so a subject with two tracers gets two distinct sets rather than two files competing for one name. The data dictionary is generated from the table that was actually written, and the availability flags follow from what you linked, so you are never asked to state them.

Linking blood also adds an every *_blood.json section to the dataset template, asking for what the curves cannot tell you: whether the plasma was dispersion corrected, which BIDS requires, the withdrawal rate, the tubing, the haematocrit. If you linked a parent fraction curve it also asks how metabolites were measured, because that requirement applies only when metabolite data exists.

Step 10

Preview the BIDS tree

Before converting, open the BIDS preview in the bottom panel. It shows the exact folder structure and the exact filenames your current table will produce, built from the same schema the converter uses.

This is the last cheap moment to notice that a subject label is wrong, that a session is missing, or that a task name reads task-Rest in one row and task-rest in another. Reading the tree takes a minute; fixing it afterwards means converting again.

What you should see now: a tree of sub-*/ folders with datatype folders inside them, and no name appearing twice.

Step 11

Run the conversion

Press Run conversion. Each row is sent to the engine that reads its format: dcm2niix for DICOM, mne-bids for EEG and MEG recordings, pet2bids for ECAT and blood, bidsphysio for the physiological signals inside Siemens MRI DICOM files. You do not pick the engine; the row's format does.

What happens while it runs

Files are written into a private staging folder per subject first, and moved into place only when that subject converted successfully. A failure therefore leaves no half-written subject behind. If one file defeats its engine, that failure is contained: the row is reported and every other row still converts.

Conversion also repairs what the engines get wrong on the way out: fieldmaps are renamed to their BIDS suffixes and given an IntendedFor list, scans.tsv is written, key casing and scalar-where-array mistakes in sidecars are corrected against the schema.

You can stop a running conversion. It finishes the file it is on and stops cleanly rather than leaving a partial dataset.

Step 12

Read what the conversion reported

Open the Log in the bottom panel when it finishes. Read it even when everything succeeded, because it tells you what was done on your behalf.

For the other half of the question, what you actually ended up with, the Editor has a Dashboard under Tools: how many subjects, which modalities, how much of the metadata each one has answered, and which subject is the odd one out. The log says what happened; the dashboard says what you have. It is covered in the GUI tour, and you will use it in a moment.

What you should see now: a populated BIDS dataset on disk, and the Editor tab ready to open it.

Step 13

Open the dataset in the Editor

Switch to the Editor and open your converted dataset. This is where you review and repair what the conversion produced, without needing any other software.

The window has three parts. On the left, the BIDS tree of your dataset, with every row carrying how many findings are inside it: warnings in amber, errors in red, a green tick where there is nothing to report. In the centre, whatever you have selected, opened in the right viewer for its type. On the right, the validation pane listing findings for the dataset, the folder and the selected file.

The chips in the toolbar summarise the whole dataset at a glance, and clicking one opens the list of files carrying that severity, so you can work through the problems rather than hunting for them.

Step 14

Edit sidecars and tables

Selecting a file opens it in an editor built for its type. Both are editing surfaces, not just viewers: what you change is written back to the file.

JSON sidecars

A .json sidecar opens as a schema-aware form, not as raw text. Every field the standard declares for that datatype and suffix is listed, in requirement order, whether or not the file contains it: required fields first with a red asterisk, then recommended, then optional. Fields the file carries but the standard does not define are shown too, so nothing is hidden from you.

Each row carries the standard's own description, so you can see what a field means while you fill it. This is the view that makes a sidecar reviewable by someone who does not have the specification memorised.

The Tree view tab shows the same file as a plain two-column key and value tree, which is the faster way to read a file you already understand, or to inspect keys that fall outside the schema.

TSV tables

A .tsv file, such as participants.tsv, events.tsv or channels.tsv, opens as an editable table. Click a cell, type, and the file is updated.

Large tables stay usable: the file is read on a background thread so the window never freezes, and only the visible cells are drawn, so a table with two million rows opens as quickly as a small one.

Undo

Editing is undoable. The toolbar carries undo and redo covering both sidecar edits and table edits, so you can try a change and step back from it.

Step 15

Look at the images and signals

The Editor opens your converted data directly. You do not need a separate image viewer or a separate signal browser to check that a conversion produced what you expected.

Any two NIfTI images can also be opened side by side, through Tools → Compare images or by right-clicking a selection in the tree. One set of controls drives both panes: crosshair, slice, plane, volume, the 4-D graph, the 3-D camera and its effects. Images of different shapes work, because the crosshair travels in millimetres rather than in voxels. It was built for checking a defaced image against the original and turned out to be useful for raw against preprocessed, echo against echo, and one session against another. How the compare viewer works →

Step 16

Validate, and read a finding

Press Validate dataset. The validator is part of the same application and reads the same BIDS schema as everything else, so what it checks and what the metadata forms ask for can never disagree.

Three scopes

Validate file checks the selected file, Validate folder everything under the selected folder, and Validate dataset the whole tree including the dataset-level files and the relationships between files. Validation also re-runs as you edit, so a fix turns a finding green without leaving the window.

Deep checks

The Deep checks toggle additionally opens NIfTI image headers, which catches a truncated or corrupt image that every name-based check would pass. It is slower, so the usual pattern is to leave it off while editing and switch it on once before a final review. It has no effect on a dataset of EEG or MEG recordings, which are validated from their sidecars and channel tables.

How to read a finding

Every finding tells you three things:

• What is wrong, in the standard's own terms.
• How to fix it, including an example of the value that is expected.
• Which rule of the BIDS schema it came from, shown beneath the message, so the requirement can be checked against the standard rather than accepted on the tool's authority.

Findings point at the field or the table column they refer to. The fix button takes you straight to that row of the sidecar form or that column of the table, and Highlight in editor tints every field or cell a finding refers to, so you can see all of them at once.

Things it catches that name-based checks do not

A correctly named file inside a folder that is not a BIDS datatype, such as sub-01/ses-pre/anatomy/, is reported as an error. Every filename in there can be perfect, and no BIDS tool will ever read them.

A literal TODO left in a sidecar is flagged as well. The metadata step writes those into recommended fields it could not fill, precisely so that they are visible here rather than forgotten.

Reports you can send

The severity filter in Settings controls what is shown, so you can work errors first and warnings later. A validation report can be written out as HTML, which is the artefact to attach when someone else needs to see the state of a dataset.

The whole dataset at a glance

The pane always shows three scopes at once, from the outside in. The dataset section holds findings about the dataset as a whole, the things no single file is responsible for. The folder section holds findings about the folder you are in. The file section holds findings about the file you have selected. Each carries a count, so a section with a zero beside it needs no attention.

An error inside a file

Not every problem is a naming problem. This one is a value: a timestamp in a scans table that is not a valid datetime, which no filename check could ever see. The message names the column and the offending value, the chip beside it names the field, and the grey line underneath is the rule in the BIDS schema that the requirement comes from.

Warnings, and how to clear them

Warnings are recommendations rather than violations. Most of what you see after a first conversion are recommended fields nobody has answered yet, and each carries a Fix button that takes you straight to the field in question.

An error inside a sidecar

The other kind of internal error is a field holding the wrong kind of value. A number written as text, a string where the standard wants an object. The file parses, the name is fine, and the value is unusable by anything that reads it expecting a number.

Something that should be there and is not

Some findings are about a file that is missing rather than a file that is wrong. These are warnings, because the standard recommends rather than requires them, and they are easy to miss precisely because nothing is visibly broken.

Structural errors, which are the ones most tools miss

A structural error is not about the contents of a file. The file can be perfectly named and perfectly formed and still be somewhere, or called something, that no BIDS tool will ever look at. Checked one filename at a time there is nothing wrong, which is exactly why these survive into published datasets.

The three below are all real findings on one dataset. It is the converted multimodal sample with three things broken by hand afterwards, which is how these happen: somebody tidies a folder, renames a file, or copies a naming pattern from another modality.

A datatype folder with a typo in it

Someone renamed anat to anatt. The T1w inside still has a flawless BIDS name. Every BIDS tool reads inside the datatype folders, so from now on that scan does not exist as far as any pipeline is concerned, and no per-file check will say a word about it.

An entity that does not belong on this kind of file

BIDS defines which entities each kind of file may carry, and they are not interchangeable between modalities. echo is meaningful on an MRI acquisition and meaningless on an EEG recording, so a name copied from one to the other produces a file the standard cannot account for.

What breaks next, which nobody expects

Moving those two folders also broke something else. scans.tsv lists every image in the session by its path, and two of those paths no longer point at anything. The manifest and the tree now disagree.

Step 17

Correct the shape, if it is wrong

Some problems are not a value in a file. A task label is wrong on forty recordings, one participant's scans were never put into a session although everybody else's were, a pilot run should not have been converted at all. These are changes to the shape of the dataset, and they live under Tools in the Editor toolbar, or on a right-click in the tree.

Moving the files is the easy half. What breaks a dataset is everything left pointing at what moved: the *_scans.tsv row naming a path that is gone, the IntendedFor entry on a fieldmap still pointing at the old image, the participants.tsv row for a subject who is no longer there. A validator reports none of those as a broken link, because every filename still in the dataset is perfectly valid. Each action below repairs all of it in the same step, and each is one step in the Editor's history, so a single Undo takes the whole thing back.

Try it on this dataset

In the sample MRI dataset, sub-001 has two sessions and sub-002 has none, because only one of the two people was scanned twice. That is legal BIDS, but it is awkward to analyse, and most studies would rather every subject had the same shape. So put the second subject into a session:

1. Click sub-002 in the BIDS tree.
2. Tools, then Sessions....
3. Type a session label. pre, to match the other subject.
4. Press Plan and read the preview before anything happens.

The preview nests subject, then session, then datatype, then file, the way the dataset is actually shaped, and every file has its own tick box. Acting on part of a selection is a legitimate answer, and the repairs are recomputed for whatever you leave ticked. The repairs themselves cannot be unticked: switching one off would reintroduce exactly the damage the action exists to prevent.

The other two

Add or remove an entity

The key-value pairs in a BIDS filename are called entities (task-rest, acq-highres, run-2). This adds one a file is permitted to have or removes an optional one it has. The list on offer holds only what the standard allows for that kind of file, so a required entity cannot be taken away and an entity that does not belong cannot be added. The new pair is placed in the standard's own order rather than where you typed it. Across a selection it works file by file, so a file that cannot take the change is left alone rather than stopping the others.

Delete

Remove a recording, a datatype, a session or a whole subject, together with the scans rows, the IntendedFor entries, the participants row of a subject with nothing left, and the folders the deletion empties. A scans table is deleted only when nothing it describes survives; otherwise its rows are edited. The dataset root, dataset_description.json and the change history itself are refused.

Rename entity

Change a value everywhere it appears: task-rest to task-restingstate across the study, or one subject's label. The sidecar's TaskName follows the label, but only when the value there really does derive from the old one, so something you wrote by hand is left alone rather than overwritten with a guess.

What you should see now: the tree in its new shape, with the counts on each row updated, because validation re-runs itself after a change of this kind.

These four actions are in the application only. There is no command line equivalent, because each one is a decision about a particular dataset that you want to see previewed before it happens, and a flag cannot show you a preview.

Step 18

Fix, re-validate, and finish

Work down the findings, fixing each where the fix button takes you, then press Re-validate. The counts on the tree and the chips in the toolbar update, and you are finished when the errors are gone. A finding that landed on several files at once has a Fix in all files button on its group: it lists every file it fired on with the value each one holds now, so you answer once rather than twelve times.

What "done" looks like

Zero errors. Warnings are worth reading rather than clearing blindly: many are recommended fields that genuinely do not apply to your study, and a warning you have read and decided about is a different thing from one you have not seen.

Adding more data later

You do not start again. Scan the new folder into the same project and convert with --on-existing skip, or its equivalent in the Settings. New subjects and sessions merge in and the files already converted are left alone. Every scan is versioned inside the project, so you can always see what you converted and when.

Your curation is saved too. Reopening the project restores the inventory, the edits and the template answers, so a dataset you return to in six months does not need to be understood again from scratch.

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 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 (most of the 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 (bids_name, 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 including PET DICOM, mne-bids for EEG / MEG, pet2bids for PET ECAT and blood curves, 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 as n/a, since the mains frequency is a property of the building and nothing in the recording states it.

--pet-metadata PATH

PET dose and tracer metadata as JSON, keyed by BIDS sidecar field names (TracerName, InjectedRadioactivity, ModeOfAdministration and the rest). A flat object applies to every PET run; an object keyed by sub-<label> scopes it per subject. It reads the shape pypet2bids accepts, its nifti_json wrapper included, so a file written for that tool works here unmodified. Keys BIDS does not define for a PET sidecar are reported and dropped, never written.

--pet-spreadsheet PATH

The same information from the dose table a lab already keeps. One row per scan or one row per field; loose about column naming and strict about values.

--force-edf

Re-encode EEG 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.

--overwrite-curation

When re-converting a subject that already exists, let the fresh conversion win outright. By default a JSON sidecar and a *_scans.tsv are merged field by field instead, so metadata you curated in the Editor survives the second pass. Only has an effect together with --on-existing update or replace.

-v / --verbose

More log detail: -v for INFO, -vv for DEBUG. Worth reaching for when a conversion produced something you did not expect and the default log does not say why.

--deface

Remove the face from anatomical and PET images before each subject is committed, so the identifiable image never enters the dataset. This is the safest placement, because conversion stages a subject in a temporary folder and defacing runs there, before the move. Nothing is kept to undo from: your raw source data is where a re-run starts. See the defacing tutorial.

--deface-engine NAME

Which engine, one of allineate (the default), allineate-robust, allineate-afni, mindgrab or strip-atlas. The last two keep only the brain and write a derivative rather than replacing the image.

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

Schema-driven validation, delegated to the bidsval engine and supplemented with the BIDS Manager conventions that bidsval does not carry, such as flagging literal TODO placeholders. Runs the fast structural pass by default; --strict adds the deep checks. Every finding carries the schema rule it came from.

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

Deep checks: read NIfTI headers and file contents as well as the structural and metadata checks. Catches unreadable or malformed files, and is slower on large trees.

--schema VERSION

The BIDS schema version to validate against, for example 1.11.1. bidsval ships several, so an older dataset can be checked against the standard it was built to. Defaults to the bundled schema.

--max-rows N

How many rows of each TSV to scan during column and value checks. Default 1000; raise it to scan more of a long table.

--no-todo-warnings

Do not flag literal TODO values as warnings. That flagging is a BIDS Manager convention, on by default; turning it off gives counts identical to bidsval alone.

--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-deface

Removes the face from the anatomical and PET images of a dataset that already exists, or keeps only the brain and writes the result as a derivative. One reversible operation, recorded in the Editor's history. --dry-run reads headers only, so it reports what would happen without needing the engine installed. The defacing tutorial covers every option with pictures.

bidsmgr-deface <bids_root> [options]

Options

--target PATH

Limit the run to this file or folder. Repeatable. Defaults to the whole dataset.

--engine NAME

allineate (default), allineate-robust, allineate-afni, mindgrab, strip-atlas. The first three remove the face; the last two keep only the brain.

--dry-run

Print the images that would be treated and the ones that would be skipped with the reason, and stop.

--keep-original-in-sourcedata

Copy each original to sourcedata/ first, so it can be restored at any point later. Those copies still contain the face, so remove them before sharing.

--in-place

For a skull-strip engine: overwrite the original instead of writing to derivatives/bidsmgr-skullstrip/.

--list-engines

Describe every engine and exit.

-q, --quiet

Only report the outcome.

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

The same engine the Editor's validation pane uses, so a dataset that passes here passes there. Prints a severity-coloured summary, and each finding names the schema rule behind it.

# Validate the dataset; add --strict for deep checks, --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.

Recipes for the things you will actually need

The five commands above are the whole flow. These are the variations that come up in practice, each with the reason you would reach for it.

Add new subjects to a dataset you already converted. New sessions merge in and existing files are left alone.

bidsmgr-scan /data/raw_july --project /data/bids/my_study --probe-convert
bidsmgr-convert --project /data/bids/my_study --on-existing skip

See what would happen, without writing any file.

bidsmgr-convert inv.tsv /data/bids --dry-run

Convert PET using your lab's dose spreadsheet. Loose about how your columns are named, strict about the values it reads.

bidsmgr-convert inv.tsv /data/bids --pet-spreadsheet doses.xlsx

Convert ECAT when the inventory is not beside the raw data. ECAT rows store a path relative to the folder that was scanned, so without this the file cannot be found. The message tells you as much.

bidsmgr-convert inv.tsv /data/bids --raw-root /data/raw

Work against a specific BIDS version. Every verb takes --schema, so the metadata forms, the filenames, the enrichment and the validator all agree on which version of the standard you are targeting.

bidsmgr-scan /data/raw inv.tsv --schema 1.8.0
bidsmgr-validate /data/bids --schema 1.8.0

Re-encode EEG recordings to EDF on the way in.

bidsmgr-convert inv.tsv /data/bids --force-edf

Teach the scanner about your site's sequence names. The same JSON the GUI writes from Settings, Scan rules, so a rule you set up once in the window works headless too.

bidsmgr-scan /data/raw inv.tsv --rules-file site_rules.json

Bring in participant demographics and questionnaires. Columns become participants.tsv; each phenotype table becomes a file under phenotype/ with its own data dictionary.

bidsmgr-metadata /data/bids --participants demographics.xlsx \
                            --phenotype hads.tsv --phenotype moca.tsv

Produce a validation report you can send to someone. --strict additionally opens NIfTI image headers, which catches a truncated or corrupt image that every name-based check would pass.

bidsmgr-validate /data/bids --strict --html

Edit the inventory in a spreadsheet, then rebuild the names. Change the entities, and the predicted BIDS names are recomputed from them.

bidsmgr-rebuild inv.tsv --from entities

List the scan versions saved inside a project. Every scan is versioned, so you can see what you have and convert an earlier one.

bidsmgr-project /data/bids/my_study --list

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.