Skip to content

Welcome to fMRIPrep Workbench Documentation

This documentation covers the fMRIPrep Workbench template, a generalizable workflow for fMRI preprocessing that handles the full pipeline from scanner acquisition downloads to fMRIPrep execution.

Version: 0.3.0

Overview

The fMRIPrep Workbench transforms fMRI preprocessing scripts into a generalizable workflow that handles:

  • Automated transfer of scanner acquisitions from FlyWheel to server
  • DICOM to NIfTI conversion with dcm2niix/heudiconv
  • Dummy scan removal and fieldmap-based susceptibility distortion correction setup
  • Quality control verification (metadata and volume counts)
  • fMRIPrep anatomical-only workflows (for manual FreeSurfer editing)
  • FreeSurfer manual editing utilities (download/upload with automatic backup)
  • fMRIPrep full workflows (anatomical + functional)
  • FSL FEAT statistical analysis (Level 1, 2, 3 GLM)
  • Data management utilities (tarball/untar for inode optimization)
  • Interactive TUI launcher for all pipeline steps

Quick Start

# Pull the image
docker pull shawnschwartz/fmriprep-workbench:latest

# Clone the repository
git clone https://github.com/shawntz/fmriprep-workbench.git
cd fmriprep-workbench

# Start the container
./fmriprep-workbench start

# Launch the interactive TUI
./fmriprep-workbench launch

Option 2: Using Singularity (HPC Clusters)

# Download or build the Singularity image
singularity build fmriprep-workbench.sif docker://shawnschwartz/fmriprep-workbench:latest

# Run the TUI
singularity exec --bind $(pwd):/workspace fmriprep-workbench.sif /opt/fmriprep-workbench/launch

Option 3: Manual Installation

1. Create Repository from Template

Click "Use this template" on the GitHub repository to create your own copy.

2. Clone Your Repository

git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name

3. Configure Settings

Copy the configuration template and customize for your study:

cp config.template.yaml config.yaml
# Edit config.yaml with your study-specific parameters

4. Set Up Subject List

cp all-subjects.template.txt all-subjects.txt
# Add your subject IDs (one per line, just the number without "sub-" prefix)

5. Run the Pipeline

# Interactive mode (recommended)
./launch

# Or manual execution (14-step workflow)
./01-run.sbatch                      # Step 1: FlyWheel download
./02-run.sbatch                      # Step 2: DICOM conversion
./03-run.sbatch                      # Step 3: Prep for fMRIPrep
./04-run.sbatch                      # Step 4: QC metadata
./05-run.sbatch                      # Step 5: QC volumes
./06-run.sbatch                      # Step 6: fMRIPrep anat-only (optional)
./toolbox/download_freesurfer.sh     # Step 7: Download FreeSurfer (optional)
./toolbox/upload_freesurfer.sh       # Step 8: Upload FreeSurfer (optional)
./07-run.sbatch                      # Step 9: fMRIPrep full workflows
./10-fsl-glm/setup_glm.sh            # Step 10: FSL GLM setup
./08-run.sbatch <model-name>         # Step 11: FSL Level 1
./09-run.sbatch <model-name>         # Step 12: FSL Level 2
./10-run.sbatch <model-name>         # Step 13: FSL Level 3
./toolbox/tarball_sourcedata.sh      # Step 14: Tarball utility

What's New in v0.3.0

Major Features:

  • 🐳 Docker Containerization: Complete Docker support with automated CI/CD to Docker Hub
  • 📊 FSL FEAT Analysis: Full statistical analysis pipeline (Level 1, 2, 3 GLM)
  • 🧠 FreeSurfer Editing: Download/upload utilities with automatic backups
  • 📚 Documentation Migration: Modern MkDocs system with dark mode and PDF export
  • 🔢 14-Step Pipeline: Complete end-to-end workflow from acquisition to analysis

Breaking Changes:

  • Directory renaming: 07-run-fmriprep → 09-run-fmriprep, 08-fsl-glm → 10-fsl-glm
  • Pipeline expanded from 7 to 14 steps
  • Documentation format changed from Sphinx to MkDocs

See Changelog for full details.

Features

Automated Transfer : Transfer scanner acquisitions from FlyWheel to server

DICOM Conversion : Convert DICOM to NIfTI using heudiconv/dcm2niix

Dummy Scan Removal : Remove initial dummy scans based on configuration

Distortion Correction : Fieldmap-based susceptibility distortion correction setup

Quality Control : Built-in verification of metadata and volume counts

fMRIPrep Integration : Run anatomical-only or full workflows with FreeSurfer manual editing support

FreeSurfer Editing : Download/upload utilities with automatic backup for manual surface editing

FSL FEAT Analysis : Complete statistical analysis pipeline (Level 1, 2, 3 GLM)

Data Management : Tarball utility to optimize inode usage on shared filesystems

Interactive TUI : User-friendly launcher for all 14 pipeline steps

YAML Configuration : Portable, cross-platform configuration system

Getting Help