Functional Preprocessing¶

Initial Preprocessing¶

ANT’s N4BiasFieldCorrection - [On, Off]: Choose On to perform N4 Bias Field Correction on mean EPI image, may help enhance coregistration quality. Default is Off.
Despike - [On, Off, On/Off]: Choose On to perform AFNI 3dDespike. Default is Off.
Scaling - [On, Off]: Choose On to scale the brain to a different size, especially optimal for rodent data.
Scaling Factor - [integer]: The scaling factor of the brain. Default is 10.
Motion Statistics before Slice Timing Correction - [On, Off, On/Off]: Choose On to calculate motion parameter estimation before slice timing correction, with actual motion correction still occurring after slice timing correction. The motion parameters go on to be used in nuisance regression and statistics reporting. Default is Off.
Motion Correction Tool - [3dvolreg, mcflirt]: Choose motion correction method. Options: AFNI volreg, FSL mcflirt. Default is AFNI volreg.
Motion Correction Reference - [mean, median, selected volume]: Choose motion correction reference. Options: mean, median, selected volume. Default is mean.
Motion Correction Reference Volume - [integer]: Choose an integer as the motion correction reference volume if choosing “selected volume” as motion correction reference.
Motion Estimate Filter: Adapted from the motion estimate filter by DCAN Labs. Based on the filter described in Fair et al.[1].
1. run - [False, True]: Toggle the filter.
2. filter_type - [‘notch’, ‘lowpass’]: Use either a notch/bandstop or low-pass filter.
3. filter_order - [integer]: Specify the filter order. Default is 4.
4. breathing_rate_min - [integer]: Lowest breaths-per-minute value in the entire dataset (across all participants). Required for both notch and lowpass filters. Mutually exclusive with center_frequency, filter_bandwidth, and lowpass_cutoff. Using this parameter will guide the automatic design of the filter.
5. breathing_rate_max - [integer]: Highest breaths-per-minute value in the entire dataset (across all participants). Required for the notch filter. Mutually exclusive with center_frequency, filter_bandwidth, and lowpass_cutoff. Using this parameter will guide the automatic design of the filter.
6. center_frequency - [float]: Notch filter only. Manually select the center frequency for the notch filter. Mutually exclusive with breathing_rate_min and breathing_rate_max. Use this to manually design the filter.
7. filter_bandwidth - [float]: Notch filter only. Manually select the bandwidth for the notch filter. Mutually exclusive with breathing_rate_min and breathing_rate_max. Use this to manually design the filter.
8. lowpass_cutoff - [float]: Lowpass filter only. Manually select the cutoff frequency for the lowpass filter. Mutually exclusive with breathing_rate_min and breathing_rate_max. Use this to manually design the filter.

Configuration Without the GUI¶

The following nested key/value pairs will be set to these defaults if not defined in your pipeline configuration YAML.

registration_workflows:

  functional_registration:

    coregistration:
      # functional (BOLD/EPI) registration to anatomical (structural/T1)

      run: On

      # reference: 'brain' or 'restore-brain'
      # In ABCD-options pipeline, 'restore-brain' is used as coregistration reference
      reference: brain

      # Choose FSL or ABCD as coregistration method
      using: FSL

      # Choose brain or whole-head as coregistration input
      input: brain

      # Choose coregistration interpolation
      interpolation: trilinear

      # Choose coregistration cost function
      cost: corratio

      # Choose coregistration degree of freedom
      dof: 6

      # Extra arguments for FSL flirt
      arguments: None

      func_input_prep:

        # Choose whether to use functional brain or skull as the input to functional-to-anatomical registration
        reg_with_skull: Off

        # Choose whether to use the mean of the functional/EPI as the input to functional-to-anatomical registration or one of the volumes from the functional 4D timeseries that you choose.
        # input: ['Mean_Functional', 'Selected_Functional_Volume', 'fmriprep_reference']
        input: ['Mean_Functional']

        Mean Functional:

          # Run ANTs’ N4 Bias Field Correction on the input BOLD (EPI)
          # this can increase tissue contrast which may improve registration quality in some data
          n4_correct_func: False

        Selected Functional Volume:

          # Only for when 'Use as Functional-to-Anatomical Registration Input' is set to 'Selected Functional Volume'.
          #Input the index of which volume from the functional 4D timeseries input file you wish to use as the input for functional-to-anatomical registration.
          func_reg_input_volume: 0

functional_preproc:

  run: On

  update_header: 

    # Convert raw data from LPI to RPI
    run: On
  
  truncation:

    # First timepoint to include in analysis.
    # Default is 0 (beginning of timeseries).
    # First timepoint selection in the scan parameters in the data configuration file, if present, will over-ride this selection.
    # Note: the selection here applies to all scans of all participants.
    start_tr: 0

    # Last timepoint to include in analysis.
    # Default is None or End (end of timeseries).
    # Last timepoint selection in the scan parameters in the data configuration file, if present, will over-ride this selection.
    # Note: the selection here applies to all scans of all participants.
    stop_tr: None

  scaling:

    # Scale functional raw data, usually used in rodent pipeline
    run: Off

    # Scale the size of the dataset voxels by the factor.
    scaling_factor: 10

  despiking:

    # Run AFNI 3dDespike
    # this is a fork point
    #   run: [On, Off] - this will run both and fork the pipeline
    run: [Off]

  motion_estimates_and_correction:
  
    run: On

    motion_estimates: 

      # calculate motion statistics BEFORE slice-timing correction
      calculate_motion_first: Off

      # calculate motion statistics AFTER motion correction
      calculate_motion_after: On

    motion_correction:

      # using: ['3dvolreg', 'mcflirt']
      # Forking is currently broken for this option.
      # Please use separate configs if you want to use each of 3dvolreg and mcflirt.
      # Follow https://github.com/FCP-INDI/C-PAC/issues/1935 to see when this issue is resolved.
      using: ['3dvolreg']

      # option parameters
      AFNI-3dvolreg:

        # This option is useful when aligning high-resolution datasets that may need more alignment than a few voxels.
        functional_volreg_twopass: On

      # Choose motion correction reference. Options: mean, median, selected_volume, fmriprep_reference
      motion_correction_reference: ['mean']

      # Choose motion correction reference volume
      motion_correction_reference_volume: 0

    motion_estimate_filter:

      # Filter physiological (respiration) artifacts from the head motion estimates.
      # Adapted from DCAN Labs filter.
      #     https://www.ohsu.edu/school-of-medicine/developmental-cognition-and-neuroimaging-lab
      #     https://www.biorxiv.org/content/10.1101/337360v1.full.pdf
      # this is a fork point
      #   run: [On, Off] - this will run both and fork the pipeline
      run: [Off]

      filters:
        - # options: "notch", "lowpass"
          filter_type: "notch"

          # Number of filter coefficients.
          filter_order: 4

          # Dataset-wide respiratory rate data from breathing belt.
          # Notch filter requires either:
          #     "breathing_rate_min" and "breathing_rate_max"
          # or
          #     "center_frequency" and "filter_bandwitdh".
          # Lowpass filter requires either:
          #     "breathing_rate_min"
          # or
          #     "lowpass_cutoff".
          # If "breathing_rate_min" (for lowpass and notch filter)
          # and "breathing_rate_max" (for notch filter) are set,
          # the values set in "lowpass_cutoff" (for lowpass filter),
          # "center_frequency" and "filter_bandwidth" (for notch filter)
          # options are ignored.

          # Lowest Breaths-Per-Minute in dataset.
          # For both notch and lowpass filters.
          breathing_rate_min:

          # Highest Breaths-Per-Minute in dataset.
          # For notch filter.
          breathing_rate_max:

          # notch filter direct customization parameters

          # mutually exclusive with breathing_rate options above.
          # If breathing_rate_min and breathing_rate_max are provided,
          # the following parameters will be ignored.

          # the center frequency of the notch filter
          center_frequency:

          # the width of the notch filter
          filter_bandwidth:

        - # options: "notch", "lowpass"
          filter_type: "lowpass"

          # Number of filter coefficients.
          filter_order: 4

          # Dataset-wide respiratory rate data from breathing belt.
          # Notch filter requires either:
          #     "breathing_rate_min" and "breathing_rate_max"
          # or
          #     "center_frequency" and "filter_bandwitdh".
          # Lowpass filter requires either:
          #     "breathing_rate_min"
          # or
          #     "lowpass_cutoff".
          # If "breathing_rate_min" (for lowpass and notch filter)
          # and "breathing_rate_max" (for notch filter) are set,
          # the values set in "lowpass_cutoff" (for lowpass filter),
          # "center_frequency" and "filter_bandwidth" (for notch filter)
          # options are ignored.

          # Lowest Breaths-Per-Minute in dataset.
          # For both notch and lowpass filters.
          breathing_rate_min:

          # lowpass filter direct customization parameter

          # mutually exclusive with breathing_rate options above.
          # If breathing_rate_min is provided, the following
          # parameter will be ignored.

          # the frequency cutoff of the filter
          lowpass_cutoff:

