mrsiprep 0.1.0__py3-none-any.whl

mrsiprep/cli/parser.py

@@ -0,0 +1,294 @@
+"""CLI parser for MRSIPrep."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from mrsiprep.config.defaults import QUALITY_DEFAULTS
+from mrsiprep.config.settings import MRSIPrepConfig
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mrsiprep", description="Preprocess quantified whole-brain MRSI derivatives.")
+    parser.add_argument("bids_dir", type=Path, help="The root folder of a BIDS valid dataset (sub-XXXXX folders at the top level).")
+    parser.add_argument("output_dir", type=Path, help="The output path for MRSIPrep derivatives and reports.")
+    parser.add_argument(
+        "analysis_level",
+        choices=["participant"],
+        help="Processing stage to be run, only 'participant' in the case of MRSIPrep (see BIDS-Apps specification).",
+    )
+
+    selection = parser.add_argument_group("Options for filtering BIDS queries")
+    selection.add_argument("--participant-label", nargs="+", default=[])
+    selection.add_argument("--session-label", nargs="+", default=[])
+    selection.add_argument("--participants", type=Path, default=None, help="TSV/CSV subject-session list.")
+    selection.add_argument(
+        "--bids-filter-file",
+        type=Path,
+        default=None,
+        help="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 = parser.add_argument_group("quality thresholds")
+    quality.add_argument(
+        "--metabolites",
+        type=_parse_comma_list,
+        required=True,
+        help="Comma-separated metabolite names to process, e.g. 'CrPCr,GluGln,GPCPCh,NAANAAG,Ins'.",
+    )
+    quality.add_argument("--quality-metrics", nargs="+", default=["snr", "linewidth", "crlb"])
+    quality.add_argument("--snr-min", type=float, default=QUALITY_DEFAULTS["snr_min"])
+    quality.add_argument("--linewidth-max", type=float, default=QUALITY_DEFAULTS["linewidth_max"])
+    quality.add_argument("--crlb-max", type=float, default=QUALITY_DEFAULTS["crlb_max"])
+
+    processing = parser.add_argument_group("Options for performing only a subset of the workflow")
+    processing.add_argument(
+        "--mode",
+        "--processing-mode",
+        dest="processing_mode",
+        choices=["mni-norm", "parc-con", "midas"],
+        default="mni-norm",
+        help="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.",
+    )
+    processing.add_argument(
+        "--tissue-backend",
+        choices=["synthseg-fast", "existing", "none"],
+        default="synthseg-fast",
+        help="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.",
+    )
+
+    registration = parser.add_argument_group("Specific options for registrations")
+    registration.add_argument(
+        "--registration-backend",
+        choices=["ants", "fsl", "flirt-fnirt", "flirt_fnirt", "flirt/fnirt"],
+        default="ants",
+        help="Registration toolchain. 'ants' is the default; 'fsl'/'flirt-fnirt' uses FLIRT affine registration "
+        "(no deformable stage -- FNIRT is not implemented).",
+    )
+    registration.add_argument(
+        "--ants-mrsi-to-t1-transform",
+        default="sr",
+        help="ANTs transform preset/code for MRSI-to-T1w registration. Default matches the previous implementation: 'sr'.",
+    )
+    registration.add_argument(
+        "--ants-t1-to-mni-transform",
+        default="s",
+        help="ANTs transform preset/code for T1w-to-MNI registration. Default matches the previous implementation: 's'.",
+    )
+    registration.add_argument("--fsl-mrsi-to-t1-dof", type=int, choices=[6, 7, 9, 12], default=6)
+    registration.add_argument(
+        "--fsl-mrsi-to-t1-init",
+        choices=["flirt", "usesqform"],
+        default="flirt",
+        help="FSL MRSI-to-T1w initialization. 'usesqform' applies the NIfTI qform/sform geometry with FLIRT.",
+    )
+    registration.add_argument("--fsl-t1-to-mni-dof", type=int, choices=[6, 7, 9, 12], default=12)
+    registration.add_argument("--fsl-cost", default="mutualinfo", help="FLIRT cost function for FSL registrations.")
+    registration.add_argument("--normalization", choices=["simple", "ants-syn", "existing"], default="simple")
+    registration.add_argument("--output-spaces", nargs="+", default=["MNI152NLin2009cAsym"])
+    registration.add_argument(
+        "--output-mrsi-t1w",
+        action="store_true",
+        help="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.",
+    )
+    registration.add_argument(
+        "--mni-resolution",
+        default="t1wres",
+        help="MNI template resolution: 'origres' (MRSI native), 't1wres' (T1w native), or '<N>mm' (e.g. '2mm').",
+    )
+    registration.add_argument("--registration-t1-target", choices=["brain-csf", "brain", "raw"], default=None)
+    registration.add_argument("--csf-pv-threshold", type=float, default=0.95)
+    registration.add_argument(
+        "--ref-met",
+        required=True,
+        help="Reference metabolite map used to build the MRSI registration target, e.g. 'CrPCr'.",
+    )
+    registration.add_argument("--t1", dest="t1_pattern", default="desc-brain_T1w")
+
+    parcellation = parser.add_argument_group("parcellation")
+    parcellation.add_argument("--parcellation-mode", choices=["synthseg", "chimera", "mni"], default=None)
+    parcellation.add_argument("--synthseg-mode", choices=["fast", "standard", "robust"], default="robust")
+    parcellation.add_argument("--chimera-scheme", default="LFMIHIFIFF")
+    parcellation.add_argument("--chimera-scale", type=_parse_scale, default=3)
+    parcellation.add_argument("--chimera-grow", type=int, default=2)
+    parcellation.add_argument("--atlas", default="chimera-LFMIHIFIS-3")
+    parcellation.add_argument("--custom-atlas", type=Path, default=None)
+    parcellation.add_argument("--custom-atlas-lut", type=Path, default=None)
+    parcellation.add_argument("--fs-subjects-dir", type=Path, default=None)
+
+    connectivity = parser.add_argument_group("connectivity")
+    connectivity.add_argument("--write-connectivity", action="store_true")
+    connectivity.add_argument("--connectivity-method", choices=["pearson", "spearman", "cosine", "euclidean_distance"], default="spearman")
+    connectivity.add_argument("--connectivity-space", choices=["MRSI", "T1w", "MNI"], default="MRSI")
+    connectivity.add_argument("--connectivity-n-perturbations", type=int, default=50, help="Number of CRLB-scaled noise perturbations per metabolite used to build the connectivity similarity matrix.")
+    connectivity.add_argument("--connectivity-sigma-scale", type=float, default=2.0, help="Scale factor applied to the CRLB-derived noise sigma when perturbing metabolite maps for connectivity.")
+    connectivity.add_argument(
+        "--connectivity-exclude-parcels",
+        default=None,
+        help="Comma-separated substrings; parcels whose name contains any of them are excluded from the connectivity matrix (e.g. 'wm-lh,cer-').",
+    )
+    connectivity.add_argument(
+        "--connectivity-max-parcel-id",
+        type=int,
+        default=None,
+        help="Exclude parcels whose label/ID is greater than or equal to this value from the connectivity matrix.",
+    )
+    connectivity.add_argument("--regional-summary", choices=["mean", "median", "weighted_mean"], default="mean")
+
+    processing_control = parser.add_argument_group("Workflow configuration")
+    processing_control.add_argument("--transform", default="", help="Legacy output transform override; prefer --output-spaces.")
+    processing_control.add_argument("--no-filter", action="store_true", help="Disable biharmonic spike filtering (enabled by default in every processing mode).")
+    processing_control.add_argument(
+        "--filter-fwhm-mm",
+        type=float,
+        default=None,
+        help="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)).",
+    )
+    processing_control.add_argument("--spikepc", type=float, default=99.0)
+    processing_control.add_argument("--no-pvc", action="store_true")
+    processing_control.add_argument(
+        "--longitudinal",
+        action="store_true",
+        help="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.",
+    )
+    processing_control.add_argument("--transform-spikemask", action="store_true", help="Also transform per-metabolite spike masks into T1w/MNI space.")
+    processing_control.add_argument("--nthreads", type=int, default=16, help="ANTs/ITK thread count per subject/session process.")
+    processing_control.add_argument(
+        "--nproc",
+        type=int,
+        default=1,
+        help="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.",
+    )
+    processing_control.add_argument("--work-dir", "-w", type=Path, default=None)
+
+    overwrite = parser.add_argument_group("overwrite/recompute")
+    overwrite.add_argument("--overwrite", action="store_true")
+    overwrite.add_argument("--overwrite-filt", action="store_true")
+    overwrite.add_argument("--overwrite-seg", action="store_true", help="Force recompute of tissue segmentation (SynthSeg brain extraction + dseg/probseg), even if cached outputs exist.")
+    overwrite.add_argument("--overwrite-pve", action="store_true")
+    overwrite.add_argument("--overwrite-t1-reg", action="store_true")
+    overwrite.add_argument("--overwrite-mni-reg", action="store_true")
+    overwrite.add_argument("--overwrite-transform", action="store_true")
+    overwrite.add_argument("--overwrite-chimera", action="store_true", help="Force re-run Chimera parcellation even if the output dseg file already exists.")
+
+    runtime = parser.add_argument_group("Other options")
+    runtime.add_argument("--validate-only", action="store_true", help="Check selected subject/session inputs and exit without running preprocessing.")
+    runtime.add_argument(
+        "--skip-file-integrity-check",
+        action="store_true",
+        help="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.",
+    )
+    runtime.add_argument("--check-external-libs", action="store_true", help="Verify required external binaries are available and exit.")
+    runtime.add_argument(
+        "--stop-on-first-crash",
+        action="store_true",
+        help="Abort the whole run immediately on the first recording failure, instead of logging it and continuing with the rest of the batch.",
+    )
+    runtime.add_argument(
+        "--verbose",
+        "-v",
+        type=int,
+        choices=[0, 1, 2, 3],
+        default=1,
+        help="0=subject start/finish only, 1=+processing steps, 2=+step details, 3=+raw ANTs/recon-all/mri_synthseg output.",
+    )
+    return parser
+
+
+def parse_args(argv: list[str] | None = None) -> MRSIPrepConfig:
+    args = build_parser().parse_args(argv)
+    return MRSIPrepConfig(
+        bids_dir=args.bids_dir,
+        output_dir=args.output_dir,
+        analysis_level=args.analysis_level,
+        participant_label=args.participant_label,
+        session_label=args.session_label,
+        participants_file=args.participants,
+        bids_filter_file=args.bids_filter_file,
+        metabolites=args.metabolites,
+        quality_metrics=args.quality_metrics,
+        snr_min=args.snr_min,
+        linewidth_max=args.linewidth_max,
+        crlb_max=args.crlb_max,
+        processing_mode=args.processing_mode,
+        tissue_backend=args.tissue_backend,
+        registration_backend=args.registration_backend,
+        ants_mrsi_to_t1_transform=args.ants_mrsi_to_t1_transform,
+        ants_t1_to_mni_transform=args.ants_t1_to_mni_transform,
+        fsl_mrsi_to_t1_dof=args.fsl_mrsi_to_t1_dof,
+        fsl_mrsi_to_t1_init=args.fsl_mrsi_to_t1_init,
+        fsl_t1_to_mni_dof=args.fsl_t1_to_mni_dof,
+        fsl_cost=args.fsl_cost,
+        normalization=args.normalization,
+        output_spaces=args.output_spaces,
+        output_mrsi_t1w=args.output_mrsi_t1w,
+        mni_resolution=args.mni_resolution,
+        registration_t1_target=args.registration_t1_target,
+        csf_pv_threshold=args.csf_pv_threshold,
+        ref_met=args.ref_met,
+        t1_pattern=args.t1_pattern,
+        parcellation_mode=args.parcellation_mode,
+        synthseg_mode=args.synthseg_mode,
+        chimera_scheme=args.chimera_scheme,
+        chimera_scale=args.chimera_scale,
+        chimera_grow=args.chimera_grow,
+        atlas=args.atlas,
+        custom_atlas=args.custom_atlas,
+        custom_atlas_lut=args.custom_atlas_lut,
+        fs_subjects_dir=args.fs_subjects_dir,
+        write_connectivity=args.write_connectivity,
+        connectivity_method=args.connectivity_method,
+        connectivity_space=args.connectivity_space,
+        connectivity_n_perturbations=args.connectivity_n_perturbations,
+        connectivity_sigma_scale=args.connectivity_sigma_scale,
+        connectivity_exclude_parcels=args.connectivity_exclude_parcels,
+        connectivity_max_parcel_id=args.connectivity_max_parcel_id,
+        regional_summary=args.regional_summary,
+        transform=args.transform,
+        filter_biharmonic=not args.no_filter,
+        filter_fwhm_mm=args.filter_fwhm_mm,
+        spike_percentile=args.spikepc,
+        no_pvc=args.no_pvc,
+        longitudinal=args.longitudinal,
+        transform_spikemask=args.transform_spikemask,
+        nthreads=args.nthreads,
+        nproc=args.nproc,
+        work_dir=args.work_dir,
+        overwrite=args.overwrite,
+        overwrite_filt=args.overwrite_filt,
+        overwrite_seg=args.overwrite_seg,
+        overwrite_pve=args.overwrite_pve,
+        overwrite_t1_reg=args.overwrite_t1_reg,
+        overwrite_mni_reg=args.overwrite_mni_reg,
+        overwrite_transform=args.overwrite_transform,
+        overwrite_chimera=args.overwrite_chimera,
+        validate_only=args.validate_only,
+        skip_file_integrity_check=args.skip_file_integrity_check,
+        check_external_libs=args.check_external_libs,
+        stop_on_first_crash=args.stop_on_first_crash,
+        verbose=args.verbose,
+    )
+
+
+def _parse_comma_list(value: str) -> list[str]:
+    return [item.strip() for item in str(value).split(",") if item.strip()]
+
+
+def _parse_scale(value) -> int:
+    text = str(value)
+    if text.startswith("scale"):
+        text = text[len("scale") :]
+    return int(text)

mrsiprep/cli/run.py

@@ -0,0 +1,48 @@
+"""MRSIPrep command entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from mrsiprep.cli.parser import parse_args
+from mrsiprep.utils.banner import print_banner
+from mrsiprep.utils.debug import Debug
+from mrsiprep.utils.logging import setup_logging
+from mrsiprep.utils.provenance import check_external_software
+from mrsiprep.workflows.participant import run_participant_workflow, validate_participant_inputs
+
+
+def main(argv: list[str] | None = None) -> int:
+    print_banner()
+    config = parse_args(argv)
+    logger = setup_logging(config.verbose, log_dir=config.logs_dir)
+    nproc, nthreads, cpu_warning = config.resolve_cpu_budget()
+    if cpu_warning:
+        logger.warning(cpu_warning)
+    config.nproc, config.nthreads = nproc, nthreads
+    if config.analysis_level != "participant":
+        logger.error("Only participant analysis level is currently supported.")
+        return 2
+    if config.check_external_libs:
+        debug = Debug(verbose=config.verbose)
+        ok = check_external_software(debug, config)
+        return 0 if ok else 1
+    if config.validate_only:
+        statuses = validate_participant_inputs(config)
+        failed = [status for status in statuses if status.status != "success"]
+        succeeded = [status for status in statuses if status.status == "success"]
+        logger.info("MRSIPrep input validation finished: %d valid, %d invalid", len(succeeded), len(failed))
+        for status in failed:
+            logger.error("INVALID sub-%s%s: %s", status.subject, f" ses-{status.session}" if status.session else "", status.error)
+        return 1 if failed else 0
+    statuses = run_participant_workflow(config)
+    failed = [status for status in statuses if status.status != "success"]
+    succeeded = [status for status in statuses if status.status == "success"]
+    logger.info("MRSIPrep finished: %d succeeded, %d failed", len(succeeded), len(failed))
+    for status in failed:
+        logger.error("FAILED sub-%s%s: %s", status.subject, f" ses-{status.session}" if status.session else "", status.error)
+    return 1 if failed and not succeeded else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

