NeuroPilot

An agent-driven, three-skill pipeline for brain-MRI preprocessing and QC.

NeuroPilot packages the brain-MRI lifecycle as three composable, model-invocable Agent Skills — one for data ingestion, one for preprocessing, and one for quality control. Each skill is a self-describing SKILL.md capability package: a large-language-model (LLM) agent reads its description to decide when it applies, loads its reference procedures on demand, and runs its parameterized scripts (path-in, path-out) on a SLURM/Apptainer HPC cluster. The scientific tools themselves (fMRIPrep, QSIPrep, FreeSurfer, …) are unchanged; the skills supply the orchestration, checkpoints, and human-in-the-loop review that bind them into one reproducible workflow.

The three skills chain end to end but are also usable on their own.

New here? Start with the User Guide — install, per-skill setup, what to say to the agent, a full configuration reference, and troubleshooting.

---

The pipeline at a glance

                        raw DICOM  (or .zip / .tgz / extension-less)
                             │
        ┌────────────────────┴────────────────────┐
        │  1. dcm2bids-skill       (ingestion)     │   dcm2niix + Dcm2Bids
        └────────────────────┬────────────────────┘
                             ▼
                      BIDS dataset  (anat / dwi / func / perf + sidecars)
                             │
        ┌────────────────────┴────────────────────┐
        │  2. neuroimage-pre-skill (preprocessing) │   fMRIPrep · sMRIPrep · QSIPrep ·
        └────────────────────┬────────────────────┘   QSIRecon · XCP-D · FreeSurfer · MRtrix3
                             ▼
              FC / SC matrices  +  cortical-surface metrics
                             │
        ┌────────────────────┴────────────────────┐
        │  3. qc-agent-skill (quality control)     │  5-step review: raw → brain extraction →
        └────────────────────┬────────────────────┘  registration → segmentation → surface
                             ▼
               quality-controlled, human-signed derivatives

Ingestion produces BIDS, preprocessing turns BIDS into connectivity/surface derivatives, and QC reviews the structural intermediates — the output of one skill is a valid input to the next.

---

The three skills

1. dcm2bids-skill — ingestion (DICOM → BIDS)

Converts a raw DICOM archive into a validated BIDS dataset. Detects extension-less DICOM by magic bytes, extracts .zip/.tgz archives into a scratch copy (source untouched), classifies each series (T1w / T2w / FLAIR / DWI / BOLD / ASL), builds a cohort-wide series-union config so minority modalities are never dropped, self-tests the config, converts with per-subject fault tolerance, and validates with the BIDS Validator.

• Wraps: dcm2niix · Dcm2Bids · output follows the BIDS standard.

2. neuroimage-pre-skill — preprocessing (BIDS → FC / SC / surfaces)

Selects a pipeline from the modalities present and runs the matching BIDS Apps to produce functional-connectivity (FC), structural-connectivity (SC), and cortical-surface metrics.

• Wraps: fMRIPrep · sMRIPrep · XCP-D · QSIPrep · QSIRecon · FreeSurfer · MRtrix3 · nilearn · ANTs.

3. qc-agent-skill — quality control

A five-step, human-in-the-loop structural-MRI review — raw image → brain extraction → registration → segmentation → surface — under a detect → propose → approve → fix → verify loop. Detection is done by the skill’s own scripts; fixes are delegated to established tools; source data is read-only; and every decision is written to an append-only sign-off ledger.

• Wraps: FreeSurfer · SynthStrip · SynthSeg · ANTs · FSL · in-dashboard NiiVue viewer · QC metrics after MRIQC.

---

Environment & container setup

Nothing is hard-coded: each skill self-locates and takes its paths from arguments or environment variables. Set up each skill’s environment once, then point the preprocessing skill at your cluster with a single config file.

1. dcm2bids-skill — Python + dcm2niix + bids-validator

One-command conda route:

conda env create -f dcm2bids-skill/environment.yml   # python, nodejs, dcm2niix, dcm2bids
conda activate dcm2bids-skill
npm install -g bids-validator                        # the only manual step left

Or pip + system tools:

pip install -r dcm2bids-skill/requirements.txt       # dcm2bids >=3.2,<4.0
conda install -c conda-forge dcm2niix                # or a binary from the dcm2niix repo
npm install -g bids-validator                        # needs Node.js >= 18

./install.sh (Linux/macOS) or .\install.ps1 (Windows) auto-detects what you already have and installs the rest. Details: dcm2bids-skill/ENVIRONMENT.md.

2. qc-agent-skill — self-contained virtualenv

