Parameter Reference

Path to the FreeSurfer license file. This is the only strictly required option.

Specify which preprocessing workflows to run. Multiple tasks must be enclosed in double quotes and separated by spaces.

• anat — T1w structural MRI preprocessing
• bold — BOLD fMRI preprocessing
• dwi — diffusion MRI preprocessing

Specify the participant age group for age-appropriate MRI preprocessing.

• infant — under 2 years
• pediatric — 2 to under 18 years
• adult — 18 years and older

Specify one or more participants to process. If this option is not provided, all participants in the BIDS directory will be processed.

Specify participants to exclude from processing. If specified, the designated participants will be ignored.

Path to a pre-existing T1w derivatives directory.

This option is required if anat is not included in --tasks but BOLD or DWI preprocessing is requested, because BOLD and DWI workflows depend on structural derivatives such as T1w images, masks, surfaces, segmentations, and parcellations. If no path is specified, output_dir/derivatives/omniprep/Recon is used by default.

Skip BIDS validation. By default, OmniPrep validates the input dataset as a BIDS dataset before processing. Use this option only if you are confident that the input data are organized correctly or if validation is handled externally.

Remove intermediate files generated during workflow execution. This helps reduce disk usage, especially for large multimodal datasets. Recommended if storage space is limited.

Specify the compute device.

• auto — automatically select available compute devices.
• cpu — disable GPU acceleration and run GPU-capable steps on CPU where supported.
• 0, 1, 2, ... — run GPU-enabled steps on the specified GPU device ID.

Maximum number of CPU cores available to the workflow.

When set to auto, OmniPrep automatically detects the total number of CPU cores in the runtime environment and uses that value for Nextflow. When customizing, ensure the value you set does not exceed the actual number of CPU cores.

Maximum memory available to the workflow, in GB.

When set to auto, OmniPrep automatically detects the amount of memory available in the runtime environment and allocates 90% of it to Nextflow.

Number of threads used by multi-threaded applications. Set to 0 to disable explicit multi-threading control. If this value is too high, efficiency will actually decrease, so 8 is recommended.

Continue the workflow when selected non-critical errors are encountered. Useful for large datasets, but use with caution — failed derivatives may be missing for some subjects.

Resume a previous Nextflow run. Completed tasks will be reused from the cache instead of being recomputed. Use this after an unexpected termination to avoid re-running already-completed tasks.

Disable generation of the quality control results, including all QC documents.

Specify the brain atlas or atlases to use for atlas-based outputs. Multiple atlases must be enclosed in double quotes and separated by spaces.

Built-in atlases:

Atlas-based outputs may include:

• T1w ROI-level morphometric features
• BOLD ROI time series
• ROI Pearson functional connectivity
• DWI structural connectomes

If a custom atlas is used, provide the required atlas files (such as GCS or ANNOT files, LUT files, and reordered LUT files), and map them to /opt/atlas inside the Docker container.

Include subcortical regions in atlas-based outputs.

• For cortical-only atlases, OmniPrep can append 21 FreeSurfer-defined subcortical regions. See the LUT files under omniprep/atlas/LUT in the source code for details.
• For atlases that provide their own subcortical parcellation, a corresponding .gca file (named AtlasName.gca) or NIfTI subcortical file (named AtlasName_space-MNI152XXX-subcortex.nii.gz, where MNI152XXX is the associated MNI space name) must be provided. Map these files to the /opt/atlas/ path within the Docker container.

Specify atlas names whose subcortical parcellation is provided as a NIfTI image and should be transformed using SynthMorph. Use this option when a custom atlas includes a subcortical NIfTI file, for example AtlasName_space-MNI152XXX-subcortex.nii.gz. The file should be mapped to /opt/atlas inside the Docker container.

Specify BOLD task names to process, such as "rest" or task-specific names. Multiple tasks should be enclosed in double quotes and separated by spaces.

Example: --bold_task_type "rest nback"