Changed in version 1.8.5: Changed from single dictionary to filters list of dictionaries

For each filter in motion_estimate_filter.filters, if breathing_rate_min and breathing_rate_max are provided, the filter design attributes (center_frequency, filter_bandwidth, lowpass_cutoff) are automatically configured. But if you provide these directly, you don’t need the breathing rates. If all all parameters are provided, the filter design attributes will be ignored in favor of the breathing_rate_* attributes. A configuration must match at least one row in the following table:

`run`	`filter_type`	`filter_order`	`breathing_rate_min`	`breathing_rate_max`	`center_frequency`	`filter_bandwidth`	`lowpass_cutoff`	`Name`
“Off”
“On”	“notch”	required int	required float	required float				optional str
“On”	“notch”	required int	None	None	required float	required float		optional str
“On”	“lowpass”	required int	required float					optional str
“On”	“lowpass”	required int	None				required float	optional str

For each filter, Name need not be provided; if Name is not provided, it will be autopopulated based on the configuration, using the keys in this table [2]:

`breathing_rate_min`	`breathing_rate_max`	`center_frequency`	`filter_bandwidth`	`lowpass_cutoff`
`fl`	`fu`	`fc`	`bw`	`fc`

and the format {filterType}{filterOrder}[{key}{value}]* with a lowercase p replacing any decimal points. If any filters have duplicate names (given or generated), each name after the first will be suffixed with dup{duplicate_number}, with duplicate_number starting at 1. See CPAC.pipeline.schema.name_motion_filter for examples.

Note about abbreviation table

References

Slice Timing Correction¶

Most fMRI images are created by combining multiple 2D slices into a single 3D volume. Slices are acquired one after another, either sequentially in ascending or descending order, or in an interleaved manner, such that every other slice is acquired in a first pass, and the remaining slices are acquired in a second pass. The time elapsed between the acquisition of the first and last slice is equivalent to the repetition time (TR) used. Slice timing correction acts to adjust the timecourse of voxels in each slice to account for these differences. This is done by interpolating the data in each slice to match the timing of a reference slice. Slice timing correction is necessary because many statistical models used for fMRI analysis assume that all voxels are measured simultaneously. As such, differences in acquisition time between slices can cause confounds.

You can configure your slice time correction settings through the C-PAC pipeline configuration editor, under the Time Series Options tab in the Functional Preprocessing section. Here you can select whether or not to run Slice Time Correction, as well as which slice acquisition pattern to enter.

First Timepoint - [integer]: The starting volume of the scan. If you need to censor the first volumes of a scan to facilitate stable magnetization, you can do so here.
Last Timepoint - [integer/text]: The last volume of the timeseries. If you wish to cut off the timeseries before a specific point, you can do so here. Otherwise, set this to ‘End’.
TR - [numerical value]: The TR for volume acquisitions. If you wish to have this information read from the NifTI header set this to ‘None’.
Perform Slice Time Correction - [On, Off, On/Off]: Interpolate voxel timeseries so that sampling occurs at the same time.
Slice Acquisition Pattern - [Use NifTI Header, alt+z, alt+z2, alt-z, alt-z2, seq+z, seq-z]: The order of slice acquisition for the scans.

Note that if a scan parameters file was used to construct the participant list, the parameters defined in this file will override the settings used here.

Configuration Without the GUI¶

The following nested key/value pairs will be set to these defaults if not defined in your pipeline configuration YAML.

functional_preproc:

  slice_timing_correction:

    # Interpolate voxel time courses so they are sampled at the same time points.
    # this is a fork point
    #   run: [On, Off] - this will run both and fork the pipeline
    run: [On]

    # use specified slice time pattern rather than one in header
    tpattern: None

    # align each slice to given time offset
    # The default alignment time is the average of the 'tpattern' values (either from the dataset header or from the tpattern option).
    tzero: None

Through the Data Configuration¶

You can also specify slice timing parameters within the subject list. If you wish to specify slice timing correction parameters in this way, scan parameters must be supplied to C-PAC in a .csv file, and the path to this file provided when setting up a new subject list.

If all subjects within a site have the same acquisition order:
Use the template scan_parameters.csv file available for download here.

If subjects within a site have different acquisition orders:
Use the template scan_parameters_multiscan.csv file available for download here.

Slice Timing information should be entered into these files as follows:

Site - Site name corresponding to a site-level folder in your directory structure (e.g. site_1).
Scan - Only for scan_parameters_multiscan.csv. Scan name corresponding to a scan-level folder in your directory structure (e.g. anat, rest)
TR - TR in seconds.
Reference - Desired reference slice (usually the middle slice).
Acquisition - Acquisition order.
- altplus - Alternating in the +z direction
- alt+z - Alternating in the +z direction
- alt+z2 - Alternating, but beginning at slice #1
- altminus - Alternating in the -z direction
- alt-z - Alternating in the -z direction
- alt-z2 - Alternating, starting at slice #nz-2 instead of #nz-1
- seqplus - Sequential in the plus direction
- seqminus - Sequential in the minus direction
FirstTR - First volume to include in analysis. (Reminder, volumes start at 0)
LastTR - Last volume to include in analysis.

If your data does not conform to one of the 6 acquisition orders in the list above (as would be the case for multiband and multi-echo sequences), you must generate acquisition order files before running slice timing correction. This is done using the AFNI command dicom_hdr and specifying the first DICOM file in an image sequence, as well as the name of an output .txt file.:

dicom_hdr -slice_times /path/to/file.dcm > output_name.txt

This will output a text file with the name you specified. Each number in this file corresponds to a slice and the time when it was acquired (relative to the beginning of the TR). The following is an example of an acquisition order file for a a multiband fMRI scan with 40 slices and TR=645ms:

0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0 0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0 0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0 0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0

The path to the acquisition order file for each scan should be specified in the “Acquisition” column of your scan_parameters.csv or scan_parameters_multiscan.csv file.

Note: alt+z2 is the order most commonly used on Siemens scanners for interleaved scans with an even number of slices.

Note: Scan parameter information specified for slice timing correction will override the settings specified in the pipeline configuration YAML.

Field Map-Based Distortion Correction¶

Distortion correction is a method that aims to reduce distortion in EPI (fMRI) images caused by inhomogeneities in the magnetic field (which often stem from differences in tissue across tissue boundaries in the head). C-PAC has the option of including field map-based distortion correction into your pre-processing pipeline, and two methods, Phase Difference (PhaseDiff) or Phase-Encoding Polarity (Blip-up/Blip-down) to perform distortion correction.

Performing PhaseDiff distortion correction requires the acquisition of a phase difference image and two magnitude images. The “best of the two” magnitude images is chosen, and a final input of one phase difference file and one magnitude file are then used by the pre-processing pipeline. Phase-Encoding Polarity (commonly known as blip-up/blip-down) employs phase-encoding direction-specific EPI field maps to correct for distortion in the direction of the phase-encoding. It uses AFNI 3dQWarp to calculate the distortion unwarp for EPI field maps of opposite/same phase encoding direction.

These files are used to generate the field map during pre-processing, and they can be provided to the C-PAC pipeline through the data configuration (participant list) file. More information on how to set this data configuration file is available here.

The C-PAC pipeline configuration builder provides options for configuring the Distortion Correction workflow. The field maps are generated within the distortion correction workflow, and the result is subsequently sent to the functional-to-anatomical registration step (FSL FLIRT, and with Boundary-Based Registration if selected and if tissue segmentation is run), where the distortion is “un-warped” during the transform.

