Reproducible-fMRI

An open-source template framework for reproducible multimodal neuroimaging analysis

Author
Affiliation

Emil Olsson

Reflexion Lab

Published

April 28, 2026

1 Welcome

Reproducible-fMRI is a template framework for reproducible multimodal neuroimaging analysis. It provides:

  • A two-tier path-resolution system (config/paths.toml + paths.local.toml) so code stays data-agnostic across sites.
  • BIDS Stats Models (.smdl.json) as the canonical statistical-model spec, with two pluggable runners (nilearn, FitLins).
  • Containerised pipelines for fMRIPrep, MRIQC, XCP-D, GLMsingle, FitLins, with HPC-tuned SLURM batch launchers.
  • A HALFpipe-style QC rater (make qc-rater) that produces a single-file static HTML form for inclusion-decision workflows.
  • A complete resting-state derivative pipeline (ALFF, fALFF, ReHo, seed-FC, atlas-FC) with ground-truth verification tests powered by known-signal injection.
  • Auto-generated CC0 Methods boilerplate (make methods-boilerplate) ready to paste into a manuscript.
  • Per-run provenance (libs.provenance) capturing config hash, container digest, git commit, SLURM job ID — drift-detectable on re-read.
  • A template-to-child propagation system with three-tier sync categorisation (SAFE_INFRA / SYNC_WITH_CARE / NEVER_SYNCS) and a durable cross-repo health dashboard (make cross-repo-health).
  • Boutiques descriptors for every pipeline tool, exposing the template to Nipoppy / CBRAIN / NeuroBagel.

2 Quick start

git clone https://github.com/CNClaboratory/Reproducible-fMRI my-study
cd my-study
make setup           # auto-detects site, copies preset, runs preflight --fix
$EDITOR config/paths.toml config/site.conf   # fill placeholders
make preflight       # re-verify after edits
make all BATCH_LABEL=my-study   # run the full pipeline

See Getting Started for the full 30-minute onboarding walkthrough.

3 Active child repositories

Four research projects propagate from this template:

  • CNClaboratory/twcf_figureground_fmri_analysis (figure-ground attention, 4 tasks, CCN 2026 manuscript)
  • subjectivitylab/vividness-perception-imagery (ETHOS pilot, multi-site UCI + NEU)
  • CNClaboratory/Hypergraphsciousness (HGNN consciousness science, EEG-fMRI fusion)
  • CNClaboratory/TI_DecNef (transcranial neurofeedback, MATLAB/Python hybrid)

The cross-repo health dashboard keeps these in sync.

4 Documentation map

The book is organized following NiPreps’ canonical IA:

  1. Installation & Setup — clone, configure, validate.
  2. Usage — HPC deployment + analysis standards.
  3. Outputs & Caveats — known issues with Symptom → Cause → Fix recipes for every multi-site bug we’ve hit.
  4. References — community standards (BIDS, BIDS Stats Models), tools, papers, and tutorials (Andy’s Brain Book, BCBS, HALFpipe).
  5. Developer Guide — template maintenance, sync mechanics, convergence playbook, dated decision log.

5 Citation

If you use this template, see the CITATION.cff at the repo root.