Number of initial BOLD volumes to remove before denoising. Commonly used to remove non-steady-state volumes affected by unstable MR signal.

Apply susceptibility distortion correction (SDC) for BOLD fMRI when fieldmap or suitable distortion-correction information is available.

Generate CIFTI-format BOLD outputs. The default CIFTI output space is the HCP-style 91k grayordinate space. Disabled by default unless this option is specified.

Specify the surface template space for BOLD surface outputs.

Supported values:

Specify the template space and resolution for volumetric BOLD outputs. Supports optional cohort and resolution settings.

Registration strategy:

• Adults: direct registration from T1w to the specified output space.
• Infants and children: an age-appropriate MNIInfant or MNIPediatric cohort is automatically selected based on age_months.
  • If the selected cohort matches the output space, register directly from T1w to that space (single-stage).
  • Otherwise, register from T1w to the age-matched cohort, then to the specified output space (two-stage).

All transforms are combined to resample BOLD only once.

Age detection (age_months): automatically read age from BIDS sessions.tsv (preferred) or participants.tsv. Supported fields: age_days > age_weeks > age_months > age (years). All ages are converted to months (age_months).

Age-specific templates:

• Under 5 years — MNIInfant (age-matched cohort).
• 5 to under 18 years — MNIPediatricAsym (age-matched cohort).
• 18 years and older — Adult template.

Examples:

Compute BOLD confound regressors, including motion parameters, tissue-based signals, outlier regressors, and other nuisance variables used for BOLD denoising.

OmniPrep generates the motion_outlier_XXX parameters for motion frame detection. The Power method is used for motion frame detection by default, with a threshold of 0.2 for framewise displacement (FD).

This option is automatically enabled when --bold_denoise, --bold_roi_timeseries, or --bold_roi_pearson_fc is enabled.

Once scrubbing is enabled, OmniPrep processes motion frames during the denoising step of the post-processing workflow, in accordance with the strategy defined by the bold_scrubbing_strategy variable. The motion frame markers are defined by the motion_outlier_XXX and scrub_fd_XXX_0pX_mask values in the confounds file.

Specify the scrubbing strategy. Currently, only the regression and interpolation methods are supported.

• regression — the motion frames will be regressed out during the regression of the covariates.
• interpolation — the motion frames will be processed using the PCHIP method.

Specify the type of FD used to detect motion frames. Currently, the power and jenkinson methods are supported.

• power — the FD value is stored in the framewise_displacement field of the confounds file.
• jenkinson — the value is stored in the rmsd field of the confounds file.

Specify the threshold for FD. When this threshold is exceeded, the frame is considered to be a motion frame.

Number of volumes preceding each detected motion outlier to additionally mark as outliers.

Number of BOLD volumes following each detected motion outlier that will also be marked as outliers. A value of 0 disables forward temporal expansion.

Perform BOLD denoising based on the generated confound regressors. Depending on the selected options, this may include nuisance regression, detrending, temporal filtering, and removal of initial volumes (--bold_skip_frame).

Specify the BOLD denoising strategy.

• motion6 — six rigid-body motion parameters: trans_x, trans_y, trans_z, rot_x, rot_y, rot_z.
• motion24 — Friston-24 motion model: six motion parameters, their temporal derivatives, squared terms, and squared derivatives.
• motion24_wm_csf — Friston-24 motion regressors plus white matter and CSF regressors, including derivatives and squared terms.
• motion24_wm_csf_gsr — Friston-24 motion regressors plus white matter, CSF, and global signal regressors. Includes global signal regression and should be used with explicit methodological justification or sensitivity analysis.
• acompcor6_motion24 — the first six anatomical CompCor components plus Friston-24 motion regressors.
• acompcor6_motion24_wm_csf — the first six anatomical CompCor components plus Friston-24 motion regressors, white matter, and CSF regressors.

Number of anatomical CompCor components to use when an aCompCor-based denoising strategy is selected. For example, if this value is 6, the first six aCompCor components will be used. This parameter only affects strategies containing acompcor.