Distortion correction - [On, Off]: Perform field map-based distortion correction.
PhaseDiff - [On, Off]: Perform field map correction using a single phase difference image, a subtraction of the two phase images from each echo. Default scanner for this method is SIEMENS.
Blip - [On, Off]: Uses AFNI 3dQWarp to calculate the distortion unwarp for EPI field maps of opposite/same phase encoding direction.
Skull-strip the magnitude file with - [BET, 3dSkullStrip]: Since the results of the distortion correction can be strongly affected by the strength of the skull-stripping of the magnitude file, the choice between using FSL’s BET or AFNI’s 3dSkullStrip is left open, as these tools can have varying results depending on the data itself. The choice of tool is only for skull-stripping the magnitude file, and not for the skull-stripping step of the main anatomical pre-processing part of the pipeline.
BET threshold/AFNI shrink factor - [float]: The threshold for brain extraction. FSL requires tight skull-stripping, erring on the side of ignoring brain voxels rather than adding noise. However, it might not be required to increase the threshold in all datasets, so it is important to check your dataset before changing the threshold.In FSL-BET, this is referred to as “threshold intensity” and in AFNI’S 3dSkull Strip, it is the -shrink_factor. The default value is 0.5.
DeltaTE, in ms - [float]: The time difference between the first magnitude image and the second magnitude image. The default value is 2.46 ms, which is widely used for SIEMENS, but it may differ with different datasets acquired by other MRI scanner brands, so it is important to ascertain this value specific to your data.
EffectiveEchoSpacing, in s - [float]: The effective echo spacing is the time between the start of the readout of two successive lines in k-space during the EPI acquisition. This is a value obtained from the functional EPI (NOT the fieldmap).

New in version 1.0.3.

Changed in version 1.8.5.

Warning

Prior to v1.8.5, C-PAC erroneously used the DwellTime value from the fieldmap metadata instead of the appropriate EffectiveEchoSpacing value from the BOLD metadata.
EffectiveEchoSpacing to asymmetric ratio - [float]: This is the ratio between the effective echo spacing, as referenced above, and the asymmetric time.
Phase encoding direction - [string]: This is the position of the voxels in the input image, and can have values of x/y/z or -x/-y/-z.

Configuration Without the GUI¶

The following nested key/value pairs will be set to these defaults if not defined in your pipeline configuration YAML.

functional_preproc:

  distortion_correction:

    # this is a fork point
    #   run: [On, Off] - this will run both and fork the pipeline
    run: [On]

    # using: ['PhaseDiff', 'Blip', 'Blip-FSL-TOPUP']
    #   PhaseDiff - Perform field map correction using a single phase difference image, a subtraction of the two phase images from each echo. Default scanner for this method is SIEMENS.
    #   Blip - Uses AFNI 3dQWarp to calculate the distortion unwarp for EPI field maps of opposite/same phase encoding direction.
    #   Blip-FSL-TOPUP - Uses FSL TOPUP to calculate the distortion unwarp for EPI field maps of opposite/same phase encoding direction.
    using: ['PhaseDiff', 'Blip']

    # option parameters
    PhaseDiff:

      # Since the quality of the distortion heavily relies on the skull-stripping step, we provide a choice of method ('AFNI' for AFNI 3dSkullStrip or 'BET' for FSL BET).
      # Options: 'BET' or 'AFNI'
      fmap_skullstrip_option: 'BET'

      # Set the fraction value for the skull-stripping of the magnitude file. Depending on the data, a tighter extraction may be necessary in order to prevent noisy voxels from interfering with preparing the field map.
      # The default value is 0.5.
      fmap_skullstrip_BET_frac: 0.5

      # Set the threshold value for the skull-stripping of the magnitude file. Depending on the data, a tighter extraction may be necessary in order to prevent noisy voxels from interfering with preparing the field map.
      # The default value is 0.6.
      fmap_skullstrip_AFNI_threshold:  0.6
      
    Blip-FSL-TOPUP:
      
      # (approximate) resolution (in mm) of warp basis for the different sub-sampling levels, default 10
      warpres: 10
      
      # sub-sampling scheme, default 1
      subsamp: 1
      
      # FWHM (in mm) of gaussian smoothing kernel, default 8
      fwhm: 8
      
      # Max # of non-linear iterations, default 5
      miter: 5
      
      # Weight of regularisation, default depending on --ssqlambda and --regmod switches. See user documentation.
      lambda: 1
      
      # If set (=1), lambda is weighted by current ssq, default 1
      ssqlambda: 1
      
      # Model for regularisation of warp-field [membrane_energy bending_energy], default bending_energy
      regmod: bending_energy
      
      # Estimate movements if set, default 1 (true)
      estmov: 1
      
      # Minimisation method 0=Levenberg-Marquardt, 1=Scaled Conjugate Gradient, default 0 (LM)
      minmet: 0
      
      # Order of spline, 2->Qadratic spline, 3->Cubic spline. Default=3
      splineorder: 3
      
      # Precision for representing Hessian, double or float. Default double
      numprec: double
      
      # Image interpolation model, linear or spline. Default spline
      interp: spline
      
      # If set (=1), the images are individually scaled to a common mean, default 0 (false)
      scale: 0
      
      # If set (=1), the calculations are done in a different grid, default 1 (true)
      regrid: 1

Functional to Anatomical Registration¶

Run Functional-to-Anatomical Registration - [On, Off]: Register the functional timeseries and functional mean images to the T1 anatomical images.
Using BB Register - [On, Off, On/Off]: Use Boundary-Based Registration in the functional-to-anatomical registration process. This uses the anatomical segmentation outputs to improve the co-registration of functional images to the anatomical. However, this may not be the best option if your anatomical images feature low contrast, resulting in segmentation which may not be of high quality.
Boundary Based Registration Scheduler - [path]: Standard FSL 5.0 Scheduler used for Boundary Based Registration. It is not necessary to change this path unless you intend to use non-standard MNI registration.
Use as Functional-to-Anatomical Registration Input - [Mean Functional, Selected Functional Volume]: Choose whether to use the mean of the functional/EPI as the input to functional-to-anatomical registration or one of the volumes from the functional 4D timeseries that you choose.
Functional Volume to Use as Input (Selected Functional Volume only) - [integer]: Only for when ‘Use as Functional-to-Anatomical Registration Input’ is set to ‘Selected Functional Volume’. Input the index of which volume from the functional 4D timeseries input file you wish to use as the input for functional-to-anatomical registration.
Functional Masking - [AFNI, FSL, FSL_AFNI, Anatomical_Refined]: Choose which tool to be used in functional masking - AFNI (3dAutoMask), FSL (BET), FSL_AFNI (BET+3dAutoMask) or Anatomical_Refined (generate functional mask by registering anatomical mask to functional space). Default is AFNI.

Configuration Without the GUI¶

The following nested key/value pairs will be set to these defaults if not defined in your pipeline configuration YAML.

registration_workflows:

  functional_registration:

    coregistration:
      # functional (BOLD/EPI) registration to anatomical (structural/T1)

      run: On

      func_input_prep:

        # Choose whether to use functional brain or skull as the input to functional-to-anatomical registration
        reg_with_skull: Off

        # Choose whether to use the mean of the functional/EPI as the input to functional-to-anatomical registration or one of the volumes from the functional 4D timeseries that you choose.
        # input: ['Mean_Functional', 'Selected_Functional_Volume', 'fmriprep_reference']
        input: ['Mean_Functional']

        Mean Functional:

          # Run ANTs’ N4 Bias Field Correction on the input BOLD (EPI)
          # this can increase tissue contrast which may improve registration quality in some data
          n4_correct_func: False

        Selected Functional Volume:

          # Only for when 'Use as Functional-to-Anatomical Registration Input' is set to 'Selected Functional Volume'.
          #Input the index of which volume from the functional 4D timeseries input file you wish to use as the input for functional-to-anatomical registration.
          func_reg_input_volume: 0

      boundary_based_registration:
        # this is a fork point
        #   run: [On, Off] - this will run both and fork the pipeline
        run: [On]

        # Standard FSL 5.0 Scheduler used for Boundary Based Registration.
        # It is not necessary to change this path unless you intend to use non-standard MNI registration.
        bbr_schedule: $FSLDIR/etc/flirtsch/bbr.sch

        # reference for boundary based registration
        # options: 'whole-head' or 'brain'
        reference: whole-head

        # choose which FAST map to generate BBR WM mask
        # options: 'probability_map', 'partial_volume_map'
        bbr_wm_map: 'probability_map'

        # optional FAST arguments to generate BBR WM mask
        bbr_wm_mask_args: '-thr 0.5 -bin'