bash qc-agent-skill/setup_env.sh                        # creates qc-agent-skill/.venv
PYTHON=/path/to/python3 bash qc-agent-skill/setup_env.sh   # or pick a base interpreter

The only prerequisite is Python ≥ 3.9 on your PATH — no conda, no cluster, no group directory. It installs requirements.txt (nibabel, numpy, scipy, matplotlib, nilearn, pillow, pyyaml, pandas). The core — every step’s detection, the review dashboards, the in-page niivue 3-D viewer, dismiss, and sign-off — runs on this venv alone.

The fix / rerun stages additionally need external, licensed tools that are not bundled:

3. neuroimage-pre-skill — containers + one cluster config

Every cluster-specific setting lives in one file:

cp neuroimage-pre-skill/scripts/pipeline.env.template ~/pipeline.env
# edit ~/pipeline.env, then pass it to the submission script for your route:
bash neuroimage-pre-skill/scripts/fmri_dwi/submit_fmriprep.sh ~/pipeline.env

Submission scripts live under scripts//, one directory per pipeline:

Every step is bracketed by checkpoints you can also run standalone:

bash neuroimage-pre-skill/scripts/check_status.sh pre   
bash neuroimage-pre-skill/scripts/check_status.sh post  
bash neuroimage-pre-skill/scripts/check_status.sh dwi-qc 

The template ships with no preset paths. Fill in:

• APPTAINER_BIND — filesystem roots the container must see (e.g. /work,/proj,/users)
• MOD_APPTAINER / MOD_FREESURFER / MOD_MRTRIX / MOD_ANTS — your cluster’s module avail names, or leave empty if the tools are already on PATH
• FMRIPREP_IMG / SMRIPREP_IMG / XCPD_IMG / QSIPREP_IMG / QSIRECON_IMG — container paths (below)
• FS_LICENSE — FreeSurfer license (free registration)
• TEMPLATEFLOW_HOME — a cache you own and can write to. Compute nodes often have no internet, so pre-download templates on a login node through the container; a read-only shared cache fails with PermissionError on any missing file.
• FC_ATLAS_DIR, QSIRECON_ATLAS_DIR, UNC_ATLAS_DIR, DHCP_ATLAS_DIR — parcellations
• BIDS_DIR, OUTPUT_DIR, WORK_DIR, LOG_DIR — your data
• BATCH_SIZE, SLURM_CPUS, SLURM_MEM, SLURM_TIME — SLURM defaults

Containers (multi-GB, not bundled)

Build each once from its official Docker image, then point the matching *_IMG at the .sif:

module load apptainer          # if your cluster uses modules
mkdir -p ~/containers && cd ~/containers

apptainer build fmriprep-24.1.1.sif docker://nipreps/fmriprep:24.1.1
apptainer build smriprep-0.17.0.sif docker://nipreps/smriprep:0.17.0   # >= 0.17
apptainer build xcp_d-0.10.1.sif    docker://pennlinc/xcp_d:0.10.1
apptainer build qsiprep-0.19.0.sif  docker://pennbbl/qsiprep:0.19.0    # adult SC
apptainer build qsiprep-1.1.1.sif   docker://pennbbl/qsiprep:1.1.1     # infant SC (--infant needs 1.x)
apptainer build qsirecon-1.0.1.sif  docker://pennlinc/qsirecon:1.0.1   # adult SC recon

Pin these tags. The run scripts pass version-specific flags, so changing a tag can reintroduce unrecognized-argument crashes. Adult and infant SC deliberately use different QSIPrep images (0.19 vs 1.1.1) — set QSIPREP_IMG per route. Build only what your pipeline needs; leave the rest empty.

Porting to a new cluster is a one-file edit. Heavy jobs run in pinned Apptainer containers submitted to SLURM; large binaries (containers, atlases, license) come from their providers and are not bundled here.

---

Underlying tools — where to get them

---

Repository layout

NeuroPrep-Skill/
├── dcm2bids-skill/       # Stage 1 — ingestion (SKILL.md, scripts, tests)
├── neuroimage-pre-skill/ # Stage 2 — preprocessing (SKILL.md, scripts/pipeline.env.template)
├── qc-agent-skill/       # Stage 3 — quality control (SKILL.md, WORKFLOW.md, thresholds, steps)
└── README.md

Each skill directory has its own SKILL.md (and, where relevant, README.md / WORKFLOW.md) with detailed usage.

---

License

Apache-2.0. The underlying neuroimaging tools retain their own licenses — obtain them from their respective providers.