Specify the temporal filtering mode used during BOLD denoising.

• bandpass — apply explicit temporal band-pass filtering using --bold_bandpass and exclude fMRIPrep-style cosine regressors.
• cosine — use fMRIPrep-style cosine regressors for high-pass drift removal and disable explicit high-pass/low-pass filtering.
• none — do not use cosine regressors and do not apply explicit temporal filtering.

Temporal band-pass frequency range in Hz. Used only when --bold_filter_mode is set to "bandpass".

Example: --bold_bandpass 0.01-0.08 means high-pass = 0.01 Hz, low-pass = 0.08 Hz.

Spatial smoothing kernel size in millimeters, specified as full width at half maximum (FWHM). Use "0" to disable smoothing. Multiple values can be provided to generate multiple smoothed BOLD outputs from the same denoised BOLD image.

Examples: --bold_smooth_fwhm "0", --bold_smooth_fwhm "4", --bold_smooth_fwhm "4 6 8"

Specify one or more BOLD metrics to calculate. Multiple metrics should be provided as a space-separated string.

• reho — regional homogeneity, measuring local synchronization of neighboring voxel time series using Kendall's W.
• alff — amplitude of low-frequency fluctuations within the configured frequency band.
• malff — mean-normalized ALFF, calculated by dividing voxelwise ALFF by the mean ALFF within the analysis mask.
• zalff — Z-score-normalized ALFF, calculated by standardizing voxelwise ALFF values within the analysis mask.
• falff — fractional ALFF, calculated as the ratio of low-frequency amplitude to the amplitude across the full available frequency range.
• int — intrinsic neural timescale, estimated from the temporal autocorrelation of the BOLD signal.

Notes: ReHo is calculated using the time series from which motion frames have been removed. However, the ALFF metrics (and their derivatives) and INT are calculated using the complete sequence, with no motion frames removed.

Specifies the frequency range from which low-frequency amplitudes are extracted during ALFF/fALFF frequency-domain calculations.

Note that this differs from --bold_bandpass, which is used for time-domain bandpass filtering of BOLD signals. --bold_alff_bandpass is used solely for ALFF/fALFF spectral calculations.

Enable atlas-based ROI summarization of the requested BOLD metrics. For each configured brain atlas, voxelwise metric values are aggregated within each ROI and saved as region-level tabular outputs. When this option is not enabled, only voxelwise metric maps are generated.

Extract atlas-based BOLD ROI time series from denoised BOLD images. Requires --atlas and is automatically enabled when --bold_roi_pearson_fc is enabled.

The output is saved as an N × T matrix (rows = ROIs, columns = time points). The saved ROI time-series file contains no header, no index, and no ROI label column.

Notes: although the time series retains the full timeline, only valid frames that have not been identified as motion artefacts are used to calculate the mean and standard deviation of each ROI for z-score normalisation.

After excluding any time points flagged as abnormal motion, calculate the Pearson correlation coefficient between two valid ROI time series to construct a static functional connectivity matrix.

This option automatically enables --bold_roi_timeseries, --bold_denoise, and --bold_confounds.

The output is an N × N ROI functional connectivity matrix without header or ROI labels.

Controls whether to physically censor (remove) motion frames when computing static functional connectivity. If omitted, the correlation matrix is computed on the full-length time series, where motion frames have been processed according to the specified --bold_scrubbing_strategy.

Save Fisher-z-transformed Pearson FC values instead of raw Pearson correlation coefficients. Recommended for group-level statistical analysis, edge-wise statistical tests, regression models, or group-average FC calculation. If FC matrices are used directly as graph edge weights for machine learning or GNN models, raw Pearson correlations may be preferable.

Specify DWI task or acquisition labels to process when multiple DWI acquisitions are present. Multiple values should be enclosed in double quotes and separated by spaces.

Specify the susceptibility distortion correction (SDC) method for DWI.