functional_preproc:

  func_masking:
    run: On
    # using: ['AFNI', 'FSL', 'FSL_AFNI', 'Anatomical_Refined', 'Anatomical_Based', 'Anatomical_Resampled', 'CCS_Anatomical_Refined']

    # FSL_AFNI: fMRIPrep-style BOLD mask. Ref: https://github.com/nipreps/niworkflows/blob/a221f612/niworkflows/func/util.py#L246-L514
    # Anatomical_Refined: 1. binarize anat mask, in case it is not a binary mask. 2. fill holes of anat mask 3. init_bold_mask : input raw func → dilate init func brain mask 4. refined_bold_mask : input motion corrected func → dilate anatomical mask 5. get final func mask
    # Anatomical_Based: Generate the BOLD mask by basing it off of the anatomical brain mask. Adapted from DCAN Lab's BOLD mask method from the ABCD pipeline.
    # Anatomical_Resampled: Resample anatomical brain mask in standard space to get BOLD brain mask in standard space. Adapted from DCAN Lab's BOLD mask method from the ABCD pipeline. ("Create fMRI resolution standard space files for T1w image, wmparc, and brain mask […] don't use FLIRT to do spline interpolation with -applyisoxfm for the 2mm and 1mm cases because it doesn't know the peculiarities of the MNI template FOVs")
    # CCS_Anatomical_Refined: Generate the BOLD mask by basing it off of the anatomical brain. Adapted from the BOLD mask method from the CCS pipeline.

    # this is a fork point
    using: ['AFNI']

Configuring FSL BET options:¶

Note: These options are pre-set for FSL BET’s default values. These do not need to be modified unless you are looking to optimize the results of skull-stripping for your particular dataset.

Threshold - [0.3]: Set the threshold value controlling the brain vs non-brain voxels. Default is 0.3
Radius - [0]: Integer value of head radius. Default is 0.
Vertical gradient - [0]: Vertical gradient un fractional intensity threshold. Within the range of (-1,1).
Func_mean - [Off,On]: Apply to 4D FMRI data, if bold_bet_functional_mean_boolean : Off. Mutually exclusive with functional,reduce_bias,robust,padding,remove_eyes,surfaces. Default is Off.
Apply Threshold - [Off,On]: Apply thresholding to segmented brain image and mask. Default is Off.
Mask - [Off, On]: Mask created along with skull stripping. Default option is Off.
Mesh - [Off, On]: Mesh created along with skull stripping. Default is Off.
Skull - [Off,On]: Create a Skull Image. Default is Off.
Surfaces - [Off, On]: Get additional skull and scalp surfaces by running bet2 and betsurf. This is mutually exclusive with reduce bias, robust, padding, remove_eyes.
Surfaces Outline - [Off, On]: Create a surface outline image, Default is Off.
Padding - [Off, On]: Add padding to the end of the image, improving BET. Mutually exclusive functional, reduce_bias, robust, padding, remove_eyes, surfaces.
Reduce bias - [Off, On]: Reduce bias and cleanup neck. Mutually exclusive with functional, reduce_bias, robust, padding, remove_eyes, surfaces.
Remove eyes - [Off,On]: Eyes and optic nerve cleanup. Mutually exclusive with functional, reduce_bias, robust, padding, remove_eyes, surfaces.
Robust brain center - [Off, On]: Robust brain center estimation. Mutually exclusive with functional, reduce_bias, robust, padding, remove_eyes, surfaces.

Configuration Without the GUI¶

The following nested key/value pairs will be set to these defaults if not defined in your pipeline configuration YAML.

functional_preproc:

    FSL-BET:
      # Switch "On" to crop out neck regions before generating the mask (default: Off).    
      Robustfov : Off
      
      # Set the threshold value controling the brain vs non-brain voxels, default is 0.5
      frac: 0.5

      # Mesh created along with skull stripping
      mesh_boolean: Off

      # Create a surface outline image
      outline: Off

      # Add padding to the end of the image, improving BET.Mutually exclusive with functional,reduce_bias,robust,padding,remove_eyes,surfaces
      padding: Off

      # Integer value of head radius
      radius: 0

      # Reduce bias and cleanup neck. Mutually exclusive with functional,reduce_bias,robust,padding,remove_eyes,surfaces
      reduce_bias: Off

      # Eyes and optic nerve cleanup. Mutually exclusive with functional,reduce_bias,robust,padding,remove_eyes,surfaces
      remove_eyes: Off

      # Robust brain center estimation. Mutually exclusive with functional,reduce_bias,robust,padding,remove_eyes,surfaces
      robust: On

      # Create a skull image
      skull: Off

      # Gets additional skull and scalp surfaces by running bet2 and betsurf. This is mutually exclusive with reduce_bias, robust, padding, remove_eyes
      surfaces: Off

      # Apply thresholding to segmented brain image and mask
      threshold: Off

      # Vertical gradient in fractional intensity threshold (-1,1)
      vertical_gradient : 0.0

    UNet:

      # UNet model
      unet_model : s3://fcp-indi/resources/cpac/resources/Site-All-T-epoch_36.model

    niworkflows-ants:

      # Template to be used during niworkflows-ants.
      # It is not necessary to change this path unless you intend to use a non-standard template.

      # niworkflows-ants Brain extraction template
      template_path : /ants_template/oasis/T_template0.nii.gz

      # niworkflows-ants probability mask
      mask_path : /ants_template/oasis/T_template0_BrainCerebellumProbabilityMask.nii.gz

      # niworkflows-ants registration mask (can be optional)
      regmask_path : /ants_template/oasis/T_template0_BrainCerebellumRegistrationMask.nii.gz

    FreeSurfer-BET:

      # Template to be used for FreeSurfer-BET brain extraction in CCS-options pipeline
      T1w_brain_template_mask_ccs: /ccs_template/MNI152_T1_1mm_first_brain_mask.nii.gz


