Basic Usage

MRSIPrep runs as a Docker container; there is no supported host installation of the pipeline itself. Either invoke docker run directly, or install the mrsiprep-docker wrapper from PyPI (pip install mrsiprep-docker), which builds the equivalent docker run command for you — see Installation for both options. The examples below use plain docker run; drop the bind-mount flags and image name for the equivalent mrsiprep-docker command.

docker run --rm \
  -v /path/to/bids:/data:ro \
  -v /path/to/derivatives:/out \
  mrsiup/mrsiprep:cpu \
  /data /out participant \
  --participant-label S001 \
  --session-label V1 \
  --metabolites CrPCr,GluGln,GPCPCh,NAANAAG,Ins \
  --ref-met CrPCr \
  --mode mni-norm \
  --synthseg-mode fast \
  --nthreads 8

mni-norm registers the imported MRSI signal maps to a SynthSeg-extracted T1w image, resamples into MNI space, and runs SynthSeg with cortical parcellation. Its parcel QC table reports the percentage of each anatomical T1w parcel covered by MRSI, parcelwise CRLB, and valid-voxel fractions. mni-norm does not run FAST, PETPVC, Chimera, or recon-all.

SynthSeg-based brain extraction always retains the whole brain (GM, WM, ventricles, and inner/outer CSF, including extra-ventricular CSF label 24) — only SynthSeg background (label 0) is excluded from the brain mask, so FAST sees the complete CSF compartment when estimating tissue probabilities.

Try it now: demo on the public SynthMRSI-Project dataset

No BIDS dataset of your own yet? Download the small, public, synthetic SynthMRSI-Project dataset (32 subjects, real T1w + model-synthesized MRSI signal, CC0) and run MRSIPrep against it directly:

# 1. Download and extract the public test dataset (~300-400MB)
curl -L -o SynthMRSI-Project.zip \
  "https://zenodo.org/records/21477048/files/SynthMRSI-Project.zip"
unzip SynthMRSI-Project.zip

# 2. Pull the CPU image
docker pull mrsiup/mrsiprep:cpu

# 3. Run a single subject in mni-norm mode (a couple of minutes on a
#    modern multi-core machine)
docker run --rm \
  -v "$(pwd)/SynthMRSI-Project:/data:ro" \
  -v "$(pwd)/SynthMRSI-Project/derivatives:/out" \
  -v /path/to/your/freesurfer/license.txt:/opt/freesurfer/license.txt:ro \
  -e FS_LICENSE=/opt/freesurfer/license.txt \
  mrsiup/mrsiprep:cpu \
  /data /out participant \
  --participant-label 01 \
  --session-label 01 \
  --mode mni-norm \
  --t1 acq-mprage_T1w \
  --metabolites NAANAAG,GPCPCh,CrPCr,GluGln,Ins \
  --ref-met CrPCr \
  --nthreads 8 --nproc 2 --verbose 2

# 4. Open the QC report to confirm it worked
xdg-open SynthMRSI-Project/derivatives/mrsiprep/sub-01/ses-01/reports/coverage/sub-01_ses-01_desc-report.html

Drop --participant-label 01 to process all 32 subjects (scale runtime by 32 / --nproc). You'll need a free FreeSurfer license file (from https://surfer.nmr.mgh.harvard.edu/registration.html) for mri_synthseg. See PUBLIC_DATASET.md in the repository for the dataset's full description, ground-truth files, and expected output layout.

Check all selected subject/session inputs without running preprocessing:

docker run --rm \
  -v /path/to/bids:/data:ro \
  -v /path/to/derivatives:/out \
  mrsiup/mrsiprep:cpu \
  /data /out participant \
  --participants participants.tsv \
  --metabolites CrPCr,GluGln,GPCPCh,NAANAAG,Ins \
  --ref-met CrPCr \
  --validate-only

--validate-only reports every invalid recording before any expensive segmentation, registration, parcellation, or PVC step starts. Use it before starting an expensive batch run.

The preflight table shows, per recording: T1w reference, MRSI file count, CRLB/SNR/FWHM quality map availability, brainmask, tissue files, a FreeSurfer column (shown only in parc-con mode with Chimera parcellation, indicating whether a valid prior recon-all output already exists and will be reused), and the MRSI→T1/T1→MNI transform status.

The Nipype workflow engine

Every processing run is orchestrated by a per-recording Nipype workflow (mrsiprep/workflows/nipype_engine/) rather than a hand-rolled script. This is transparent to normal use — the CLI, its arguments, and the console output are unchanged — but it has two practical consequences:

Rerunning a completed subject/session skips already-finished steps. Each of the 13 pipeline steps (tissue segmentation, anatomical prep, MRSI preprocessing, registration, tissue probability maps, PVC, resampling, SynthSeg parcellation/QC, Chimera/MNI parcellation, regional extraction, connectivity, metprofiles export, reports) is a cached Nipype node, keyed on the step name plus the full run configuration. If nothing about the configuration or the subject/session changed since a prior successful run, the step is skipped rather than recomputed — a rerun of an already-fully processed recording typically finishes in a few seconds instead of tens of minutes. Pass --overwrite (or one of the step-specific --overwrite-* flags) to force recomputation regardless of the cache.
--nproc fans out across recordings, each running its own independent Nipype workflow; within one recording the steps run as a linear chain (they are an inherent data-dependency chain, not independently parallelizable).

