Usage

The SML fMRI Preprocessing Template provides two methods for running pipeline steps: an interactive TUI launcher and manual execution of sidecar scripts.

Interactive TUI Launcher

The graphical launcher provides an interactive interface with context and parameter setting:

./launch

Features:

  • Welcome screen with pipeline overview

  • Workflow selector with step descriptions

  • Interactive parameter setting for each step

  • User-friendly for those less familiar with command line

Example Workflow:

  1. Launch the TUI: ./launch

  2. Select a preprocessing step from the menu

  3. Configure parameters (if needed)

  4. Submit the job to Slurm

Manual Execution

For more control, you can manually execute each sidecar script:

Basic Usage

# Run step 1: FlyWheel to Server transfer
./01-run.sbatch

# Run step 3: dcm2niix conversion
./03-run.sbatch

# Run step 4: Prep for fMRIPrep
./04-run.sbatch

fMRIPrep Options

# Anatomical workflows only
./05-run.sbatch --anat-only

# Both anatomical and functional workflows
./05-run.sbatch

# Continue with remaining fMRIPrep steps
./06-run.sbatch

Pipeline Steps

The preprocessing pipeline consists of the following steps:

Step 1: FlyWheel Transfer

Automated transfer of scanner acquisitions from FlyWheel to Server

Step 2: BIDS Conversion (if needed)

Convert raw data to BIDS format

Step 3: dcm2niix Conversion

Convert DICOM files to NIfTI format

Step 4: Prep for fMRIPrep

  • Remove dummy scans

  • Set up fieldmap-based distortion correction

  • Validate data structure

Step 5: fMRIPrep Anatomical

Run fMRIPrep anatomical workflows only (if doing manual edits)

Step 6: fMRIPrep Complete

Run remaining fMRIPrep steps (functional workflows)

Monitoring Jobs

Check Slurm Job Status

# View all your jobs
squeue -u $USER

# View specific job details
scontrol show job <job_id>

# View job array status
sacct -j <job_id>

Check Logs

Log files are stored in the configured log directory:

# Slurm logs
ls ${BASE_DIR}/logs/slurm/

# Workflow logs
ls ${BASE_DIR}/logs/workflows/

# View a specific log
less ${BASE_DIR}/logs/slurm/step-01_<subject_id>.out

Quality Control

After preprocessing, review the outputs:

Check fMRIPrep Reports

# Open HTML reports in browser
firefox ${DERIVS_DIR}/sub-<subject_id>.html

Validate BIDS Structure

# Use BIDS validator (if installed)
bids-validator ${TRIM_DIR}

Inspect Preprocessed Data

# Check output structure
tree ${DERIVS_DIR}/sub-<subject_id>/

# View metadata
cat ${DERIVS_DIR}/sub-<subject_id>/func/*.json

Troubleshooting

Failed Jobs

If a job fails, check the logs:

  1. Review Slurm output: ${BASE_DIR}/logs/slurm/*.out

  2. Check error logs: ${BASE_DIR}/logs/slurm/*.err

  3. Examine workflow logs: ${BASE_DIR}/logs/workflows/

Common solutions:

  • Verify paths in settings.sh

  • Check file permissions

  • Ensure sufficient disk space

  • Validate BIDS structure

Rerunning Subjects

To rerun a subject, use the force modifier:

# In your subject list file
101:force

Or manually remove the completion marker before rerunning.

Debug Mode

Enable debug mode in settings.sh:

DEBUG=1

This provides more verbose output for troubleshooting.

Best Practices

  1. Test on a Single Subject

    Always test your configuration on one subject before processing the entire dataset.

  2. Monitor Resource Usage

    Use sstat and sacct to monitor job resource usage and adjust settings if needed.

  3. Regular Backups

    Maintain backups of raw data and important intermediate outputs.

  4. Document Changes

    Keep notes on any parameter changes or manual interventions.

  5. Review QC Reports

    Always review fMRIPrep HTML reports for quality control.

Next Steps