segmentation:

  # Automatically segment anatomical images into white matter, gray matter,
  # and CSF based on prior probability maps.
  run: On

  tissue_segmentation:

    # using: ['FSL-FAST', 'Template_Based', 'ANTs_Prior_Based', 'FreeSurfer']
    # this is a fork point
    using: ['FSL-FAST']

    # option parameters
    FSL-FAST:

      thresholding:

        # thresholding of the tissue segmentation probability maps
        # options: 'Auto', 'Custom'
        use: 'Auto'

        Custom:
          # Set the threshold value for the segmentation probability masks (CSF, White Matter, and Gray Matter)
          # The values remaining will become the binary tissue masks.
          # A good starting point is 0.95.

          # CSF (cerebrospinal fluid) threshold.
          CSF_threshold_value : 0.95

          # White matter threshold.
          WM_threshold_value : 0.95

          # Gray matter threshold.
          GM_threshold_value : 0.95

      use_priors:

        # Use template-space tissue priors to refine the binary tissue masks generated by segmentation.
        run: On

        # Full path to a directory containing binarized prior probability maps.
        # These maps are included as part of the 'Image Resource Files' package available on the Install page of the User Guide.
        # It is not necessary to change this path unless you intend to use non-standard priors.
        priors_path: $FSLDIR/data/standard/tissuepriors/2mm

        # Full path to a binarized White Matter prior probability map.
        # It is not necessary to change this path unless you intend to use non-standard priors.
        WM_path: $priors_path/avg152T1_white_bin.nii.gz

        # Full path to a binarized Gray Matter prior probability map.
        # It is not necessary to change this path unless you intend to use non-standard priors.
        GM_path: $priors_path/avg152T1_gray_bin.nii.gz

        # Full path to a binarized CSF prior probability map.
        # It is not necessary to change this path unless you intend to use non-standard priors.
        CSF_path: $priors_path/avg152T1_csf_bin.nii.gz

    Template_Based:

      # These masks should be in the same space of your registration template, e.g. if
      # you choose 'EPI Template' , below tissue masks should also be EPI template tissue masks.
      #
      # Options: ['T1_Template', 'EPI_Template']
      template_for_segmentation: ['T1_Template']

      # These masks are included as part of the 'Image Resource Files' package available
      # on the Install page of the User Guide.

      # Full path to a binarized White Matter mask.
      WHITE: $FSLDIR/data/standard/tissuepriors/2mm/avg152T1_white_bin.nii.gz

      # Full path to a binarized Gray Matter mask.
      GRAY: $FSLDIR/data/standard/tissuepriors/2mm/avg152T1_gray_bin.nii.gz

      # Full path to a binarized CSF mask.
      CSF: $FSLDIR/data/standard/tissuepriors/2mm/avg152T1_csf_bin.nii.gz

    ANTs_Prior_Based:

      # Generate white matter, gray matter, CSF masks based on antsJointLabelFusion
      # ANTs Prior-based Segmentation workflow that has shown optimal results for non-human primate data.

      # The atlas image assumed to be used in ANTs Prior-based Segmentation.
      template_brain_list :
        - /cpac_templates/MacaqueYerkes19_T1w_0.5mm_desc-JLC_T1w_brain.nii.gz
        - /cpac_templates/J_Macaque_11mo_atlas_nACQ_194x252x160space_0.5mm_desc-JLC_T1w_brain.nii.gz

      # The atlas segmentation images.
      # For performing ANTs Prior-based segmentation method
      # the number of specified segmentations should be identical to the number of atlas brain image sets.
      # eg.
      # ANTs_prior_seg_template_brain_list :
      #   - atlas1.nii.gz
      #   - atlas2.nii.gz
      # ANTs_prior_seg_template_segmentation_list:
      #   - segmentation1.nii.gz
      #   - segmentation1.nii.gz
      template_segmentation_list:
        - /cpac_templates/MacaqueYerkes19_T1w_0.5mm_desc-JLC_Segmentation.nii.gz
        - /cpac_templates/J_Macaque_11mo_atlas_nACQ_194x252x160space_0.5mm_desc-JLC_Segmentation.nii.gz

      # Label values corresponding to CSF/GM/WM in atlas file
      # It is not necessary to change this values unless your CSF/GM/WM label values are different from Freesurfer Color Lookup Table.
      # https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT

      # Label values corresponding to CSF in multiatlas file
      CSF_label : [24]

      # Label values corresponding to Gray Matter in multiatlas file
      GM_label : [3, 42]

      # Label values corresponding to White Matter in multiatlas file
      WM_label : [2, 41]

    FreeSurfer:

      # Use mri_binarize --erode option to erode segmentation masks
      erode: 0

      # Label values corresponding to CSF in FreeSurfer aseg segmentation file
      CSF_label : [24]

      # Label values corresponding to Gray Matter in FreeSurfer aseg segmentation file
      GM_label : [3, 42]

      # Label values corresponding to White Matter in FreeSurfer aseg segmentation file
      WM_label : [2, 41]