• auto — automatically select the best available method based on BIDS metadata and participant age.
  • Adults: pepolar > fieldmap > synb0 > none.
  • Infants/Children: pepolar > fieldmap > none.
• pepolar — use reverse phase-encoded b0 images for correction (FSL TOPUP).
• fieldmap — use GRE-based field maps for distortion correction.
• synb0 — use Synb0-DISCO to synthesize an undistorted b0 image for correction. Supported for adults only.
• none — disable susceptibility distortion correction.

Specify DWI volumetric output resolution.

• native — keep the native DWI resolution.
• 01, 02, 03, ... — resample DWI derivatives to the specified isotropic resolution in millimeters.

Compute diffusion tensor imaging metrics.

Automatically enabled when tensor-based tractography is requested with --fiber_track_algorithm "tensor_prob", and when FA-weighted connectomes are requested with --dwi_fa_connectome.

Specify DTI metrics to compute. This parameter only controls which DTI metrics are generated — DTI metrics are computed only when --dwi_cal_dti is enabled (or automatically enabled by a dependent option).

Estimate fiber orientation distributions using constrained spherical deconvolution (CSD).

Automatically enabled when FOD-based tractography algorithms are selected (ifod2, sd_stream). Therefore, if any of --fiber_track_algorithm "ifod2", --fiber_track_algorithm "sd_stream", or --fiber_track_algorithm "ifod2 sd_stream" is specified, OmniPrep will automatically enable CSD calculation if --dwi_cal_csd has not been explicitly specified.

Specify CSD-related outputs to generate when CSD calculation is enabled. Typical outputs may include white matter fiber orientation distributions and related tissue response components, depending on the current implementation.

Perform whole-brain tractography. Automatically enabled when any of --dwi_create_connectome, --dwi_fa_connectome, or --fiber_track_sift2 is enabled. If tractography is enabled but no tracking algorithm is specified, OmniPrep uses ifod2.

Specify the tractography algorithm or algorithms. Multiple tracking algorithms can be specified simultaneously by enclosing them in double quotes and separating them with spaces.

• ifod2 — probabilistic FOD-based tractography using second-order integration over fiber orientation distributions. Requires CSD.
• sd_stream — deterministic FOD-based streamline tractography based on spherical deconvolution. Requires CSD.
• tensor_prob — probabilistic tensor-based tractography. Requires DTI.

Examples: --fiber_track_algorithm "ifod2", "ifod2 sd_stream", "ifod2 sd_stream tensor_prob"

Number of streamlines to generate or select during tractography.

Tractography is currently CPU-based and can be one of the most time-consuming steps in OmniPrep.

• Routine processing: 5,000,000 streamlines provides a practical balance between computational cost and tractography quality.
• Higher-quality connectomes: 10,000,000 streamlines may be used if sufficient computing time is available.
• Testing/debugging: this value can be reduced, e.g. --fiber_track_select 200000.

Minimum streamline length in millimeters.

Maximum streamline length in millimeters.

Apply SIFT2 to estimate streamline weights after tractography. This option automatically enables --dwi_fiber_track. Note that OmniPrep currently uses iFOD2-based tractography for SIFT2-weighted derivatives if ifod2 is not included in --fiber_track_algorithm.

Construct atlas-based structural connectivity matrices from tractography outputs. Requires an atlas to be specified with --atlases "DK Brainnetome Glasser ...".

Automatically enables --dwi_fiber_track and --dwi_cal_csd. Note that OmniPrep currently constructs structural connectomes based on iFOD2 tractography if ifod2 is not included in --fiber_track_algorithm.

Compute FA-weighted structural connectivity matrices. Automatically enables --dwi_cal_dti, --dwi_create_connectome, and --dwi_fiber_track.

Apply inverse node-volume scaling during structural connectome construction. This option can reduce the influence of ROI size on connectivity estimates by scaling connection weights according to the inverse volume of the connected nodes.