spineprep 26.0.0

A containerised BIDS-App for reproducible spinal-cord fMRI preprocessing with per-vertebral-level quality control

Reproducible, QC-first preprocessing for human spinal-cord fMRI.
An open, containerised BIDS-App — a BIDS dataset in, GLM-ready derivatives and per-step quality control out.

---

SpinePrep automates the field's recommended cord-fMRI recipe end to end, with one step-local truth metric and one visual reportlet at every step. It follows the design of the established brain pipelines (fMRIPrep, MRIQC, SCT) and applies it to a 5–7 mm structure that moves, distorts, and spans vertebral levels.

The scientific methods belong to the tools SpinePrep integrates — the Spinal Cord Toolbox, FSL, ANTs, and the PAM50 template. SpinePrep's contribution is the integration, automation, reproducibility, and standardised quality control around them, not new algorithms.

[!NOTE] SpinePrep is at v26.0.0 and methods validation is ongoing. It has been developed and tested on cervical spinal-cord EPI-BOLD at 3 T across eight public and internal datasets; it runs outside that envelope but warns you. See the validation page for current evidence and known limits.

Pipeline

flowchart TB
  IN([BIDS dataset]) --> P
  subgraph P ["Set up"]
    direction LR
    S1[S1 Input verify] --> S2[S2 Anat cordref] --> S3[S3 Func ref + crop]
  end
  P --> C
  subgraph C ["Align & correct"]
    direction LR
    S4[S4 Motion] --> S5[S5 Distortion] --> S6[S6 Func to anat]
  end
  C --> N
  subgraph N ["Normalize & derive"]
    direction LR
    S7[S7 PAM50 normalize] --> S8[S8 Confounds] --> S9[S9 Derivatives]
  end
  N --> S10["S10 QC & release"] --> OUT([GLM-ready derivatives + QC report])

Each step measures itself in isolation (its own pass/warn/fail metric) and emits a diagnostic reportlet, so a failure is attributable to the step that caused it.

Quality control is the validator

Every run produces self-contained HTML reports — the human eyeballs the figures; the numbers quantify the call. One reportlet should tell you what failed and why.

Installation

Container (recommended)

SpinePrep ships as a build recipe, not a prebuilt image — a deliberate choice. The container installs FSL, which is free for academic/non-commercial use but carries non-commercial licence terms. Building the image yourself (rather than us redistributing one that bundles FSL) keeps SpinePrep's own Apache-2.0 distribution unencumbered, and you obtain FSL directly under its own licence.

git clone https://github.com/SpinePrep/SpinePrep.git
cd SpinePrep
docker build -f Dockerfile.spineprep \
  --build-arg GIT_SHA=$(git rev-parse HEAD) \
  --build-arg GIT_DESCRIBE=$(git describe --always --tags) \
  -t spineprep:26.0.0 .

For HPC, convert the image to Apptainer — see the quickstart.

Local (advanced)

The Python orchestration layer installs with pip, but the full pipeline also needs SCT, FSL, and ANTs on your PATH (the container provides these). A PyPI release is planned; for now, install from a clone:

git clone https://github.com/SpinePrep/SpinePrep.git
cd SpinePrep && pip install .

Quickstart

SpinePrep uses the standard BIDS-App interface:

# participant level: preprocess each subject
docker run --rm -v /path/to/bids:/bids:ro -v /path/to/out:/out \
  spineprep:26.0.0 /bids /out participant --participant-label sub-01

# group level: aggregate QC and write the release report
docker run --rm -v /path/to/bids:/bids:ro -v /path/to/out:/out \
  spineprep:26.0.0 /bids /out group

See the documentation for options, configuration, and the full walkthrough.

What you get

• BIDS-native — a BIDS dataset in, BIDS-Derivatives out; no manual masking.
• Cord-focused — segmentation, motion, distortion and PAM50 normalization tuned for the cord, not adapted from brain defaults.
• Readable QC — one truth metric and one reportlet per step, plus subject- and group-level HTML reports with a reconciled attrition waterfall.
• Reproducible — deterministic runs, versioned policy, and a provenance receipt (tool + policy + git SHAs); a re-run reproduces the same numbers under the same tool versions.

Documentation

Full documentation lives at spineprep.com:

• Quickstart · Install & use
• Methods (S1–S10) · Validation
• CLI · Configuration · Cite

Citation

If you use SpinePrep, please cite the software and the tools it builds on (SCT, FSL, ANTs, PAM50) — the auto-generated methods boilerplate in each report lists them, and How to cite gives the references.

@software{spineprep,
  title   = {SpinePrep: a containerised BIDS-App for reproducible
             spinal-cord fMRI preprocessing},
  author  = {Sharifi, Kiomars},
  year    = {2026},
  version = {26.0.0},
  url     = {https://spineprep.com}
}

GitHub's "Cite this repository" button reads CITATION.cff and always gives the current form.

Contributing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. For usage questions, please post on the NeuroStars spineprep tag rather than the issue tracker, so answers stay searchable for the next person.

Acknowledgements

SpinePrep builds directly on the Spinal Cord Toolbox, FSL, ANTs, and the PAM50 template, and follows the design philosophy of fMRIPrep. We are grateful to those projects and their communities.

License

Apache-2.0 — see LICENSE. SpinePrep integrates third-party tools under their own licences; see NOTICE.