MRI advanced tutorial

MRI: the rich-protocol deep dive.

A second Oldenburg MRI sample, picked to push the engine harder than the primary tutorial dataset. Three source folders that cluster to two BIDS subjects, six anatomical contrasts (T1w / T2w / T2starw / FLAIR), BOLD with SBRefs, DWI with scanner-derived FA / colFA / trace / TENSOR maps, fmap pairs, and Siemens CMRR physio. Walk this after the primary MRI tutorial; the GUI flow is identical.

This dataset exercises the classifier's quirks.

The primary MRI tutorial uses a clean dataset with one anatomy, one BOLD, one DWI, one fmap pair. This one piles on: multiple anatomy contrasts, DWI derivatives (FA / colFA / trace / TENSOR) that the BIDS schema 1.11+ treats as first-class suffixes, a PA-direction DWI that gets rerouted to fmap/_epi as the B0 reference for distortion correction, and CMRR physio that converts via the vendored bidsphysio backend.

Example data

Oldenburg neuroimaging unit (3 folders / 2 BIDS subjects)

Three source folders (OL_3844, OL_3845, OL_3846) clustered by PatientID. The first two share XX00XX00 and collapse into sub-001 with ses-pre / ses-post. The third is a different PatientID (YY11YY11) and stands alone as sub-002.

Download MRI advanced dataset →

Dataset overview

3 folders → 2 BIDS subjects.

sub-001 2 folders PatientID XX00XX00

OL_3844 → ses-pre. OL_3845 → ses-post. StudyDate ordering drives which folder gets which session label.

sub-002 1 folder PatientID YY11YY11

OL_3846 stands alone. No second session, so no ses entity is written.

Modality mix 10 distinct datatypes

T1w, T2w, T2starw, FLAIR, BOLD, SBRef, DWI, DWI derivatives (FA / colFA / trace / TENSOR), fmap (magnitude1 / phasediff / epi), physio, scout / Phoenix report (skipped).

Notable classifier moves on this dataset

  • Subject identity clustering. The subject_identity.cluster_subjects module reads the DICOM PatientID + PatientName, then groups folders. Three folders → two clusters → two BIDS subjects with the appropriate session split.
  • DWI derivative detection. The classifier recognises FA / colFA / trace / TENSOR series as scanner-derived derivatives and writes them with the BIDS 1.11+ suffixes (_FA, _colFA, _trace, _TENSOR) in dwi/ rather than dropping them.
  • B0-reference reroute. The PA-direction DWI series (a single-volume acquisition with reversed phase encoding) is automatically rerouted to fmap/_epi so it can serve as the B0 reference for distortion correction of the AP-direction DWIs.
  • Phoenix and scouts auto-skipped. 19 rows on this dataset (3 folders × 4 AAHead Scout variants + 1 PhoenixZIPReport, plus a few extra calibration variants) come pre-marked with bids_guess_skip = true. The user can re-include any of them, but the default is "drop these".
  • CMRR physio. Three physio logs (PhysioLog Siemens CMRR format) are dispatched to the PhysioDcmBackend which uses the vendored bidsphysio. Two of three succeed on this dataset; one is corrupted at source and fails cleanly with bidsphysio produced no output files. The Convert log surfaces the failure without aborting the rest.
What you'll see

Real numbers from the advanced MRI pipeline.

Same four commands as the primary MRI tutorial. The difference is in the breadth of modalities and the classifier's reroute / derivative-detection logic.

Scan 51 / 19 inv rows / skipped

--probe-convert on this dataset takes ~30 s on a Mac (one dcm2niix probe per series). 32 keepers across both subjects, 19 auto- skipped (scouts, Phoenix reports, calibrations).

Convert 32 NIfTI + 9 physio files written

32 NIfTI files (anat / func / dwi / fmap), 9 physio TSV.gz (the successful PhysioLog rows), 44 sidecar JSONs. 3 physio rows fail cleanly with the "bidsphysio produced no output files" warning.

Validate 75 / 5 / 0 ok / warn / err

Zero errors. The 5 warnings are TODO placeholders the enrichment cannot infer: License / Authors in dataset_description.json, plus Instructions / TaskDescription on the BOLD sidecars. Fillable in the Editor in one pass.

What's different vs the primary MRI tutorial

Same engine, more data variety.

  • More than one anatomical contrast. The primary dataset has T1w + T2w. This one has T1w + T2w + T2starw + FLAIR. All four route to anat/ with the correct suffix; no per-row override needed.
  • DWI scanner-derivative detection in action. BIDS 1.11+ promoted FA, colFA, trace, and TENSOR to first-class suffixes; older pipelines either dropped them or hand-coded a derivative layout. The classifier recognises them natively.
  • The B0 reroute. Watch the Convert log for classifier: acq-15_dir-PA b0 rerouted to fmap/_epi. The PA-direction single-volume DWI becomes the BIDS-required reference for distortion correction without a heuristic file.
  • Partial physio failures. Three of the CMRR physio rows fail cleanly. The dataset is still BIDS-valid because the failed rows do not write incomplete output (the per-subject staging is atomic). The Convert scene in the GUI surfaces the failures in the Log dock.
  • Highlight aborts becomes useful. The inspection-pane footer's Highlight aborts toggle tints suspected-abort rows purple. On the primary dataset it does nothing (no aborts). Here it lights up the scout-with-MPR pairs the classifier already auto-deselected.

Walk the GUI tutorial → See the CLI walkthrough