Installation¶

Prerequisites¶

Before using the fMRIPrep Workbench, ensure you have:

Access to a computing cluster with SLURM workload manager
Singularity/Apptainer for container execution
FreeSurfer license file
Git for version control
Python 3.6 or higher (with PyYAML package)

Getting Started¶

1. Create Repository from Template¶

Click the "Use this template" button 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. Key sections to configure:

directories:
  base_dir: '/path/to/your/study'
  scripts_dir: '/path/to/your/study/code'
  raw_dir: '/path/to/your/study/sourcedata'
  trim_dir: '/path/to/your/study'
  freesurfer_license: '~/freesurfer.txt'

scan:
  task_id: 'YourTaskName'
  n_dummy: 5
  run_numbers:
    - '01'
    - '02'

validation:
  expected_fmap_vols: 12
  expected_bold_vols: 220

slurm:
  email: 'your.email@institution.edu'
  partition: 'your,partitions'

4. Set Up Subject List¶

Create your subject list file:

cp all-subjects.template.txt all-subjects.txt

Add your subject IDs (one per line, just the number without "sub-" prefix):

# Study subjects
101
102
103

5. Verify Configuration¶

Test that your configuration loads correctly:

source ./load_config.sh

You should see a message indicating successful configuration loading and the number of subjects found.

6. Verify Paths¶

Ensure all paths in config.yaml are correct and accessible:

directories.base_dir - Your study's root directory
directories.raw_dir - BIDS-formatted raw data location
directories.trim_dir - Destination for processed data
directories.freesurfer_license - Path to FreeSurfer license file
pipeline.singularity_image_dir - Path to Singularity/Apptainer containers

System Requirements¶

Minimum Requirements:

8 CPU cores per subject
8GB RAM per subject
100GB storage per subject (for preprocessed outputs)

Recommended:

16 CPU cores per subject
32GB RAM per subject
200GB storage per subject

Software Dependencies:

SLURM workload manager
Singularity/Apptainer 3.0+
FreeSurfer (via container)
fMRIPrep (via container)
dcm2niix/heudiconv (via container)
Python 3.6+ with PyYAML

Container Setup¶

The pipeline uses Singularity/Apptainer containers for reproducibility. Configure container paths in config.yaml:

pipeline:
  singularity_image_dir: '/path/to/containers'
  singularity_image: 'fmriprep-24.0.1.simg'
  heudiconv_image: 'heudiconv_latest.sif'

Ensure the containers exist at the specified paths before running the pipeline.

Python Dependencies¶

The configuration loader requires PyYAML. Install it if not available:

pip install pyyaml

Or using conda:

conda install pyyaml

Migration from v0.1.x¶

If upgrading from a version that used settings.sh:

Create the new configuration file:

cp config.template.yaml config.yaml

Transfer your settings from settings.sh to config.yaml. See the migration guide in the Configuration documentation for a detailed mapping of old to new settings.
Note the new pipeline step numbering (14 steps total):
Steps 1-5: FlyWheel download, DICOM conversion, prep, and QC
Step 6: fMRIPrep anatomical-only (optional, for manual FreeSurfer editing)
Steps 7-8: FreeSurfer download/upload utilities (optional)
Step 9: fMRIPrep full workflows
Steps 10-13: FSL FEAT statistical analysis (Level 1, 2, 3 GLM)
Step 14: Tarball utility for data management
Remove or archive your old settings.sh file.

Docker Installation (Recommended)¶

The easiest way to use fMRIPrep Workbench is via the pre-built Docker container. This eliminates dependency management and ensures consistent environments.

Prerequisites¶

Docker Engine 20.10+ (for local workstations)
OR Singularity/Apptainer 3.0+ (for HPC clusters)

Option 1: Using Docker (Local Workstations)¶

1. Install Docker¶

Follow the official Docker installation guide for your platform: - Docker Desktop for Mac - Docker Desktop for Windows - Docker Engine for Linux

2. Pull the Image¶

docker pull shawnschwartz/fmriprep-workbench:latest

3. Download the Wrapper Script¶

# Clone the repository (or download just the wrapper script)
git clone https://github.com/shawntz/fmriprep-workbench.git
cd fmriprep-workbench

# Make the wrapper script executable
chmod +x fmriprep-workbench

4. Start the Container¶

./fmriprep-workbench start

5. Launch the TUI¶

./fmriprep-workbench launch

Option 2: Using Singularity (HPC Clusters)¶

Singularity/Apptainer is designed for HPC environments and provides better integration with job schedulers like SLURM.

1. Download Pre-built Singularity Image¶

Download the .sif file from the latest release:

# Replace vX.Y.Z with the actual version from the releases page
wget https://github.com/shawntz/fmriprep-workbench/releases/download/vX.Y.Z/fmriprep-workbench_vX.Y.Z.sif

2. Or Convert from Docker Hub¶

If a pre-built Singularity image isn't available:

# Using Singularity 3.x
singularity build fmriprep-workbench_vX.Y.Z.sif docker://shawnschwartz/fmriprep-workbench:latest

# Using Apptainer (newer Singularity)
apptainer build fmriprep-workbench_vX.Y.Z.sif docker://shawnschwartz/fmriprep-workbench:latest

3. Run the Container¶

# Interactive shell
singularity shell \
  --bind $(pwd):/workspace \
  --bind $HOME/.cache/templateflow:/cache/templateflow \
  --bind $HOME/.cache/fmriprep:/cache/fmriprep \
  fmriprep-workbench_vX.Y.Z.sif

# Execute a specific command
singularity exec \
  --bind $(pwd):/workspace \
  fmriprep-workbench_vX.Y.Z.sif \
  /opt/fmriprep-workbench/launch

# Submit as SLURM job
sbatch --wrap="singularity exec --bind $(pwd):/workspace fmriprep-workbench_vX.Y.Z.sif /opt/fmriprep-workbench/01-run.sbatch"

Option 3: Using Docker Compose¶

For more complex setups with multiple services:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Container Mount Points¶

The container exposes the following mount points:

Host Path	Container Path	Purpose
`./` (current directory)	`/opt/fmriprep-workbench/workspace`	Working directory
`./config.yaml`	`/data/config/config.yaml`	Configuration file
`./all-subjects.txt`	`/data/subjects/all-subjects.txt`	Subject list
`./logs/`	`/data/logs`	Log files
`~/.cache/templateflow`	`/data/cache/templateflow`	TemplateFlow cache
`~/.cache/fmriprep`	`/data/cache/fmriprep`	fMRIPrep cache

Wrapper Script Commands¶

The fmriprep-workbench wrapper script provides convenient commands:

./fmriprep-workbench start     # Start container in background
./fmriprep-workbench stop      # Stop the container
./fmriprep-workbench launch    # Launch the TUI
./fmriprep-workbench shell     # Open bash shell
./fmriprep-workbench logs      # View container logs
./fmriprep-workbench status    # Check container status
./fmriprep-workbench exec <cmd># Execute command in container
./fmriprep-workbench pull      # Pull latest image
./fmriprep-workbench build     # Build image locally
./fmriprep-workbench help      # Show help

Building Locally¶

To build the Docker image from source:

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

# Build the image
docker build -t shawnschwartz/fmriprep-workbench:latest .

# Or use the wrapper script
./fmriprep-workbench build

Next Steps¶

After installation, proceed to the Configuration guide to set up your preprocessing pipeline parameters in detail.

For Docker-specific usage instructions, see Docker Usage Guide.