registration_workflows:

  anatomical_registration:

    run: On

    # The resolution to which anatomical images should be transformed during registration.
    # This is the resolution at which processed anatomical files will be output.
    resolution_for_anat: 2mm

    # Template to be used during registration.
    # It is not necessary to change this path unless you intend to use a non-standard template.
    T1w_brain_template: $FSLDIR/data/standard/MNI152_T1_${resolution_for_anat}_brain.nii.gz

    # Template to be used during registration.
    # It is not necessary to change this path unless you intend to use a non-standard template.
    T1w_template: $FSLDIR/data/standard/MNI152_T1_${resolution_for_anat}.nii.gz

    # Template to be used during registration.
    # It is not necessary to change this path unless you intend to use a non-standard template.
    T1w_brain_template_mask: $FSLDIR/data/standard/MNI152_T1_${resolution_for_anat}_brain_mask.nii.gz

    # Register skull-on anatomical image to a template.
    reg_with_skull: True

    registration:

      # using: ['ANTS', 'FSL', 'FSL-linear']
      # this is a fork point
      #   selecting both ['ANTS', 'FSL'] will run both and fork the pipeline
      using: ['ANTS']

      # option parameters
      ANTs:

        # If a lesion mask is available for a T1w image, use it to improve the ANTs' registration
        # ANTS registration only.
        use_lesion_mask: False

        # ANTs parameters for T1-template-based registration
        T1_registration:

          - collapse-output-transforms: 0
          - dimensionality: 3
          - initial-moving-transform :
             initializationFeature: 0

          - transforms:
             - Rigid:
                 gradientStep : 0.1
                 metric :
                   type : MI
                   metricWeight: 1
                   numberOfBins : 32
                   samplingStrategy : Regular
                   samplingPercentage : 0.25
                 convergence:
                   iteration : 1000x500x250x100
                   convergenceThreshold : 1e-08
                   convergenceWindowSize : 10
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 8x4x2x1
                 use-histogram-matching : True

             - Affine:
                 gradientStep : 0.1
                 metric :
                   type : MI
                   metricWeight: 1
                   numberOfBins : 32
                   samplingStrategy : Regular
                   samplingPercentage : 0.25
                 convergence:
                   iteration : 1000x500x250x100
                   convergenceThreshold : 1e-08
                   convergenceWindowSize : 10
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 8x4x2x1
                 use-histogram-matching : True

             - SyN:
                 gradientStep : 0.1
                 updateFieldVarianceInVoxelSpace : 3.0
                 totalFieldVarianceInVoxelSpace : 0.0
                 metric:
                   type : CC
                   metricWeight: 1
                   radius : 4
                 convergence:
                   iteration : 100x100x70x20
                   convergenceThreshold : 1e-09
                   convergenceWindowSize : 15
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 6x4x2x1
                 use-histogram-matching : True
                 winsorize-image-intensities :
                   lowerQuantile : 0.01
                   upperQuantile : 0.99

        # Interpolation method for writing out transformed anatomical images.
        # Possible values: Linear, BSpline, LanczosWindowedSinc
        interpolation: LanczosWindowedSinc

      FSL-FNIRT:

        # Configuration file to be used by FSL to set FNIRT parameters.
        # It is not necessary to change this path unless you intend to use custom FNIRT parameters or a non-standard template.
        fnirt_config: T1_2_MNI152_2mm

        # The resolution to which anatomical images should be transformed during registration.
        # This is the resolution at which processed anatomical files will be output. 
        # specifically for monkey pipeline
        ref_resolution: 2mm

        # Reference mask for FSL registration.
        ref_mask: $FSLDIR/data/standard/MNI152_T1_${resolution_for_anat}_brain_mask_dil.nii.gz
        
        # Template to be used during registration.
        # It is for monkey pipeline specifically. 
        FNIRT_T1w_brain_template: None

        # Template to be used during registration.
        # It is for monkey pipeline specifically. 
        FNIRT_T1w_template: None
        
        # Interpolation method for writing out transformed anatomical images.
        # Possible values: trilinear, sinc, spline
        interpolation: sinc

        # Identity matrix used during FSL-based resampling of anatomical-space data throughout the pipeline.
        # It is not necessary to change this path unless you intend to use a different template.
        identity_matrix: $FSLDIR/etc/flirtsch/ident.mat

        # Reference mask with 2mm resolution to be used during FNIRT-based brain extraction in ABCD-options pipeline.
        ref_mask_res-2: $FSLDIR/data/standard/MNI152_T1_2mm_brain_mask_dil.nii.gz

        # Template with 2mm resolution to be used during FNIRT-based brain extraction in ABCD-options pipeline.
        T1w_template_res-2: $FSLDIR/data/standard/MNI152_T1_2mm.nii.gz

    overwrite_transform:

      run: Off

      # Choose the tool to overwrite transform, currently only support 'FSL' to overwrite 'ANTs' transforms in ABCD-options pipeline.
      # using: 'FSL'
      using: FSL

  functional_registration:

    coregistration:
      # functional (BOLD/EPI) registration to anatomical (structural/T1)

      run: On

      # reference: 'brain' or 'restore-brain'
      # In ABCD-options pipeline, 'restore-brain' is used as coregistration reference
      reference: brain

      # Choose FSL or ABCD as coregistration method
      using: FSL

      # Choose brain or whole-head as coregistration input
      input: brain

      # Choose coregistration interpolation
      interpolation: trilinear

      # Choose coregistration cost function
      cost: corratio

      # Choose coregistration degree of freedom
      dof: 6

      # Extra arguments for FSL flirt
      arguments: None

      func_input_prep:

        # Choose whether to use functional brain or skull as the input to functional-to-anatomical registration
        reg_with_skull: Off

        # Choose whether to use the mean of the functional/EPI as the input to functional-to-anatomical registration or one of the volumes from the functional 4D timeseries that you choose.
        # input: ['Mean_Functional', 'Selected_Functional_Volume', 'fmriprep_reference']
        input: ['Mean_Functional']

        Mean Functional:

          # Run ANTs’ N4 Bias Field Correction on the input BOLD (EPI)
          # this can increase tissue contrast which may improve registration quality in some data
          n4_correct_func: False

        Selected Functional Volume:

          # Only for when 'Use as Functional-to-Anatomical Registration Input' is set to 'Selected Functional Volume'.
          #Input the index of which volume from the functional 4D timeseries input file you wish to use as the input for functional-to-anatomical registration.
          func_reg_input_volume: 0

      boundary_based_registration:
        # this is a fork point
        #   run: [On, Off] - this will run both and fork the pipeline
        run: [On]

        # Standard FSL 5.0 Scheduler used for Boundary Based Registration.
        # It is not necessary to change this path unless you intend to use non-standard MNI registration.
        bbr_schedule: $FSLDIR/etc/flirtsch/bbr.sch

        # reference for boundary based registration
        # options: 'whole-head' or 'brain'
        reference: whole-head

        # choose which FAST map to generate BBR WM mask
        # options: 'probability_map', 'partial_volume_map'
        bbr_wm_map: 'probability_map'

        # optional FAST arguments to generate BBR WM mask
        bbr_wm_mask_args: '-thr 0.5 -bin'

    EPI_registration:

      # directly register the mean functional to an EPI template
      #   instead of applying the anatomical T1-to-template transform to the functional data that has been
      #   coregistered to anatomical/T1 space
      run: Off

      # using: ['ANTS', 'FSL', 'FSL-linear']
      # this is a fork point
      # ex. selecting both ['ANTS', 'FSL'] will run both and fork the pipeline
      using: ['ANTS']

      # EPI template for direct functional-to-template registration
      # (bypassing coregistration and the anatomical-to-template transforms)
      EPI_template: s3://fcp-indi/resources/cpac/resources/epi_hbn.nii.gz

      # EPI template mask.
      EPI_template_mask: None

      ANTs:

        # EPI registration configuration - synonymous with T1_registration
        # parameters under anatomical registration above
        parameters:

          - collapse-output-transforms: 0
          - dimensionality: 3
          - initial-moving-transform :
             initializationFeature: 0

          - transforms:
             - Rigid:
                 gradientStep : 0.1
                 metric :
                   type : MI
                   metricWeight: 1
                   numberOfBins : 32
                   samplingStrategy : Regular
                   samplingPercentage : 0.25
                 convergence:
                   iteration : 1000x500x250x100
                   convergenceThreshold : 1e-08
                   convergenceWindowSize : 10
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 8x4x2x1
                 use-histogram-matching : True

             - Affine:
                 gradientStep : 0.1
                 metric :
                   type : MI
                   metricWeight: 1
                   numberOfBins : 32
                   samplingStrategy : Regular
                   samplingPercentage : 0.25
                 convergence:
                   iteration : 1000x500x250x100
                   convergenceThreshold : 1e-08
                   convergenceWindowSize : 10
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 8x4x2x1
                 use-histogram-matching : True

             - SyN:
                 gradientStep : 0.1
                 updateFieldVarianceInVoxelSpace : 3.0
                 totalFieldVarianceInVoxelSpace : 0.0
                 metric:
                   type : CC
                   metricWeight: 1
                   radius : 4
                 convergence:
                   iteration : 100x100x70x20
                   convergenceThreshold : 1e-09
                   convergenceWindowSize : 15
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 6x4x2x1
                 use-histogram-matching : True
                 winsorize-image-intensities :
                   lowerQuantile : 0.01
                   upperQuantile : 0.99

        # Interpolation method for writing out transformed EPI images.
        # Possible values: Linear, BSpline, LanczosWindowedSinc
        interpolation: LanczosWindowedSinc

      FSL-FNIRT:

        # Configuration file to be used by FSL to set FNIRT parameters.
        # It is not necessary to change this path unless you intend to use custom FNIRT parameters or a non-standard template.
        fnirt_config: T1_2_MNI152_2mm

        # Interpolation method for writing out transformed EPI images.
        # Possible values: trilinear, sinc, spline
        interpolation: sinc

        # Identity matrix used during FSL-based resampling of BOLD-space data throughout the pipeline.
        # It is not necessary to change this path unless you intend to use a different template.
        identity_matrix: $FSLDIR/etc/flirtsch/ident.mat

    func_registration_to_template:

      # these options modify the application (to the functional data), not the calculation, of the
      # T1-to-template and EPI-to-template transforms calculated earlier during registration
      
      # apply the functional-to-template (T1 template) registration transform to the functional data
      run: On
      
      # apply the functional-to-template (EPI template) registration transform to the functional data
      run_EPI: Off

      output_resolution:

        # The resolution (in mm) to which the preprocessed, registered functional timeseries outputs are written into.
        # NOTE:
        #   selecting a 1 mm or 2 mm resolution might substantially increase your RAM needs- these resolutions should be selected with caution.
        #   for most cases, 3 mm or 4 mm resolutions are suggested.
        # NOTE:
        #   this also includes the single-volume 3D preprocessed functional data,
        #   such as the mean functional (mean EPI) in template space
        func_preproc_outputs: 3mm

        # The resolution (in mm) to which the registered derivative outputs are written into.
        # NOTE:
        #   this is for the single-volume functional-space outputs (i.e. derivatives)
        #   thus, a higher resolution may not result in a large increase in RAM needs as above
        func_derivative_outputs: 3mm

      target_template:      
        # choose which template space to transform derivatives towards
        # using: ['T1_template', 'EPI_template']
        # this is a fork point
        # NOTE:
        #   this will determine which registration transform to use to warp the functional
        #   outputs and derivatives to template space
        using: ['T1_template']

        T1_template:

          # Standard Skull Stripped Template. Used as a reference image for functional registration.
          # This can be different than the template used as the reference/fixed for T1-to-template registration.
          T1w_brain_template_funcreg: $FSLDIR/data/standard/MNI152_T1_${func_resolution}_brain.nii.gz

          # Standard Anatomical Brain Image with Skull.
          # This can be different than the template used as the reference/fixed for T1-to-template registration.
          T1w_template_funcreg: $FSLDIR/data/standard/MNI152_T1_${func_resolution}.nii.gz

          # Template to be used during registration.
          # It is not necessary to change this path unless you intend to use a non-standard template.
          T1w_brain_template_mask_funcreg: $FSLDIR/data/standard/MNI152_T1_${func_resolution}_brain_mask.nii.gz

          # a standard template for resampling if using float resolution
          T1w_template_for_resample:  $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz

        EPI_template:

          # EPI template for direct functional-to-template registration
          # (bypassing coregistration and the anatomical-to-template transforms)
          EPI_template_funcreg: s3://fcp-indi/resources/cpac/resources/epi_hbn.nii.gz

          # EPI template mask.
          EPI_template_mask_funcreg: None

          # a standard template for resampling if using float resolution
          EPI_template_for_resample:  $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz

      ANTs_pipelines:

        # Interpolation method for writing out transformed functional images.
        # Possible values: Linear, BSpline, LanczosWindowedSinc
        interpolation: LanczosWindowedSinc

      FNIRT_pipelines:

        # Interpolation method for writing out transformed functional images.
        # Possible values: trilinear, sinc, spline
        interpolation: sinc

        # Identity matrix used during FSL-based resampling of functional-space data throughout the pipeline.
        # It is not necessary to change this path unless you intend to use a different template.
        identity_matrix: $FSLDIR/etc/flirtsch/ident.mat

      apply_transform:

        # options: 'default', 'abcd', 'single_step_resampling_from_stc', 'dcan_nhp'
        # 'default': apply func-to-anat and anat-to-template transforms on motion corrected functional image.
        # 'abcd': apply motion correction, func-to-anat and anat-to-template transforms on each of raw functional volume using FSL applywarp based on ABCD-HCP pipeline.
        # 'single_step_resampling_from_stc': apply motion correction, func-to-anat and anat-to-template transforms on each of slice-time-corrected functional volume using ANTs antsApplyTransform based on fMRIPrep pipeline.
        #   - if 'single_step_resampling_from_stc', 'template' is the only valid option for ``nuisance_corrections: 2-nuisance_regression: space``
        using: 'default'


