Functional Preprocessing¶

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.

1. 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.
2. 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’.
3. TR - [numerical value]: The TR for volume acquisitions. If you wish to have this information read from the NifTI header set this to ‘None’.
4. Perform Slice Time Correction - [On, Off, On/Off]: Interpolate voxel timeseries so that sampling occurs at the same time.
5. 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 key/value pairs must be defined in your pipeline configuration YAML for C-PAC to run slice timing correction and drop TRs:

Key Description Potential Values
startIdx First timepoint to include in analysis. An integer.
stopIdx Last timepoint to include in analysis. An integer, or Stop or None to use the last possible timepoint.
TR The TR at which images were acquired. A number, or None if the TR is to be read from the NifTI header.
slice_timing_correction Interpolate voxel time courses so they are sampled at the same time points. A list where ‘1’ represents ‘yes’ and ‘0’ represents ‘no’ (e.g., ‘[1]’).
slice_timing_pattern Acquisition strategy for acquiring image slices. A list that can contain one of the following values: ‘Use NIFTI Header’,’alt+z’, ‘alt+z2’, ‘alt-z’, ‘alt-z2’, ‘seq+z’, ‘seq-z’

The box below contains an example of what these parameters might look like when defined in the YAML:

startIdx : 0
stopIdx : None
TR : None
slice_timing_correction : [0]


Through the Subject List¶

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, through a collection of tools produced by FMRIB’s FSL- primarily, a script which prepares field maps, and the FUGUE tool. Performing field map 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.

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.

1. Perform Field Map Distortion correction - [On, Off]: Perform field map-based distortion correction.
2. 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.
3. 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.
4. 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.
5. Dwell Time, in s - [float]: The dwell time is also known as echo spacing, and it 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). Here, the default value is 0.0005s.
6. Dwell to asymmetric ratio - [float]: This is the ratio between the Dwell time, as referenced above, and the asymmetric time. Here, the default value is 0.93902439.
7. 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 key/value pairs must be defined in your pipeline configuration YAML for C-PAC to run distortion correction:

The box below contains an example of what these parameters might look like when defined in the pipeline configuration YAML:

runEPI_DistCorr: [1]
fmap_distcorr_skullstrip: ["BET"]
fmap_distcorr_frac: [0.5]
fmap_distcorr_deltaTE : 2.46
fmap_distcorr_dwell_time : [0.0005]
fmap_distcorr_dwell_asym_ratio : [0.93902439]
fmap_distcorr_pedir: -y


Functional to Anatomical Registration¶

1. Run Functional-to-Anatomical Registration - [On, Off]: Register the functional timeseries and functional mean images to the T1 anatomical images.
2. 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.
3. 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.
4. 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.
5. 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.

Configuration Without the GUI¶

The following key/value pairs must be defined in your pipeline configuration YAML for C-PAC to run functional to anatomical registration:

Key Description Potential Values
runRegisterFuncToAnat Run Functional to Anatomical Registration. A list where ‘1’ represents ‘yes’ and ‘0’ represents ‘no’ (e.g., ‘[1]’).
runBBReg Run Functional to Anatomical Registration with BB Register A list where ‘1’ represents ‘yes’ and ‘0’ represents ‘no’ (e.g., ‘[1]’).
boundaryBasedRegistration Schedule 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. A path (e.g., /usr/share/fsl/5.0/etc/flirtsch/bbr.sch).
func_reg_input 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. A list that can contain one of the following values: “Mean Functional”,”Selected Functional Volume”
func_reg_input_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. Only for when func_reg_input is set to ‘Selected Functional Volume’. An integer.

The box below contains an example of what these parameters might look like when defined in the YAML:

runRegisterFuncToAnat : [1]
runBBReg : [1]
boundaryBasedRegistrationSchedule : /usr/share/fsl/5.0/etc/flirtsch/bbr.sch
func_reg_input :  ['Mean Functional']
func_reg_input_volume :  0


Functional to MNI Registration¶

1. Run Functional to MNI Registration - [On, Off]: Register functional images to a standard MNI152 template. This option must be enabled if you wish to calculate any derivatives.
2. Functional Standard Resolution - [1mm, 2mm, 3mm, 4mm]: 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.
3. Standard Brain only Template (functional resolution) - [path]: Standard FSL Skull Stripped Template. Used as a reference image for functional registration.
4. Standard Template with Skull (functional resolution) - [path]: Standard FSL Anatomical Brain Image with skull.
5. 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.
6. Resolutions to Resample to - [1mm, 2mm, 3mm, 4mm]: 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.

Configuration Without the GUI¶

The following key/value pairs must be defined in your pipeline configuration YAML for C-PAC to run functional to anatomical registration:

Key Description Potential Values
runRegisterFuncToMNI Register functional images to a standard MNI152 template. This option must be enabled if you wish to calculate any derivatives. A list where ‘1’ represents ‘yes’ and ‘0’ represents ‘no’ (e.g., ‘[1]’).
resolution_for_func The resolution (in mm) to which functional images are transformed during registration. 1mm,2mm,3mm,4mm
template_brain_only_for_func Standard FSL Skull Stripped Template. Used as a reference image for functional registration. A path (e.g., $FSLDIR/data/standard/MNI152_T1_${resolution_for_func}_brain.nii.gz).
template_skull_for_anat Standard FSL Template with skull. Used as a reference image for functional registration. A path (e.g., $FSLDIR/data/standard/MNI152_T1_${resolution_for_func}.nii.gz).
identityMatrix 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. A path (e.g., $FSLDIR/etc/flirtsch/ident.mat). resolution_for_func_derivative The resolutions to resample the normalized functional timeseries to. 1mm,2mm,3mm,4mm The box below contains an example of what these parameters might look like when defined in the YAML: runRegisterFuncToMNI : [1] resolution_for_func : 2mm template_brain_only_for_anat : /usr/share/fsl/5.0/data/standard/MNI152_T1_${resolution_for_anat}_brain.nii.gz
template_skull_for_anat : /usr/share/fsl/5.0/data/standard/MNI152_T1_\${resolution_for_anat}.nii.gz
identityMatrix : /usr/share/fsl/5.0/etc/flirtsch/ident.mat
resolution_for_func_derivative : 2mm