mrsiprep/config/defaults.py

@@ -0,0 +1,22 @@
+"""Default values for MRSIPrep."""
+
+METABOLITE_ALIASES = {
+    "Glx": ["GluGln", "Glx"],
+    "GluGln": ["GluGln", "Glx"],
+    "NAA": ["NAA", "NAANAAG"],
+    "tNAA": ["NAANAAG", "tNAA", "NAA"],
+    "NAANAAG": ["NAANAAG", "tNAA", "NAA"],
+    "Cho": ["GPCPCh", "Cho"],
+    "GPCPCh": ["GPCPCh", "Cho"],
+    "tCr": ["CrPCr", "tCr"],
+    "CrPCr": ["CrPCr", "tCr"],
+    "Ins": ["Ins"],
+}
+
+QUALITY_DEFAULTS = {
+    "snr_min": 4.0,
+    "linewidth_max": 0.1,
+    "crlb_max": 20.0,
+}
+
+CHIMERA_SCALES = {"scale1": 1, "scale2": 2, "scale3": 3, "scale4": 4, "scale5": 5}

mrsiprep/config/settings.py

@@ -0,0 +1,212 @@
+"""Runtime configuration objects."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from .defaults import QUALITY_DEFAULTS
+
+
+@dataclass
+class MRSIPrepConfig:
+    bids_dir: Path
+    output_dir: Path
+    analysis_level: str
+    participant_label: list[str] = field(default_factory=list)
+    session_label: list[str] = field(default_factory=list)
+    participants_file: Path | None = None
+    bids_filter_file: Path | None = None
+    metabolites: list[str] | None = None
+    quality_metrics: list[str] = field(default_factory=lambda: ["snr", "linewidth", "crlb"])
+    snr_min: float = QUALITY_DEFAULTS["snr_min"]
+    linewidth_max: float = QUALITY_DEFAULTS["linewidth_max"]
+    crlb_max: float = QUALITY_DEFAULTS["crlb_max"]
+    processing_mode: str = "mni-norm"
+    tissue_backend: str = "synthseg-fast"
+    registration_backend: str = "ants"
+    ants_mrsi_to_t1_transform: str = "sr"
+    ants_t1_to_mni_transform: str = "s"
+    fsl_mrsi_to_t1_dof: int = 6
+    fsl_mrsi_to_t1_init: str = "flirt"
+    fsl_t1_to_mni_dof: int = 12
+    fsl_cost: str = "mutualinfo"
+    normalization: str = "simple"
+    output_spaces: list[str] = field(default_factory=lambda: ["MNI152NLin2009cAsym"])
+    output_mrsi_t1w: bool = False
+    mni_resolution: str = "t1wres"
+    registration_t1_target: str | None = None
+    csf_pv_threshold: float = 0.95
+    parcellation_mode: str | None = None
+    synthseg_mode: str = "robust"
+    chimera_scheme: str = "LFMIHIFIS"
+    chimera_scale: int = 3
+    chimera_grow: int = 2
+    atlas: str = "chimera-LFMIHIFIS-3"
+    custom_atlas: Path | None = None
+    custom_atlas_lut: Path | None = None
+    fs_subjects_dir: Path | None = None
+    write_connectivity: bool = False
+    connectivity_method: str = "spearman"
+    connectivity_space: str = "MRSI"
+    connectivity_n_perturbations: int = 50
+    connectivity_sigma_scale: float = 2.0
+    connectivity_exclude_parcels: str | None = None
+    connectivity_max_parcel_id: int | None = None
+    regional_summary: str = "mean"
+    nthreads: int = 16
+    nproc: int = 1
+    ref_met: str | None = None
+    t1_pattern: str = "desc-brain_T1w"
+    transform: str = ""
+    filter_biharmonic: bool = True
+    filter_fwhm_mm: float | None = None
+    spike_percentile: float = 99.0
+    no_pvc: bool = False
+    longitudinal: bool = False
+    transform_spikemask: bool = False
+    overwrite: bool = False
+    overwrite_filt: bool = False
+    overwrite_seg: bool = False
+    overwrite_pve: bool = False
+    overwrite_t1_reg: bool = False
+    overwrite_mni_reg: bool = False
+    overwrite_transform: bool = False
+    overwrite_chimera: bool = False
+    work_dir: Path | None = None
+    verbose: int = 1
+    validate_only: bool = False
+    skip_file_integrity_check: bool = False
+    check_external_libs: bool = False
+    stop_on_first_crash: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.metabolites:
+            raise ValueError("--metabolites is required (comma-separated list, e.g. 'CrPCr,GluGln,GPCPCh,NAANAAG,Ins').")
+        if not self.ref_met:
+            raise ValueError("--ref-met is required (reference metabolite used to build the MRSI registration target).")
+        self.bids_dir = Path(self.bids_dir).resolve()
+        self.output_dir = Path(self.output_dir).resolve()
+        if self.bids_filter_file is not None:
+            self.bids_filter_file = Path(self.bids_filter_file).resolve()
+        from mrsiprep.io.bids import load_bids_filters
+
+        self.bids_filters = load_bids_filters(self.bids_filter_file)
+        self.output_spaces = _normalize_output_spaces(self.output_spaces)
+        if self.work_dir is None:
+            self.work_dir = self.output_dir / "work"
+        else:
+            self.work_dir = Path(self.work_dir).resolve()
+        if self.fs_subjects_dir is not None:
+            self.fs_subjects_dir = Path(self.fs_subjects_dir).resolve()
+        if self.processing_mode not in {"mni-norm", "parc-con", "midas"}:
+            raise ValueError(f"Unsupported processing mode: {self.processing_mode}")
+        if self.synthseg_mode not in {"fast", "standard", "robust"}:
+            raise ValueError(f"Unsupported SynthSeg mode: {self.synthseg_mode}")
+        if self.tissue_backend not in {"synthseg-fast", "existing", "none"}:
+            raise ValueError(f"Unsupported tissue backend: {self.tissue_backend}")
+        if self.registration_backend in {"flirt/fnirt", "flirt_fnirt", "flirt-fnirt"}:
+            self.registration_backend = "fsl"
+        if self.registration_backend not in {"ants", "fsl"}:
+            raise ValueError(f"Unsupported registration backend: {self.registration_backend}")
+        if self.registration_backend == "fsl" and self.longitudinal:
+            raise ValueError("--longitudinal currently requires --registration-backend ants.")
+        if self.fsl_mrsi_to_t1_dof not in {6, 7, 9, 12}:
+            raise ValueError("--fsl-mrsi-to-t1-dof must be one of 6, 7, 9, or 12.")
+        if self.fsl_mrsi_to_t1_init not in {"flirt", "usesqform"}:
+            raise ValueError("--fsl-mrsi-to-t1-init must be 'flirt' or 'usesqform'.")
+        if self.fsl_t1_to_mni_dof not in {6, 7, 9, 12}:
+            raise ValueError("--fsl-t1-to-mni-dof must be one of 6, 7, 9, or 12.")
+        if self.tissue_backend == "none":
+            self.no_pvc = True
+        if self.registration_t1_target is None:
+            self.registration_t1_target = "brain" if self.processing_mode in {"mni-norm", "midas"} else "brain-csf"
+        if self.parcellation_mode is None:
+            # midas defaults to SynthSeg parcellation: subject-native, needs no
+            # recon-all, and its GM/WM atlas suffices for the Eq. 4 regression.
+            self.parcellation_mode = "synthseg" if self.processing_mode in {"mni-norm", "midas"} else "chimera"
+        if self.processing_mode == "mni-norm" and self.parcellation_mode != "synthseg":
+            raise ValueError("mni-norm only supports SynthSeg parcellation. Use --mode parc-con for Chimera or MNI atlases.")
+        if self.processing_mode == "mni-norm" and self.registration_t1_target not in {"brain", "raw"}:
+            raise ValueError("mni-norm supports SynthSeg brain or raw T1w registration targets.")
+        if self.processing_mode == "parc-con" and self.parcellation_mode == "synthseg":
+            raise ValueError("parc-con requires Chimera or MNI atlas parcellation.")
+        if self.processing_mode == "midas":
+            # MIDAS mode's tissue correction is the per-parcel Eq. 4 regression,
+            # not PETPVC RBV; the paper has no voxelwise PVC step. Fuzzy c-means
+            # always supplies its own GM/WM/CSF maps, so the SynthSeg+FAST/CAT12
+            # tissue backends do not apply here.
+            self.no_pvc = True
+            self.tissue_backend = "synthseg-fast"
+        self.nproc = max(1, int(self.nproc))
+        self.nthreads = max(1, int(self.nthreads))
+
+    def resolve_cpu_budget(self) -> tuple[int, int, str | None]:
+        """Coerce nproc*nthreads to the available CPU count.
+
+        Returns (nproc, nthreads, warning) where warning is set (and nthreads
+        reduced) if the requested total thread budget exceeds the machine's
+        CPU count.
+        """
+        import os
+
+        cpu_count = os.cpu_count() or 1
+        requested_total = self.nproc * self.nthreads
+        if requested_total <= cpu_count:
+            return self.nproc, self.nthreads, None
+        coerced_nthreads = max(1, cpu_count // self.nproc)
+        warning = (
+            f"--nproc {self.nproc} x --nthreads {self.nthreads} = {requested_total} threads exceeds "
+            f"{cpu_count} available CPUs; coercing --nthreads to {coerced_nthreads} "
+            f"({self.nproc} x {coerced_nthreads} = {self.nproc * coerced_nthreads})."
+        )
+        return self.nproc, coerced_nthreads, warning
+
+    @property
+    def derivative_dir(self) -> Path:
+        return self.output_dir if self.output_dir.name == "mrsiprep" else self.output_dir / "mrsiprep"
+
+    @property
+    def source_derivatives_dir(self) -> Path:
+        return self.bids_dir / "derivatives"
+
+    @property
+    def logs_dir(self) -> Path:
+        return self.derivative_dir / "logs"
+
+    @property
+    def freesurfer_dir(self) -> Path:
+        if self.fs_subjects_dir is not None:
+            return self.fs_subjects_dir
+        return self.output_dir / "freesurfer"
+
+    def to_dict(self) -> dict:
+        out = asdict(self)
+        for key, value in list(out.items()):
+            if isinstance(value, Path):
+                out[key] = str(value)
+            elif isinstance(value, list):
+                out[key] = [str(item) if isinstance(item, Path) else item for item in value]
+        return out
+
+
+def _normalize_output_spaces(spaces: list[str]) -> list[str]:
+    aliases = {
+        "mrsi": "MRSI",
+        "orig": "MRSI",
+        "t1": "T1w",
+        "t1w": "T1w",
+        "mni": "MNI152NLin2009cAsym",
+        "mni152": "MNI152NLin2009cAsym",
+        "mni152nlin2009casym": "MNI152NLin2009cAsym",
+    }
+    normalized = []
+    for value in spaces:
+        key = str(value).strip().lower()
+        if key not in aliases:
+            supported = ", ".join(sorted(aliases))
+            raise ValueError(f"Unsupported output space '{value}'. Supported values: {supported}")
+        canonical = aliases[key]
+        if canonical not in normalized:
+            normalized.append(canonical)
+    return normalized