functional_preproc:

  run: On

  update_header: 

    # Convert raw data from LPI to RPI
    run: On
  
  truncation:

    # First timepoint to include in analysis.
    # Default is 0 (beginning of timeseries).
    # First timepoint selection in the scan parameters in the data configuration file, if present, will over-ride this selection.
    # Note: the selection here applies to all scans of all participants.
    start_tr: 0

    # Last timepoint to include in analysis.
    # Default is None or End (end of timeseries).
    # Last timepoint selection in the scan parameters in the data configuration file, if present, will over-ride this selection.
    # Note: the selection here applies to all scans of all participants.
    stop_tr: None

  scaling:

    # Scale functional raw data, usually used in rodent pipeline
    run: Off

    # Scale the size of the dataset voxels by the factor.
    scaling_factor: 10

  despiking:

    # Run AFNI 3dDespike
    # this is a fork point
    #   run: [On, Off] - this will run both and fork the pipeline
    run: [Off]

  slice_timing_correction:

    # Interpolate voxel time courses so they are sampled at the same time points.
    # this is a fork point
    #   run: [On, Off] - this will run both and fork the pipeline
    run: [On]

    # use specified slice time pattern rather than one in header
    tpattern: None

    # align each slice to given time offset
    # The default alignment time is the average of the 'tpattern' values (either from the dataset header or from the tpattern option).
    tzero: None

  motion_estimates_and_correction:
  
    run: On

    motion_estimates: 

      # calculate motion statistics BEFORE slice-timing correction
      calculate_motion_first: Off

      # calculate motion statistics AFTER motion correction
      calculate_motion_after: On

    motion_correction:

      # using: ['3dvolreg', 'mcflirt']
      # Forking is currently broken for this option.
      # Please use separate configs if you want to use each of 3dvolreg and mcflirt.
      # Follow https://github.com/FCP-INDI/C-PAC/issues/1935 to see when this issue is resolved.
      using: ['3dvolreg']

      # option parameters
      AFNI-3dvolreg:

        # This option is useful when aligning high-resolution datasets that may need more alignment than a few voxels.
        functional_volreg_twopass: On

      # Choose motion correction reference. Options: mean, median, selected_volume, fmriprep_reference
      motion_correction_reference: ['mean']

      # Choose motion correction reference volume
      motion_correction_reference_volume: 0

    motion_estimate_filter:

      # Filter physiological (respiration) artifacts from the head motion estimates.
      # Adapted from DCAN Labs filter.
      #     https://www.ohsu.edu/school-of-medicine/developmental-cognition-and-neuroimaging-lab
      #     https://www.biorxiv.org/content/10.1101/337360v1.full.pdf
      # this is a fork point
      #   run: [On, Off] - this will run both and fork the pipeline
      run: [Off]

      filters:
        - # options: "notch", "lowpass"
          filter_type: "notch"

          # Number of filter coefficients.
          filter_order: 4

          # Dataset-wide respiratory rate data from breathing belt.
          # Notch filter requires either:
          #     "breathing_rate_min" and "breathing_rate_max"
          # or
          #     "center_frequency" and "filter_bandwitdh".
          # Lowpass filter requires either:
          #     "breathing_rate_min"
          # or
          #     "lowpass_cutoff".
          # If "breathing_rate_min" (for lowpass and notch filter)
          # and "breathing_rate_max" (for notch filter) are set,
          # the values set in "lowpass_cutoff" (for lowpass filter),
          # "center_frequency" and "filter_bandwidth" (for notch filter)
          # options are ignored.

          # Lowest Breaths-Per-Minute in dataset.
          # For both notch and lowpass filters.
          breathing_rate_min:

          # Highest Breaths-Per-Minute in dataset.
          # For notch filter.
          breathing_rate_max:

          # notch filter direct customization parameters

          # mutually exclusive with breathing_rate options above.
          # If breathing_rate_min and breathing_rate_max are provided,
          # the following parameters will be ignored.

          # the center frequency of the notch filter
          center_frequency:

          # the width of the notch filter
          filter_bandwidth:

        - # options: "notch", "lowpass"
          filter_type: "lowpass"

          # Number of filter coefficients.
          filter_order: 4

          # Dataset-wide respiratory rate data from breathing belt.
          # Notch filter requires either:
          #     "breathing_rate_min" and "breathing_rate_max"
          # or
          #     "center_frequency" and "filter_bandwitdh".
          # Lowpass filter requires either:
          #     "breathing_rate_min"
          # or
          #     "lowpass_cutoff".
          # If "breathing_rate_min" (for lowpass and notch filter)
          # and "breathing_rate_max" (for notch filter) are set,
          # the values set in "lowpass_cutoff" (for lowpass filter),
          # "center_frequency" and "filter_bandwidth" (for notch filter)
          # options are ignored.

          # Lowest Breaths-Per-Minute in dataset.
          # For both notch and lowpass filters.
          breathing_rate_min:

          # lowpass filter direct customization parameter

          # mutually exclusive with breathing_rate options above.
          # If breathing_rate_min is provided, the following
          # parameter will be ignored.

          # the frequency cutoff of the filter
          lowpass_cutoff:

  distortion_correction:

    # this is a fork point
    #   run: [On, Off] - this will run both and fork the pipeline
    run: [On]

    # using: ['PhaseDiff', 'Blip', 'Blip-FSL-TOPUP']
    #   PhaseDiff - Perform field map correction using a single phase difference image, a subtraction of the two phase images from each echo. Default scanner for this method is SIEMENS.
    #   Blip - Uses AFNI 3dQWarp to calculate the distortion unwarp for EPI field maps of opposite/same phase encoding direction.
    #   Blip-FSL-TOPUP - Uses FSL TOPUP to calculate the distortion unwarp for EPI field maps of opposite/same phase encoding direction.
    using: ['PhaseDiff', 'Blip']

    # option parameters
    PhaseDiff:

      # Since the quality of the distortion heavily relies on the skull-stripping step, we provide a choice of method ('AFNI' for AFNI 3dSkullStrip or 'BET' for FSL BET).
      # Options: 'BET' or 'AFNI'
      fmap_skullstrip_option: 'BET'

      # Set the fraction value for the skull-stripping of the magnitude file. Depending on the data, a tighter extraction may be necessary in order to prevent noisy voxels from interfering with preparing the field map.
      # The default value is 0.5.
      fmap_skullstrip_BET_frac: 0.5

      # Set the threshold value for the skull-stripping of the magnitude file. Depending on the data, a tighter extraction may be necessary in order to prevent noisy voxels from interfering with preparing the field map.
      # The default value is 0.6.
      fmap_skullstrip_AFNI_threshold:  0.6
      
    Blip-FSL-TOPUP:
      
      # (approximate) resolution (in mm) of warp basis for the different sub-sampling levels, default 10
      warpres: 10
      
      # sub-sampling scheme, default 1
      subsamp: 1
      
      # FWHM (in mm) of gaussian smoothing kernel, default 8
      fwhm: 8
      
      # Max # of non-linear iterations, default 5
      miter: 5
      
      # Weight of regularisation, default depending on --ssqlambda and --regmod switches. See user documentation.
      lambda: 1
      
      # If set (=1), lambda is weighted by current ssq, default 1
      ssqlambda: 1
      
      # Model for regularisation of warp-field [membrane_energy bending_energy], default bending_energy
      regmod: bending_energy
      
      # Estimate movements if set, default 1 (true)
      estmov: 1
      
      # Minimisation method 0=Levenberg-Marquardt, 1=Scaled Conjugate Gradient, default 0 (LM)
      minmet: 0
      
      # Order of spline, 2->Qadratic spline, 3->Cubic spline. Default=3
      splineorder: 3
      
      # Precision for representing Hessian, double or float. Default double
      numprec: double
      
      # Image interpolation model, linear or spline. Default spline
      interp: spline
      
      # If set (=1), the images are individually scaled to a common mean, default 0 (false)
      scale: 0
      
      # If set (=1), the calculations are done in a different grid, default 1 (true)
      regrid: 1

  func_masking:
    run: On
    # using: ['AFNI', 'FSL', 'FSL_AFNI', 'Anatomical_Refined', 'Anatomical_Based', 'Anatomical_Resampled', 'CCS_Anatomical_Refined']

