Configuration

The preprocessing pipeline requires proper configuration of several parameters in the settings.sh file. This guide explains how to configure your pipeline.

Configuration File

The main configuration file is settings.sh, which is created by copying settings.template.sh:

cp settings.template.sh settings.sh

Path Configuration

Set up your directory structure:

BASE_DIR="/my/project/dir"           # Root directory for the study
SCRIPTS_DIR="${BASE_DIR}/scripts"    # Path of cloned fMRI repo
RAW_DIR="${BASE_DIR}/bids"           # Raw BIDS-compliant data location
TRIM_DIR="${BASE_DIR}/bids_trimmed"  # Destination for processed data
WORKFLOW_LOG_DIR="${BASE_DIR}/logs/workflows"
TEMPLATEFLOW_HOST_HOME="${HOME}/.cache/templateflow"
FMRIPREP_HOST_CACHE="${HOME}/.cache/fmriprep"
FREESURFER_LICENSE="${HOME}/freesurfer.txt"

Task Parameters

Configure your task-specific settings:

task_id="SomeTaskName"   # Original task name in BIDS format
new_task_id="cleanname"  # New task name (if renaming needed)
n_dummy=5                # Number of dummy TRs to remove
run_numbers=("01" "02" "03" "04" "05" "06" "07" "08")

Data Validation

Set expected volume counts for validation:

EXPECTED_FMAP_VOLS=12   # Expected volumes in fieldmap scans
EXPECTED_BOLD_VOLS=220  # Expected volumes in BOLD scans

Fieldmap Mapping

Map fieldmaps to BOLD runs:

declare -A fmap_mapping=(
    ["01"]="01"  # Task BOLD run 01 uses fmap 01
    ["02"]="01"  # Task BOLD run 02 uses fmap 01
    ["03"]="02"  # Task BOLD run 03 uses fmap 02
    ["04"]="02"  # Task BOLD run 04 uses fmap 02
)

Subject Lists

Basic subject list in all-subjects.txt:

101
102
103

Subject ID Modifiers

You can use suffix modifiers for per-subject control:

101                # Standard subject, runs all steps
102:step4          # Only run step 4 for this subject
103:step4:step5    # Only run steps 4 and 5
104:force          # Force rerun all steps
105:step5:force    # Only run step 5, force rerun
106:skip           # Skip this subject

Available Modifiers:

  • step1 to step6 - Run specific steps only

  • force - Force rerun even if already processed

  • skip - Skip this subject entirely

Slurm Configuration

Configure Slurm job parameters:

export SLURM_EMAIL="hello@stanford.edu"
export SLURM_TIME="2:00:00"
export SLURM_MEM="8G"
export SLURM_CPUS="8"
export SLURM_ARRAY_THROTTLE="10"
export SLURM_PARTITION="hns,normal"

fMRIPrep Settings

Configure fMRIPrep-specific parameters:

FMRIPREP_VERSION="24.0.1"
FMRIPREP_OMP_THREADS=8
FMRIPREP_NTHREADS=12
FMRIPREP_MEM_MB=30000
FMRIPREP_FD_SPIKE_THRESHOLD=0.9
FMRIPREP_DVARS_SPIKE_THRESHOLD=3.0
FMRIPREP_OUTPUT_SPACES="MNI152NLin2009cAsym:res-2 anat fsnative fsaverage5"

Permissions

Set file and directory permissions:

DIR_PERMISSIONS=775   # Directory level
FILE_PERMISSIONS=775  # File level

Validation

Before running the pipeline:

  1. Verify all paths exist and are accessible

  2. Confirm volume counts match your acquisition protocol

  3. Test configuration on a single subject

  4. Review logs for configuration warnings

Common Issues

Path Issues

Double-check all path specifications are absolute and accessible

Volume Mismatches

Verify EXPECTED_FMAP_VOLS and EXPECTED_BOLD_VOLS match your protocol

Fieldmap Mapping

Ensure each BOLD run has a corresponding fieldmap entry

Permission Problems

Check that DIR_PERMISSIONS and FILE_PERMISSIONS are appropriate

Next Steps

After configuration, see the Usage guide to learn how to run the pipeline.