Preprocessing with fMRIprep

Overview

clpipe uses fMRIprep via the clpipe preprocess command to perform minimal preprocessing on functional MRI data.

clpipe preprocess creates one batch job per subject. If you find that you are running out of memory, increase the [FMRIPrepOptions][FMRIPrepMemoryUsage] option in the configuration file.

To submit your dataset for preprocessing, use the following command:

Configuration

class clpipe.config.options.FMRIPrepOptions

Options for configuring fMRIPrep.

bids_directory: str = ''

Your BIDs formatted raw data directory.

working_directory: str = 'SET WORKING DIRECTORY'

Storage location for intermediary fMRIPrep files. Takes up a large amount of space - Longleaf users should use their /work folder.

output_directory: str = ''

Where to save your preprocessed images.

fmriprep_path: str = '/proj/hng/singularity_imgs/fmriprep_22.1.1.sif'

Path to your fMRIPrep Singularity image.

freesurfer_license_path: str = '/proj/hng/singularity_imgs/license.txt'

Path to your Freesurfer license .txt file.

use_aroma: bool = False

Set True to generate AROMA artifacts. Significantly increases run time and memory usage.

commandline_opts: str = ''

Any additional arguments to pass to FMRIprep.

templateflow_toggle: bool = True

Set True to activate to use templateflow, which allows you to generate multiple template variantions for the same outputs.

templateflow_path: str = '/proj/hng/singularity_imgs/template_flow'

The path to your templateflow directory.

templateflow_templates: list

Which templates (standard spaces) should clpipe download for use in templateflow?

fmap_roi_cleanup: int = 3

How many timepoints should the fmap_cleanup function extract from blip-up/blip-down field maps, set to -1 to disable.

fmriprep_memory_usage: str = '50G'

How much memory in RAM each subject’s preprocessing will use.

fmriprep_time_usage: str = '16:0:0'

How much time on the cluster fMRIPrep is allowed to use.

n_threads: str = '12'

How many threads to use in each job.

log_directory: str = ''

Path to your logging directory for fMRIPrep outputs. Not generally changed from default.

docker_toggle: bool = False

Set True to use a Docker image.

docker_fmriprep_version: str = ''

Path to your fMRIPrep Docker image.

Command

clpipe preprocess

Submit BIDS-formatted images to fMRIPrep.

Providing no SUBJECTS will default to all subjects. List subject IDs in SUBJECTS to process specific subjects:

> clpipe preprocess 123 124 125 …

clpipe preprocess [OPTIONS] [SUBJECTS]...

Options

-config_file, -c <config_file>

Required The path to your clpipe configuration file.

-bids_dir, -i <bids_dir>

The dicom info output file name.

-working_dir <working_dir>

Where to generate the working directory.

-output_dir, -o <output_dir>

Where to put the preprocessed data. If a configuration file is provided with a output directory, this argument is not necessary.

-log_dir <log_dir>

Where to put your HPC output files (such as SLURM output files).

-submit, -s

Flag to submit commands to the HPC.

-debug, -d

Flag to enable detailed error messages and traceback.

Arguments

SUBJECTS

Optional argument(s)

Quality Control Reports

fMRIprep produces detailed html reports for each subject, allowing users to visually inspect registration, normalization and confound plots. However, these reports do not have the images directly embedded in them, which means that directly downloading them from the HPC will not result in a usable report. There are two options:

1. Open the html reports directly on the HPC, using some sort of interactive web browser.

2. Download the reports and the images in the correct directory structure.

clpipe has a convenience function to organize and prepare a zip archive containing the reports and images, for quick download onto a personal computer.

This command uses the working directory previously specified to copy the reports and images to, then creates a zip archive containing them. This command is not a batch

command, and can take a little time creating the archive, so be aware.

Once the archive is created, it can be downloaded and unzipped to a personal computer. The reports should correctly load images once opened.

clpipe reports fmriprep

Create a .zip directory of all fMRIPrep reports.

clpipe reports fmriprep [OPTIONS]

Options

-config_file, -c <config_file>

Required The configuration file for the current data processing setup.

-output_name, -o <output_name>

Path and name of the output archive. Defaults to current working directory and “fMRIPrep_Reports.zip”

-clear_temp, -keep_temp

Keep or clear the built temporary directory. Defaults to clear_temp.

-debug, -d

Print traceback on errors.