The engine's own working files (node caches, intermediate SynthSeg/FAST outputs, scratch resampled maps used only to build QC figures) live under --work-dir (default <output_dir>/work), separate from the permanent derivatives in <output_dir>/mrsiprep/. It is safe to delete --work-dir between runs to reclaim space — the next run will simply recompute everything from scratch (the permanent derivatives in mrsiprep/ are unaffected either way, though already-cached recordings will then rerun since their node cache is gone).

Verbosity, logging, and provenance

docker run --rm \
  -v /path/to/bids:/data:ro \
  -v /path/to/derivatives:/out \
  mrsiup/mrsiprep:cpu \
  /data /out participant \
  --participants participants.tsv \
  --metabolites CrPCr,GluGln,GPCPCh,NAANAAG,Ins \
  --ref-met CrPCr \
  --mode parc-con \
  --verbose 1 \
  --nthreads 8 \
  --nproc 4

--verbose (0-3, default 1):

0 — only the start/finish line and elapsed time (hours-minutes, e.g. 0h06m; seconds for sub-minute/cached runs) per subject/session.
1 — also prints each processing step as it starts (tissue segmentation, anatomical prep, MRSI preprocessing, registration, tissue maps, PVC, resampling, parcellation, regional extraction, connectivity, reports), with no per-step detail.
2 — also prints step-level detail (info/success/warning/error messages), including Chimera milestone markers (processing supra-region: ..., starting cortical parcellation fusion) so a single-threaded Chimera run — which can otherwise sit silently for 10-20+ minutes — shows visible progress.
3 — also lets ANTs, recon-all, and mri_synthseg print their own raw subprocess output instead of being captured, and prints the full traceback for a failed recording (at 0-2, a failure shows only a one-line summary on console — the full traceback is always written to that recording's logbook regardless of --verbose, see below).

Every console line is timestamped dd/mm-HH:MM, e.g. 07/07-14:35 [ PROC ] Tissue segmentation; pass -e TZ=<zone> to the container (or let mrsiprep-docker do it automatically) so these match the host clock instead of the container's default UTC.

A full-detail DEBUG log is always written to <out>/mrsiprep/logs/mrsiprep_<timestamp>.log, independent of the console --verbose level.

Per-recording logbook and provenance

Each subject/session additionally gets, inside its own output folder:

sub-*/ses-*/logs/sub-*_ses-*_desc-mrsiprep_log.txt — every timestamped console message for that recording only, useful when re-reading a single subject's history out of a large batch run's combined log. If the recording fails, this logbook always contains the full exception text and traceback (an ERROR/TRACE entry), regardless of --verbose — the console itself only shows the full traceback at --verbose 3, to keep batch-run output readable at lower verbosity levels.
sub-*/ses-*/reports/sub-*_ses-*_desc-provenance.json — the full run configuration, software versions, and a pipeline_trace array listing each of the 13 steps as RAN or SKIPPED with a one-line reason (e.g. "mode=mni-norm, requires parc-con", "--no-pvc", "--write-connectivity not set"). Because most steps are conditional on --mode, --tissue-backend, --no-pvc, and --write-connectivity, this is the authoritative record of what actually happened for a given recording, without having to re-derive it from the CLI flags used.

--nproc runs that many subject/session recordings concurrently; each one gets --nthreads ANTs/ITK threads. MRSIPrep coerces --nthreads down (never --nproc) if nproc * nthreads would exceed the host's CPU count, and shows the resulting thread budget (or the coercion warning) in the preflight summary before any recordings are processed — e.g. on a 32-core machine, --nproc 4 --nthreads 10 (40 threads) is coerced down to --nthreads 8 (32 threads).

mni-norm requires mri_synthseg and ANTs. parc-con with the default synthseg-fast tissue backend additionally requires FSL fast, PETPVC, and (for Chimera parcellation) recon-all and a valid FS_LICENSE.

Tissue backends (parc-con mode)

docker run --rm \
  -v /path/to/bids:/data:ro \
  -v /path/to/derivatives:/out \
  mrsiup/mrsiprep:cpu \
  /data /out participant \
  --participant-label S001 \
  --session-label V1 \
  --metabolites CrPCr,GluGln,GPCPCh,NAANAAG,Ins \
  --ref-met CrPCr \
  --mode parc-con \
  --tissue-backend existing

The existing backend reuses precomputed CAT12 tissue maps and requires:

a skull-stripped T1w derivative in derivatives/skullstrip,
the raw BIDS T1w acquisition,
a CAT12-style p3 CSF probability map in derivatives/cat12.

If p3 is missing, the recording fails. In batch processing, MRSIPrep logs the error and continues with the next subject/session.

Disable tissue segmentation and PVC entirely with --tissue-backend none (equivalent to also passing --no-pvc):

docker run --rm \
  -v /path/to/bids:/data:ro \
  -v /path/to/derivatives:/out \
  mrsiup/mrsiprep:cpu \
  /data /out participant \
  --participant-label S001 \
  --session-label V1 \
  --metabolites CrPCr,GluGln,GPCPCh,NAANAAG,Ins \
  --ref-met CrPCr \
  --mode parc-con \
  --tissue-backend none

Command-Line Arguments

Preprocess quantified whole-brain MRSI derivatives.

usage: mrsiprep [-h]
                [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [--session-label SESSION_LABEL [SESSION_LABEL ...]]
                [--participants PARTICIPANTS]
                [--bids-filter-file BIDS_FILTER_FILE] --metabolites
                METABOLITES
                [--quality-metrics {snr,linewidth,crlb} [{snr,linewidth,crlb} ...]]
                [--snr-min SNR_MIN] [--linewidth-max LINEWIDTH_MAX]
                [--crlb-max CRLB_MAX] [--t1-correction {none,literature}]
                [--t1-correction-water-status {uncorrected,corrected,unknown}]
                [--overwrite-t1corr] [--mode {mni-norm,parc-con,midas}]
                [--tissue-backend {synthseg-fast,existing,none}]
                [--registration-backend {ants,fsl,flirt-fnirt,flirt_fnirt,flirt/fnirt}]
                [--ants-mrsi-to-t1-transform ANTS_MRSI_TO_T1_TRANSFORM]
                [--ants-t1-to-mni-transform ANTS_T1_TO_MNI_TRANSFORM]
                [--fsl-mrsi-to-t1-dof {6,7,9,12}]
                [--fsl-mrsi-to-t1-init {flirt,usesqform}]
                [--fsl-t1-to-mni-dof {6,7,9,12}] [--fsl-cost FSL_COST]
                [--fsl-deformable] [--no-fsl-deformable]
                [--fsl-fnirt-warpres X Y Z]
                [--fsl-fnirt-lambda FSL_FNIRT_LAMBDA]
                [--normalization {simple,ants-syn,existing}]
                [--output-spaces OUTPUT_SPACES [OUTPUT_SPACES ...]]
                [--output-mrsi-t1w] [--mni-resolution MNI_RESOLUTION]
                [--registration-t1-target {brain-csf,brain,raw}]
                [--csf-pv-threshold CSF_PV_THRESHOLD] --ref-met REF_MET
                [--t1 T1_PATTERN] [--parcellation-mode {synthseg,chimera,mni}]
                [--synthseg-mode {fast,standard,robust}]
                [--chimera-scheme CHIMERA_SCHEME]
                [--chimera-scale CHIMERA_SCALE] [--chimera-grow CHIMERA_GROW]
                [--atlas ATLAS] [--custom-atlas CUSTOM_ATLAS]
                [--custom-atlas-lut CUSTOM_ATLAS_LUT]
                [--fs-subjects-dir FS_SUBJECTS_DIR] [--write-connectivity]
                [--connectivity-method {pearson,spearman,cosine,euclidean_distance}]
                [--connectivity-space {MRSI,T1w,MNI}]
                [--connectivity-n-perturbations CONNECTIVITY_N_PERTURBATIONS]
                [--connectivity-sigma-scale CONNECTIVITY_SIGMA_SCALE]
                [--connectivity-exclude-parcels CONNECTIVITY_EXCLUDE_PARCELS]
                [--connectivity-max-parcel-id CONNECTIVITY_MAX_PARCEL_ID]
                [--regional-summary {mean,median,weighted_mean}]
                [--transform TRANSFORM] [--no-filter]
                [--filter-fwhm-mm FILTER_FWHM_MM] [--spikepc SPIKEPC]
                [--spike-max-cluster-voxels SPIKE_MAX_CLUSTER_VOXELS]
                [--no-pvc] [--longitudinal] [--transform-spikemask]
                [--nthreads NTHREADS] [--nproc NPROC] [--work-dir WORK_DIR]
                [--overwrite] [--overwrite-filt] [--overwrite-seg]
                [--overwrite-pve] [--overwrite-t1-reg] [--overwrite-mni-reg]
                [--overwrite-transform] [--overwrite-chimera]
                [--config-preset CONFIG_PRESET] [--list-presets]
                [--validate-only] [--skip-file-integrity-check]
                [--check-external-libs] [--stop-on-first-crash]
                [--verbose {0,1,2,3}]
                bids_dir output_dir {participant}

Positional Arguments

bids_dir

The root folder of a BIDS valid dataset (sub-XXXXX folders at the top level).

output_dir

The output path for MRSIPrep derivatives and reports.

analysis_level

Possible choices: participant

Processing stage to be run, only 'participant' in the case of MRSIPrep (see BIDS-Apps specification).

Options for filtering BIDS queries

--participant-label

One or more subject labels to process, without the 'sub-' prefix (e.g. 'S001 S002'). Default: process every subject found under --bids-dir.

Default: []

--session-label

One or more session labels to process, without the 'ses-' prefix (e.g. 'V1 V2'). Default: process every session found for each selected subject.

Default: []

--participants

TSV/CSV subject-session list.

--bids-filter-file

Path to a JSON file of PyBIDS-style entity filters used to select among ambiguous input candidates, e.g. {"t1w": {"acquisition": "memprage", "run": "01"}} to force a specific T1w acquisition/run when a session has more than one. Only the "t1w" key is currently supported.

quality thresholds

--metabolites

Comma-separated metabolite names to process, e.g. 'CrPCr,GluGln,GPCPCh,NAANAAG,Ins'.

--quality-metrics

Possible choices: snr, linewidth, crlb

Which per-voxel quality maps are required inputs (any of 'snr', 'linewidth', 'crlb'); a recording missing one of the listed maps fails preflight validation. Default: all three. Maps that are present are always applied as voxel-inclusion thresholds regardless of this flag (see --snr-min/--linewidth-max/--crlb-max); this flag only controls whether their absence is an error.

Default: ['snr', 'linewidth', 'crlb']

--snr-min

Minimum per-voxel SNR to include a voxel, when 'snr' is in --quality-metrics.

Default: 4.0

--linewidth-max

Maximum per-voxel linewidth (FWHM) to include a voxel, when 'linewidth' is in --quality-metrics.

Default: 0.1

--crlb-max

Maximum per-voxel Cramér-Rao lower bound (%) to include a voxel, when 'crlb' is in --quality-metrics.

Default: 20.0

T1 saturation correction

--t1-correction

Possible choices: none, literature

Correct metabolite maps for incomplete T1 relaxation recovery (T1 saturation) using the steady-state spoiled-gradient-echo signal equation (default: 'none', no correction applied). 'literature' applies a single scalar correction factor per metabolite, derived from the acquisition's TR/flip angle (read from mrsinmrs.json) and a curated literature T1 value per metabolite per field strength (see mrsiprep/config/t1_literature.json). Requires a dataset-level mrsinmrs.json with unambiguous TR/FlipAngle/MagneticFieldStrength entries -- fails loudly, per-recording, if these or a requested metabolite's T1 value are missing, rather than silently skipping or substituting. A future 'voxelwise' mode (per-voxel correction using a measured B1+ map) is planned but not yet implemented; mrsiprep does not currently ingest B1+ maps.

Default: 'none'

--t1-correction-water-status

Possible choices: uncorrected, corrected, unknown

Whether the input metabolite maps are already water-referenced/water-T1-corrected upstream (e.g. by the quantification pipeline's own internal water-scaling step). 'unknown' (default, conservative) applies the metabolite-T1-only correction and flags the ambiguity in the QC/provenance output. Ignored when --t1-correction none.

Default: 'unknown'

--overwrite-t1corr

Force recomputation of T1-corrected maps even if cached outputs exist.

Default: False

Options for performing only a subset of the workflow

--mode, --processing-mode

Possible choices: mni-norm, parc-con, midas

Processing mode. 'midas' runs a MIDAS-faithful pipeline (Maudsley et al. 2006): fuzzy c-means tissue segmentation, PSF-convolved tissue fractions, rigid MRSI->T1 registration, and per-parcel Eq. 4 pure-GM/pure-WM regression instead of PETPVC.

Default: 'mni-norm'

--tissue-backend

Possible choices: synthseg-fast, existing, none

Tissue segmentation backend for PVC. 'none' disables tissue segmentation and PVC entirely. Ignored in --mode midas, which always uses its own fuzzy c-means segmentation.

Default: 'synthseg-fast'

Specific options for registrations

--registration-backend

Possible choices: ants, fsl, flirt-fnirt, flirt_fnirt, flirt/fnirt

Registration toolchain. 'ants' is the default and generally most accurate (rigid+affine+SyN). 'fsl'/'flirt-fnirt' uses FLIRT+FNIRT (deformable) for MRSI-to-T1w by default; pass --no-fsl-deformable for FLIRT-only (faster, less accurate).

Default: 'ants'

--ants-mrsi-to-t1-transform

ANTs transform preset/code for MRSI-to-T1w registration. Default matches the previous implementation: 'sr'.

Default: 'sr'

--ants-t1-to-mni-transform

ANTs transform preset/code for T1w-to-MNI registration. Default matches the previous implementation: 's'.

Default: 's'

--fsl-mrsi-to-t1-dof

Possible choices: 6, 7, 9, 12

FLIRT degrees of freedom for MRSI-to-T1w registration: 6=rigid, 7=rigid+global scale, 9=rigid+per-axis scale, 12=full affine. Default 6 (rigid), appropriate for the low-resolution MRSI reference map.

Default: 6

--fsl-mrsi-to-t1-init

Possible choices: flirt, usesqform

FSL MRSI-to-T1w initialization. 'usesqform' applies the NIfTI qform/sform geometry with FLIRT and no further optimization. 'flirt' (default) seeds FLIRT from that same qform/sform frame, then runs a local (no-search) optimization from it -- FLIRT's own unrestricted global search was found to reliably diverge on MRSI-reference-vs-T1w registration and is not offered.

Default: 'flirt'

--fsl-t1-to-mni-dof

Possible choices: 6, 7, 9, 12

FLIRT degrees of freedom for T1w-to-MNI registration: 6=rigid, 7=rigid+global scale, 9=rigid+per-axis scale, 12=full affine. Default 12 (full affine), appropriate for inter-subject spatial normalization.

Default: 12

--fsl-cost

FLIRT cost function for FSL registrations. Default changed from FLIRT's own 'mutualinfo' default to 'corratio': mutualinfo was found to diverge on the small, low-contrast MRSI reference maps used for MRSI-to-T1w registration.

Default: 'corratio'

--fsl-deformable

Add an FNIRT deformable stage after FLIRT for the fsl MRSI-to-T1w registration, to more closely mimic ANTs' default SyN warp. On by default when --registration-backend fsl is selected (confirmed to give consistently better MRSI-brainmask/T1w-brain overlap than FLIRT-only across a 3T and a 7T subject, see experiments/registration_backend_benchmark.py); pass --no-fsl-deformable for FLIRT-only (faster, seconds instead of several minutes per subject). Has no effect on --registration-backend ants or on --mode midas (rigid-only by design).

Default: True

--no-fsl-deformable

Use FLIRT-only for the fsl MRSI-to-T1w registration (no FNIRT deformable stage). See --fsl-deformable.

Default: True

--fsl-fnirt-warpres

FNIRT --warpres (B-spline control-point grid spacing, mm) for the fsl-deformable MRSI-to-T1w stage. Default: auto-computed as ~2x the MRSI reference image's own native voxel size per axis, floored at 6mm (a higher-resolution MRSI acquisition can support a finer deformation grid without just fitting noise; validated at warpres=10mm for 5mm MRSI data -- see mrsiprep.interfaces.fsl.default_fnirt_warpres). Pass three values (e.g. --fsl-fnirt-warpres 6 6 6) to override.

--fsl-fnirt-lambda

FNIRT --lambda regularization-weight schedule for the fsl-deformable MRSI-to-T1w stage.

Default: '300,200,150,150'

--normalization

Possible choices: simple, ants-syn, existing

Legacy T1w-to-MNI normalization strategy (superseded by --registration-backend for new code; kept for backward compatibility). 'simple' registers via the backend selected by --registration-backend. 'ants-syn' forces ANTs SyN regardless of --registration-backend. 'existing' reuses a previously computed T1w-to-MNI transform instead of recomputing it.

Default: 'simple'

--output-spaces

One or more target spaces to resample final MRSI derivatives into. Accepts case-insensitive aliases: 'mni'/'mni152'/'mni152nlin2009casym' (MNI152NLin2009cAsym, default), 't1'/'t1w' (T1w space, equivalent to also passing --output-mrsi-t1w), 'mrsi'/'orig' (native MRSI grid). See docs/usage_normalization.md.

Default: ['MNI152NLin2009cAsym']

--output-mrsi-t1w

Also resample all metabolite (and CRLB/SNR/FWHM/spikemask) maps into T1w space as permanent derivatives (mrsi-t1w/). Off by default; the registration-overview report generates its own single reference-metabolite T1w map in the work directory regardless of this flag.

Default: False

--mni-resolution

MNI template resolution: 'origres' (MRSI native, default -- avoids implying spatial precision the MRSI acquisition never had, and matches the resolution mrsiprep's own spatial-smoothness benchmark evaluates), 't1wres' (T1w native), or '<N>mm' (e.g. '2mm').

Default: 'origres'

--registration-t1-target

Possible choices: brain-csf, brain, raw

Which T1w image registration targets. 'brain' registers directly to the skull-stripped T1w (default for --mode mni-norm/midas). 'brain-csf' re-adds the CSF compartment to the skull-stripped image before registering, so CSF-adjacent MRSI signal isn't clipped at the brain-only boundary (default for --mode parc-con; requires a CAT12 p3 CSF map). 'raw' registers to the original, non-skull-stripped T1w with no fixed mask.

--csf-pv-threshold

CSF partial-volume probability threshold used when building the 'brain-csf' registration target: voxels with CAT12 p3 CSF probability at or above this value are added back to the skull-stripped brain image.

Default: 0.95

--ref-met

Reference metabolite map used to build the MRSI registration target, e.g. 'CrPCr'.

--t1

BIDS entity/suffix pattern used to locate the skull-stripped T1w derivative for each recording (e.g. 'desc-brain_T1w', or 'acq-mprage_T1w' to select among multiple raw T1w acquisitions -- see --bids-filter-file for finer-grained disambiguation).

Default: 'desc-brain_T1w'

parcellation

--parcellation-mode

Possible choices: synthseg, chimera, mni

Parcellation scheme. 'synthseg' uses SynthSeg's own cortical/subcortical labels (default for --mode mni-norm/midas; the only mode compatible with mni-norm). 'chimera' runs the Chimera multi-atlas fusion tool live, combining several region-specific atlases per --chimera-scheme (default for --mode parc-con; requires FreeSurfer recon-all and FS_LICENSE). 'mni' warps a pre-bundled or custom MNI-space atlas (see --atlas) into subject space instead of running Chimera.

--synthseg-mode

Possible choices: fast, standard, robust

mri_synthseg inference mode, trading speed for accuracy/robustness: 'fast' (quickest, lower-memory), 'standard', or 'robust' (default; most accurate but the most memory-hungry -- can exceed 16GB RAM on some inputs, consider 'fast' on memory-constrained runners).

Default: 'robust'

--chimera-scheme

10-character Chimera parcellation code, one letter per supra-region in order: cortex, basal ganglia, thalamus, amygdala, hippocampus, hypothalamus, cerebellum, brainstem, gyral WM, WM. Default 'LFMIHIFIFF' = Lausanne cortex, FreeSurfer/Aseg subcortex/cerebellum/WM, MIALThalParc thalamus, FSAmygHippoParc amygdala, HBT hippocampus, FSHypoThalParc hypothalamus, FSBrainStemParc brainstem. See the Chimera documentation for the full per-position letter set.

Default: 'LFMIHIFIFF'

--chimera-scale

Lausanne2018 cortical parcellation granularity (1-5; higher = more, finer parcels), used only when --chimera-scheme's cortex position is 'L'. Accepts a bare integer or 'scaleN'.

Default: 3

--chimera-grow

Distance (mm) to grow cortical/subcortical gray-matter parcel labels into adjacent white matter when building the gyral-WM parcellation. Set to 0 to disable growing.

Default: 2

--atlas

Atlas used when --parcellation-mode mni. One of: a bundled atlas name (see mrsiprep.parcellation.atlas_registry.available_bundled_atlases(), e.g. 'chimera-LFMIHIFIS-3'); 'custom' (requires --custom-atlas and --custom-atlas-lut); 'schaefer<N>' for the Schaefer 2018 N-parcel cortical atlas (e.g. 'schaefer400'); or 'mist197'/'mist-197' for the BASC multiscale atlas at scale 197.

Default: 'chimera-LFMIHIFIS-3'

--custom-atlas

Path to a custom MNI-space atlas NIfTI (integer parcel-ID label image). Requires --atlas custom and --custom-atlas-lut.

--custom-atlas-lut

Path to the lookup table (TSV) for --custom-atlas. Must have a 'parcel_id' column (or legacy 'index') matching the label image's integer values; optional 'parcel_name' ('name') and 'hemisphere' columns (hemisphere is inferred from the name if omitted).

--fs-subjects-dir

FreeSurfer SUBJECTS_DIR to reuse pre-existing recon-all output from, instead of running recon-all inside MRSIPrep. Only relevant with --parcellation-mode chimera.

connectivity

--write-connectivity

Build and write a regional metabolic connectivity (similarity) matrix on top of the regional metabolic profiles that parc-con mode already computes unconditionally, using CRLB-scaled noise perturbations to estimate edge similarity between parcels' metabolite profiles.

Default: False

--connectivity-method

Possible choices: pearson, spearman, cosine, euclidean_distance

Similarity/distance measure between parcels' perturbed metabolite profiles used to build connectivity edges: 'pearson' or 'spearman' correlation, 'cosine' similarity, or 'euclidean_distance'.

Default: 'spearman'

--connectivity-space

Possible choices: MRSI, T1w, MNI

Space the regional metabolite profiles are extracted in before building the connectivity matrix: native MRSI grid (default), T1w space, or MNI space.

Default: 'MRSI'

--connectivity-n-perturbations

Number of CRLB-scaled noise perturbations per metabolite used to build the connectivity similarity matrix.

Default: 50

--connectivity-sigma-scale

Scale factor applied to the CRLB-derived noise sigma when perturbing metabolite maps for connectivity.

Default: 2.0

--connectivity-exclude-parcels

Comma-separated substrings; parcels whose name contains any of them are excluded from the connectivity matrix (e.g. 'wm-lh,cer-').

--connectivity-max-parcel-id

Exclude parcels whose label/ID is greater than or equal to this value from the connectivity matrix.

--regional-summary

Possible choices: mean, median, weighted_mean

How each parcel's per-voxel metabolite values are summarized into a single regional value: 'mean', 'median', or 'weighted_mean' (SNR-weighted average; falls back to an unweighted mean if no SNR map is available for that recording).

Default: 'mean'

Workflow configuration

--transform

Legacy output transform override; prefer --output-spaces.

Default: ''

--no-filter

Disable biharmonic spike filtering (enabled by default in every processing mode).

Default: False

--filter-fwhm-mm

Smoothing FWHM (mm) used when splicing repaired biharmonic-filter voxels back in. Default: derived from the native MRSI voxel size (mean voxel dimension x sqrt(2)).

--spikepc

Percentile threshold (0-100) above which a voxel is flagged as a spike for biharmonic filtering/repair. Ignored when --no-filter is set.

Default: 99.0

--spike-max-cluster-voxels

A connected cluster of spike-thresholded voxels larger than this is treated as real focal signal (e.g. a genuine metabolic abnormality) and left unfiltered, rather than median-repaired/biharmonic-inpainted like an isolated noise spike. Default: derived from the native MRSI voxel size (6 voxels at ~5.0mm/3T-like resolution, 9 voxels at ~3.4mm/7T-like resolution, empirically the 90th-percentile spike-cluster size measured on real acquisitions at each resolution). Set to a very large number to disable cluster-size filtering (every above-threshold voxel is filtered regardless of cluster size, matching pre-existing behavior).

--no-pvc

Skip partial-volume correction (PETPVC) entirely, even in --mode parc-con. Equivalent to --tissue-backend none, except tissue segmentation itself still runs (its maps are just not used for PVC).

Default: False

--longitudinal

Build one unbiased ANTs template across a subject's sessions and register it to MNI once, composing (session-to-template)+(template-to-MNI) instead of registering each session directly to MNI. No-op for subjects with a single session. Requires --registration-backend ants.

Default: False

--transform-spikemask

Also transform per-metabolite spike masks into T1w/MNI space.

Default: False

--nthreads

ANTs/ITK thread count per subject/session process.

Default: 16

--nproc

Number of subject/session recordings to process in parallel. Each parallel process gets --nthreads threads; if nproc*nthreads exceeds the available CPU count, --nthreads is coerced down and a warning is shown at startup.

Default: 1

--work-dir, -w

Directory for the Nipype engine's node cache and scratch/intermediate files. Default: <output_dir>/work. Safe to delete between runs to reclaim space; permanent derivatives under <output_dir>/mrsiprep/ are unaffected, though deleting it invalidates the rerun-skip cache for already-processed recordings.

overwrite/recompute

--overwrite

Force recompute of every cached step for selected recordings, ignoring the Nipype node cache entirely. Equivalent to passing all of the --overwrite-* flags below at once.

Default: False

--overwrite-filt

Force recompute of biharmonic spike filtering, even if cached filtered maps exist.

Default: False

--overwrite-seg

Force recompute of tissue segmentation (SynthSeg brain extraction + dseg/probseg), even if cached outputs exist.

Default: False

--overwrite-pve

Force recompute of partial-volume correction (PETPVC), even if cached corrected maps exist.

Default: False

--overwrite-t1-reg

Force recompute of MRSI-to-T1w registration, even if a cached transform exists.

Default: False

--overwrite-mni-reg

Force recompute of T1w-to-MNI registration, even if a cached transform exists.

Default: False

--overwrite-transform

Force recompute of resampling MRSI maps through existing transforms into output spaces, even if cached resampled maps exist. Does not itself force-recompute the transforms -- see --overwrite-t1-reg/--overwrite-mni-reg.

Default: False

--overwrite-chimera

Force re-run Chimera parcellation even if the output dseg file already exists.

Default: False

Other options

--config-preset

Load processing-parameter defaults from a named built-in preset (see --list-presets) or a path to a custom preset JSON file with the same shape. Explicit CLI flags always override preset values. Presets reproduce the exact parameters of a published study; the report's Citations section credits the source.

--list-presets

Print available built-in --config-preset names and their source citation, then exit.

Default: False

--validate-only

Check selected subject/session inputs and exit without running preprocessing.

Default: False

--skip-file-integrity-check

Skip forcing a full read of T1w/MRSI input files during preflight validation (existence-only checks instead). By default every run force-reads these files first and skips any recording with a missing or corrupt/truncated input.

Default: False

--check-external-libs

Verify required external binaries are available and exit.

Default: False

--stop-on-first-crash

Abort the whole run immediately on the first recording failure, instead of logging it and continuing with the rest of the batch.

Default: False

--verbose, -v

Possible choices: 0, 1, 2, 3

0=subject start/finish only, 1=+processing steps, 2=+step details, 3=+raw ANTs/recon-all/mri_synthseg output.

Default: 1

By default, when a subject/session has more than one candidate raw T1w acquisition, MRSIPrep picks one heuristically (preferring acq-memprage/mprage/mp2rage and run-01). --bids-filter-file lets you override that choice explicitly:

{"t1w": {"acquisition": "memprage", "run": "01"}}

Only the "t1w" key is currently supported (any other top-level key is rejected with an error rather than silently ignored). Filter values use either MRSIPrep's short BIDS entity names (acq, run, ses, sub) or the long PyBIDS-style names shown above (acquisition, run, session, subject) interchangeably. A value of null requires the entity to be absent from the filename.

See MNI Normalization Usage for --output-spaces and --output-mrsi-t1w, and Longitudinal (Subject-Template) Normalization for --longitudinal.

Output layout

<out>/mrsiprep/sub-*/ses-*/mrsi/orig/          native/imported-grid MRSI signal maps only
<out>/mrsiprep/sub-*/ses-*/mrsi/orig-t1corr/   T1-saturation-corrected native-grid signal maps
                                                (opt-in, --t1-correction literature)
<out>/mrsiprep/sub-*/ses-*/mrsi/orig-pvc/      PVC-corrected native-grid signal maps only
<out>/mrsiprep/sub-*/ses-*/mrsi/t1w/           T1w-aligned MRSI signal maps only (opt-in, --output-mrsi-t1w)
<out>/mrsiprep/sub-*/ses-*/mrsi/mni/           MNI-normalized MRSI signal maps only
<out>/mrsiprep/sub-*/ses-*/mrsi/parcel/        parc-con mode metabolite profile NPZ files
<out>/mrsiprep/sub-*/ses-*/anat/               raw T1w tissue files, brainCSF/registration inputs
<out>/mrsiprep/sub-*/ses-*/anat/synthseg/      SynthSeg brain/dseg outputs and parcelwise QC tables
<out>/mrsiprep/sub-*/ses-*/confounds/          every quantity that encodes a preprocessing assumption
                                                rather than signal itself, one file per space/metabolite
                                                (space-* entity in the filename): CRLB, SNR, FWHM/linewidth,
                                                spike masks, QC masks, brain mask, GM/WM/CSF tissue probsegs,
                                                T1-correction summary (opt-in, --t1-correction literature)
<out>/mrsiprep/sub-*/ses-*/transforms/         ANTs MRSI→T1w and T1w→MNI transforms
<out>/mrsiprep/sub-*/ses-*/reports/coverage/   subject HTML report + parcelwise coverage/CRLB figures
<out>/mrsiprep/sub-*/ses-*/reports/qc-reports/ per-step QC HTML reports and figures
<out>/mrsiprep/sub-*/ses-*/reports/            provenance JSON (config, software versions, pipeline_trace)
<out>/mrsiprep/sub-*/ses-*/logs/                per-recording timestamped logbook
<out>/mrsiprep/logs/                           full-detail timestamped run logs (independent of --verbose)
<out>/chimera-atlases/sub-*/ses-*/anat/        raw Chimera atlas outputs (one scheme/scale per file)
<out>/work/                                    Nipype node cache and other scratch files (--work-dir)

BIDS import utilities

These run on the host, not inside the container:

mrsiprep-import /source/folder /path/to/bids --subject S001 --session V1
mrsiprep-import-gui

The import helpers preserve the MRSI-Metabolic-Connectome derivative layout: derivatives/mrsi-orig, derivatives/cat12, and derivatives/skullstrip.

Limitations and scope

MRSIPrep is a BIDS App for whole-brain quantified MRSI derivatives, not a general-purpose neuroimaging pipeline. In particular:

It has no fieldmap/BOLD/functional-MRI handling — those are out of scope entirely, since the inputs are already-quantified MRSI metabolite maps rather than raw k-space or functional time series.
Registration can use ANTs (default, rigid+affine+SyN, generally most accurate) or FSL via --registration-backend fsl (FLIRT+FNIRT deformable by default; pass --no-fsl-deformable for FLIRT-only, faster but less accurate); there is no TemplateFlow catalog, and normalization targets are limited to MNI152 (MNI152NLin2009cAsym) plus native T1w/MRSI space — see MNI Normalization Usage.
--longitudinal builds one ANTs subject-template across sessions (requires --registration-backend ants) — see Longitudinal (Subject-Template) Normalization; it does not otherwise change per-session processing, and assumes reasonably stable anatomy across a subject's sessions.
Chimera parcellation and the synthseg-fast tissue backend require FreeSurfer, FSL, and a valid FS_LICENSE; mni-norm mode does not.

Troubleshooting

Start with a full-detail run log at <out>/mrsiprep/logs/mrsiprep_<timestamp>.log, and the per-recording logbook at sub-*/ses-*/logs/sub-*_ses-*_desc-mrsiprep_log.txt for a single subject/session's history out of a larger batch (see "Verbosity, logging, and provenance" above).
Re-run the same recording with --verbose 2 (step-level detail) or --verbose 3 (raw ANTs/recon-all/mri_synthseg subprocess output) to see exactly where a failure occurs.
--validate-only checks all selected subject/session inputs before any expensive processing starts — run it first when troubleshooting a batch.
--check-external-libs verifies required external binaries (ANTs/FSL/FreeSurfer/PETPVC/Chimera, as applicable to the selected mode) are present and exits.
By default a batch run logs a recording's failure and continues with the rest; pass --stop-on-first-crash to abort immediately instead, which is often easier when debugging a single problematic recording.
Report issues at github.com/MRSI-Psychosis-UP/MRSIPrep/issues.