NeuroMaestro

A modular neuroimaging preprocessing pipeline for HPC clusters, with both a GUI and CLI. Pipeline parameters and analysis workflows are configured through YAML files, allowing flexible customization without modifying the underlying code.

Full handbook: https://georgiacenterfordevelopmentalscience.github.io/NeuroMaestro/

Supported Pipelines

The pipeline is organized into four stages. The software used at each stage is configured per-project and can be customized; the examples below reflect our defaults.

The key distinction between pipeline types:

• Staged pipelines (--staged-prep) require an intermediate step before modality preprocessing, by default skull stripping and nonlinear registration of the T1w image. Designed for workflows like AFNI that operate on locally processed data, but can be adapted to any pipeline requiring intermediate steps.
• BIDS pipelines (--bids-prep) run directly on BIDS-formatted data without intermediate steps (e.g. fMRIPrep, QSIPrep).

Installation

Prerequisites: Python 3.10+, HPC cluster with SLURM, neuroimaging software installed on the cluster.

pip install neuromaestro

# Verify
neuromaestro --help
neuromaestro-gui --help

To install from source in development mode:

git clone https://github.com/GeorgiaCenterforDevelopmentalScience/NeuroMaestro.git
cd NeuroMaestro
pip install -e '.[dev]'

Configuration

Each project requires a {project}_config.yaml in the project_config/ folder of your config directory, the one --config-dir points at. Run neuromaestro generate-config {project} to create one from the template, then fill in paths, HPC modules, and pipeline options.

Modalities available under --bids-prep and --staged-prep, and the output folder of each task (output_pattern), are declared in config.yaml.

Expected output files for --resume are defined in config/results_check/{project}_checks.yaml. Edit this file to specify which files should exist (and optionally their minimum size) for a subject to be considered complete.

HPC scheduler, resource profiles (memory, walltime, CPU), and submission flags are configured in hpc_config.yaml. Recommended values are pre-filled; update partition names and resource limits to match your cluster.

Quick Start

First-time setup: scaffold config and script templates into your study directory.

neuromaestro init /path/to/my_study
# Optionally export to ~/.bashrc so you can omit --config-dir on every command.
# If you skip this, pass --config-dir /path/to/my_study/config explicitly instead.
export NEUROMAESTRO_CONFIG_DIR=/path/to/my_study/config

This copies config.yaml, hpc_config.yaml, project_config/, results_check/, and script templates. Edit them to match your cluster and project before running.

# Launch the GUI
neuromaestro-gui

Open the link it prints at startup (http://127.0.0.1:8050/?token=...). Requests without the token are rejected, and a new token is made at each launch.

Or use the CLI. Start with a dry-run on one subject to verify the plan:

neuromaestro run \
  --subjects 001 \
  --input /data/BIDS \
  --output /data/processed \
  --work /data/work \
  --config-dir /data/config \
  --project my_study \
  --session 01 \
  --bids-prep rest \
  --dry-run

Full pipeline (all stages, multiple subjects):

neuromaestro run \
  --subjects subjects.txt \
  --input /data/raw \
  --output /data/processed \
  --work /data/work \
  --config-dir /data/config \
  --project my_study \
  --session 01 \
  --prep unzip_recon \
  --intermed volume \
  --staged-prep cards,kidvid \
  --staged-post cards,kidvid \
  --bids-prep rest,dwi \
  --bids-post rest,dwi \
  --mriqc all

Dependencies are enforced automatically by the scheduler.

CLI Reference

Core options

Pipeline options

Run options

Resume a Partial Run

neuromaestro run \
  --subjects subjects.txt \
  --input /data/BIDS \
  --output /data/processed \
  --work /data/work \
  --config-dir /data/config \
  --project my_study \
  --session 01 \
  --bids-prep rest \
  --resume

--resume checks each subject's expected output files (defined in config/results_check/{project}_checks.yaml) before submitting. Subjects that already have valid outputs are skipped, and the skipped IDs are printed per task.

Directory Structure

Input (BIDS)

input_directory/
├── sub-001/
│   └── ses-01/
│       ├── anat/
│       ├── func/
│       └── ...
└── sub-002/
    └── ...

Output Example

output_directory/
└── project_name/
    ├── raw/
    ├── BIDS/
    ├── AFNI_derivatives/
    ├── BIDS_derivatives/
    │   ├── fmriprep/
    │   ├── xcpd/
    │   ├── qsiprep/
    │   └── qsirecon/
    ├── postprocessing/
    └── quality_control/
        └── mriqc/

work_directory/
├── database/        # default db_path, shared by projects with the same --work
└── project_name/
    └── log/

For questions or issues, contact QiuyuYu or open a repository issue.