Functional to Template Registration¶

Run Functional to Template Registration - [On, Off]: Register functional images to a standard MNI152 template or EPI template. This option must be enabled if you wish to calculate any derivatives.
Functional Resolution - [1 An integer indicating three same dimensions (e.g., 1mm, 2mm, 3mm, 4mm); 2 A float number indicating three same dimensions (e.g., 3.5mm etc.); 3 Three numbers connected by ‘x’ indicating three different dimensions (e.g., 2.67mmx2.67mmx3mm etc.)]: The resolution (in mm) to which the preprocessed, registered functional timeseries outputs are written into. Note that selecting a 1 mm or 2 mm resolution might substantially increase your RAM needs- these resolutions should be selected with caution. For most cases, 3 mm or 4 mm resolutions are suggested. Float numbers and three different dimensions are supported.
Derivative Resolution - [1 An integer indicating three same dimensions (e.g., 1mm, 2mm, 3mm, 4mm); 2 A float number indicating three same dimensions (e.g., 3.5mm etc.); 3 Three numbers connected by ‘x’ indicating three different dimensions (e.g., 2.67mmx2.67mmx3mm etc.)]: The resolution (in mm) to which functional images are transformed during registration. Note that selecting a 1 mm or 2 mm resolution will substantially increase your RAM needs. For most cases, 3 mm or 4 mm resolutions are suggested.
Standard Identity Matrix - [path]: Matrix containing all 1’s. Used as an identity matrix during registration. It is not necessary to change this path unless you intend to use non-standard MNI registration.
T1 Template Registration - [On, Off]: Register functional images to a standard MNI152 template.
Standard Brain only Template (functional resolution) - [path]: Standard FSL Skull Stripped Template. Used as a reference image for functional registration.
Standard Template with Skull (functional resolution) - [path]: Standard FSL Anatomical Brain Image with skull.
EPI Template Registration - [On, Off]: Register functional images to a standard EPI template.
Standard Brain Template - [path]: Used as a reference image for functional EPI registration.
ANTs Registration Parameters : Clicking on the setting icon will bring up a dialog where you can set ‘antsRegistration’ parameters.

Configuration Without the GUI¶

The following nested key/value pairs will be set to these defaults if not defined in your pipeline configuration YAML.

registration_workflows:

  functional_registration:

    EPI_registration:

      # directly register the mean functional to an EPI template
      #   instead of applying the anatomical T1-to-template transform to the functional data that has been
      #   coregistered to anatomical/T1 space
      run: Off

      # using: ['ANTS', 'FSL', 'FSL-linear']
      # this is a fork point
      # ex. selecting both ['ANTS', 'FSL'] will run both and fork the pipeline
      using: ['ANTS']

      # EPI template for direct functional-to-template registration
      # (bypassing coregistration and the anatomical-to-template transforms)
      EPI_template: s3://fcp-indi/resources/cpac/resources/epi_hbn.nii.gz

      # EPI template mask.
      EPI_template_mask: None

      ANTs:

        # EPI registration configuration - synonymous with T1_registration
        # parameters under anatomical registration above
        parameters:

          - collapse-output-transforms: 0
          - dimensionality: 3
          - initial-moving-transform :
             initializationFeature: 0

          - transforms:
             - Rigid:
                 gradientStep : 0.1
                 metric :
                   type : MI
                   metricWeight: 1
                   numberOfBins : 32
                   samplingStrategy : Regular
                   samplingPercentage : 0.25
                 convergence:
                   iteration : 1000x500x250x100
                   convergenceThreshold : 1e-08
                   convergenceWindowSize : 10
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 8x4x2x1
                 use-histogram-matching : True

             - Affine:
                 gradientStep : 0.1
                 metric :
                   type : MI
                   metricWeight: 1
                   numberOfBins : 32
                   samplingStrategy : Regular
                   samplingPercentage : 0.25
                 convergence:
                   iteration : 1000x500x250x100
                   convergenceThreshold : 1e-08
                   convergenceWindowSize : 10
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 8x4x2x1
                 use-histogram-matching : True

             - SyN:
                 gradientStep : 0.1
                 updateFieldVarianceInVoxelSpace : 3.0
                 totalFieldVarianceInVoxelSpace : 0.0
                 metric:
                   type : CC
                   metricWeight: 1
                   radius : 4
                 convergence:
                   iteration : 100x100x70x20
                   convergenceThreshold : 1e-09
                   convergenceWindowSize : 15
                 smoothing-sigmas : 3.0x2.0x1.0x0.0
                 shrink-factors : 6x4x2x1
                 use-histogram-matching : True
                 winsorize-image-intensities :
                   lowerQuantile : 0.01
                   upperQuantile : 0.99

        # Interpolation method for writing out transformed EPI images.
        # Possible values: Linear, BSpline, LanczosWindowedSinc
        interpolation: LanczosWindowedSinc

      FSL-FNIRT:

        # Configuration file to be used by FSL to set FNIRT parameters.
        # It is not necessary to change this path unless you intend to use custom FNIRT parameters or a non-standard template.
        fnirt_config: T1_2_MNI152_2mm

        # Interpolation method for writing out transformed EPI images.
        # Possible values: trilinear, sinc, spline
        interpolation: sinc

        # Identity matrix used during FSL-based resampling of BOLD-space data throughout the pipeline.
        # It is not necessary to change this path unless you intend to use a different template.
        identity_matrix: $FSLDIR/etc/flirtsch/ident.mat

    func_registration_to_template:

      # these options modify the application (to the functional data), not the calculation, of the
      # T1-to-template and EPI-to-template transforms calculated earlier during registration
      
      # apply the functional-to-template (T1 template) registration transform to the functional data
      run: On
      
      # apply the functional-to-template (EPI template) registration transform to the functional data
      run_EPI: Off

      output_resolution:

        # The resolution (in mm) to which the preprocessed, registered functional timeseries outputs are written into.
        # NOTE:
        #   selecting a 1 mm or 2 mm resolution might substantially increase your RAM needs- these resolutions should be selected with caution.
        #   for most cases, 3 mm or 4 mm resolutions are suggested.
        # NOTE:
        #   this also includes the single-volume 3D preprocessed functional data,
        #   such as the mean functional (mean EPI) in template space
        func_preproc_outputs: 3mm

        # The resolution (in mm) to which the registered derivative outputs are written into.
        # NOTE:
        #   this is for the single-volume functional-space outputs (i.e. derivatives)
        #   thus, a higher resolution may not result in a large increase in RAM needs as above
        func_derivative_outputs: 3mm

      target_template:      
        # choose which template space to transform derivatives towards
        # using: ['T1_template', 'EPI_template']
        # this is a fork point
        # NOTE:
        #   this will determine which registration transform to use to warp the functional
        #   outputs and derivatives to template space
        using: ['T1_template']

        T1_template:

          # Standard Skull Stripped Template. Used as a reference image for functional registration.
          # This can be different than the template used as the reference/fixed for T1-to-template registration.
          T1w_brain_template_funcreg: $FSLDIR/data/standard/MNI152_T1_${func_resolution}_brain.nii.gz

          # Standard Anatomical Brain Image with Skull.
          # This can be different than the template used as the reference/fixed for T1-to-template registration.
          T1w_template_funcreg: $FSLDIR/data/standard/MNI152_T1_${func_resolution}.nii.gz

          # Template to be used during registration.
          # It is not necessary to change this path unless you intend to use a non-standard template.
          T1w_brain_template_mask_funcreg: $FSLDIR/data/standard/MNI152_T1_${func_resolution}_brain_mask.nii.gz

          # a standard template for resampling if using float resolution
          T1w_template_for_resample:  $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz

        EPI_template:

          # EPI template for direct functional-to-template registration
          # (bypassing coregistration and the anatomical-to-template transforms)
          EPI_template_funcreg: s3://fcp-indi/resources/cpac/resources/epi_hbn.nii.gz

          # EPI template mask.
          EPI_template_mask_funcreg: None

          # a standard template for resampling if using float resolution
          EPI_template_for_resample:  $FSLDIR/data/standard/MNI152_T1_1mm_brain.nii.gz