pipeline_config_fmriprep-options.yml

%YAML 1.1
---
# CPAC Pipeline Configuration YAML file
# Version 1.8.8.dev2
#
# http://fcp-indi.github.io for more info.
#
# Tip: This file can be edited manually with a text editor for quick modifications.
FROM: blank

pipeline_setup:

  # Name for this pipeline configuration - useful for identification.
  # This string will be sanitized and used in filepaths
  pipeline_name: cpac_fmriprep-options
  system_config:

    # Select Off if you intend to run CPAC on a single machine.
    # If set to On, CPAC will attempt to submit jobs through the job scheduler / resource manager selected below.
    on_grid:
      SGE:

        # SGE Parallel Environment to use when running CPAC.
        # Only applies when you are running on a grid or compute cluster using SGE.
        parallel_environment: cpac

    # The maximum amount of memory each participant's workflow can allocate.
    # Use this to place an upper bound of memory usage.
    # - Warning: 'Memory Per Participant' multiplied by 'Number of Participants to Run Simultaneously'
    #   must not be more than the total amount of RAM.
    # - Conversely, using too little RAM can impede the speed of a pipeline run.
    # - It is recommended that you set this to a value that when multiplied by
    #   'Number of Participants to Run Simultaneously' is as much RAM you can safely allocate.
    maximum_memory_per_participant: 3

  Amazon-AWS:

    # Enable server-side 256-AES encryption on data to the S3 bucket
    s3_encryption: On

anatomical_preproc:
  run: On
  acpc_alignment:

    # ACPC aligned template
    T1w_ACPC_template:

  brain_extraction:
    run: On
    FreeSurfer-BET:

      # Template to be used for FreeSurfer-BET brain extraction in CCS-options pipeline
      T1w_brain_template_mask_ccs:

    # using: ['3dSkullStrip', 'BET', 'UNet', 'niworkflows-ants', 'FreeSurfer-ABCD', 'FreeSurfer-BET-Tight', 'FreeSurfer-BET-Loose', 'FreeSurfer-Brainmask']
    # this is a fork option
    using: [niworkflows-ants]

segmentation:

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

    # option parameters
    FSL-FAST:
      thresholding:

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

      use_priors:

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

        # 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:

    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: []

      # 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:

      # Full path to a binarized Gray Matter mask.
      GRAY:

      # Full path to a binarized CSF mask.
      CSF:

    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:

      # 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:

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

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

      # 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: []

    FreeSurfer:

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

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

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

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

registration_workflows:
  anatomical_registration:
    run: On
    registration:
      FSL-FNIRT:

        # Reference mask with 2mm resolution to be used during FNIRT-based brain extraction in ABCD-options pipeline.
        ref_mask_res-2:

        # Template with 2mm resolution to be used during FNIRT-based brain extraction in ABCD-options pipeline.
        T1w_template_res-2:

        # Reference mask for FSL registration.
        ref_mask:

      # option parameters
      ANTs:

        # ANTs parameters for T1-template-based registration
        T1_registration:
          - collapse-output-transforms: 1
          - dimensionality: 3
          - initial-moving-transform:
              initializationFeature: 0
          - transforms:
            - Rigid:
                convergence:
                  convergenceThreshold: 1e-06
                  convergenceWindowSize: 20
                  iteration: 100x100
                gradientStep: 0.05
                metric:
                  metricWeight: 1
                  numberOfBins: 32
                  samplingPercentage: 0.25
                  samplingStrategy: Regular
                  type: MI
                shrink-factors: 2x1
                smoothing-sigmas: 2.0x1.0vox
                use-histogram-matching: On
            - Affine:
                convergence:
                  convergenceThreshold: 1e-06
                  convergenceWindowSize: 20
                  iteration: 100x100
                gradientStep: 0.08
                metric:
                  metricWeight: 1
                  numberOfBins: 32
                  samplingPercentage: 0.25
                  samplingStrategy: Regular
                  type: MI
                shrink-factors: 2x1
                smoothing-sigmas: 1.0x0.0vox
                use-histogram-matching: On
            - SyN:
                convergence:
                  convergenceThreshold: 1e-06
                  convergenceWindowSize: 10
                  iteration: 100x70x50x20
                gradientStep: 0.1
                metric:
                  metricWeight: 1
                  radius: 4
                  type: CC
                shrink-factors: 8x4x2x1
                smoothing-sigmas: 3.0x2.0x1.0x0.0vox
                totalFieldVarianceInVoxelSpace: 0.0
                updateFieldVarianceInVoxelSpace: 3.0
                use-histogram-matching: On
                winsorize-image-intensities:
                  lowerQuantile: 0.005
                  upperQuantile: 0.995

    # 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: 1mm

    # 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: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-01_desc-brain_T1w.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: /code/CPAC/resources/templates/mni_icbm152_t1_tal_nlin_asym_09c.nii

    # 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: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-01_desc-brain_mask.nii.gz

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

  functional_registration:
    coregistration:

      # functional (BOLD/EPI) registration to anatomical (structural/T1)
      run: On
      func_input_prep:

        # 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: [fmriprep_reference]

      boundary_based_registration:

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

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

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

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

    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_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: single_step_resampling_from_stc

      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: 3.438mmx3.438mmx3.4mm

        # 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: 3.438mmx3.438mmx3.4mm

      target_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: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-02_T1w_reference.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: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-02_T1w_reference.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: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-01_desc-brain_mask.nii.gz

          # a standard template for resampling if using float resolution
          T1w_template_for_resample: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-01_desc-brain_T1w.nii.gz

        EPI_template:

          # EPI template for direct functional-to-template registration
          # (bypassing coregistration and the anatomical-to-template transforms)
          EPI_template_funcreg:

          # a standard template for resampling if using float resolution
          EPI_template_for_resample:

    EPI_registration:
      ANTs:

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

functional_preproc:
  run: On
  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]

  motion_estimates_and_correction:
    run: On
    motion_estimates:

      # calculate motion statistics BEFORE slice-timing correction
      calculate_motion_first: 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: [mcflirt]

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

  distortion_correction:

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

  func_masking:
    run: On
    FSL_AFNI:
      bold_ref: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-02_desc-fMRIPrep_boldref.nii.gz
      brain_mask: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-02_desc-brain_mask.nii.gz
      brain_probseg: /code/CPAC/resources/templates/tpl-MNI152NLin2009cAsym_res-01_label-brain_probseg.nii.gz

    # 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: [FSL_AFNI]

  generate_func_mean:

    # Generate mean functional image
    run: On

  coreg_prep:

    # Generate sbref
    run: On

nuisance_corrections:
  2-nuisance_regression:

    # Select which nuisance signal corrections to apply
    Regressors:
      - Name: Regressor_1
        Bandpass:
          bottom_frequency: 0.01
          top_frequency: 0.1
        CerebrospinalFluid:
          erode_mask: Off
          extraction_resolution: 2
          summary: Mean
        GlobalSignal:
          summary: Mean
        Motion:
          include_delayed: On
          include_delayed_squared: On
          include_squared: On
        PolyOrt:
          degree: 2
        WhiteMatter:
          erode_mask: Off
          extraction_resolution: 2
          summary: Mean
        aCompCor:
          extraction_resolution: 2
          summary:
            components: 5
            filter: cosine
            method: PC
          tissues:
          - WhiteMatter
          - CerebrospinalFluid
        tCompCor:
          degree: 2
          erode_mask_mm: On
          summary:
            components: 5
            filter: cosine
            method: PC
          threshold: 5PCT

    # Process and refine masks used to produce regressors and time series for
    # regression.
    regressor_masks:
      erode_anatomical_brain_mask:

        # Erode brain mask in millimeters, default for brain mask is 30 mm
        # Brain erosion default is using millimeters.
        brain_mask_erosion_mm: 30

        # Erode binarized anatomical brain mask. If choosing True, please also set regressor_masks['erode_csf']['run']: True; anatomical_preproc['brain_extraction']['using']: niworkflows-ants.
        run: On

      erode_csf:

        # Erode cerebrospinal fluid mask in millimeters, default for cerebrospinal fluid is 30mm
        # Cerebrospinal fluid erosion default is using millimeters.
        csf_mask_erosion_mm: 30

        # Erode binarized csf tissue mask.
        run: On

      erode_wm:

        # Target volume ratio, if using erosion.
        # Default proportion is 0.6 for white matter mask.
        # If using erosion, using both proportion and millimeters is not recommended.
        # White matter erosion default is using proportion erosion method when use erosion for white matter.
        wm_erosion_prop: 0.6

        # Erode WM binarized tissue mask.
        run: On

      erode_gm:

        # Target volume ratio, if using erosion.
        # If using erosion, using both proportion and millimeters is not recommended.
        gm_erosion_prop: 0.6

    # this is not a fork point
    # Run nuisance regression in native or template space
    #   - If set to template, will use the brain mask configured in
    #     ``functional_preproc: func_masking: FSL_AFNI: brain_mask``
    #   - If ``registration_workflows: functional_registration: func_registration_to_template: apply_trasnform: using: single_step_resampling_from_stc``, this must be set to template
    space: template

    # Standard Lateral Ventricles Binary Mask
    # used in CSF mask refinement for CSF signal-related regressions
    lateral_ventricles_mask:

timeseries_extraction:
  connectivity_matrix:

    # Create a connectivity matrix from timeseries data
    # Options:
    #  ['AFNI', 'Nilearn', 'ndmg']
    using: [Nilearn, ndmg]

    # Options:
    #  ['Pearson', 'Partial']
    # Note: These options are not configurable for ndmg, which will ignore these options
    measure: [Pearson, Partial]

amplitude_low_frequency_fluctuation:

  # space: Template or Native
  target_space: [Native]

regional_homogeneity:

  # space: Template or Native
  target_space: [Native]

voxel_mirrored_homotopic_connectivity:
  symmetric_registration:

    # 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 a non-standard symmetric template.
    T1w_brain_template_symmetric:

    # A reference symmetric brain template for resampling
    T1w_brain_template_symmetric_for_resample:

    # 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 a non-standard symmetric template.
    T1w_template_symmetric:

    # A reference symmetric skull template for resampling
    T1w_template_symmetric_for_resample:

    # 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 a non-standard symmetric template.
    dilated_symmetric_brain_mask:

    # A reference symmetric brain mask template for resampling
    dilated_symmetric_brain_mask_for_resample:

network_centrality:

  # Maximum amount of RAM (in GB) to be used when calculating Degree Centrality.
  # Calculating Eigenvector Centrality will require additional memory based on the size of the mask or number of ROI nodes.
  memory_allocation: 3.0

  # Full path to a NIFTI file describing the mask. Centrality will be calculated for all voxels within the mask.
  template_specification_file:
  eigenvector_centrality:

    # Enable/Disable eigenvector centrality by selecting the connectivity weights
    #   weight_options: ['Binarized', 'Weighted']
    # disable this type of centrality with:
    #   weight_options: []
    weight_options: [Binarized, Weighted]

  local_functional_connectivity_density:

    # Select the type of threshold used when creating the lFCD adjacency matrix.
    # options:
    #   'Significance threshold', 'Correlation threshold'
    correlation_threshold_option: Significance threshold

    # Based on the Threshold Type selected above, enter a Threshold Value.
    # P-value for Significance Threshold
    # Sparsity value for Sparsity Threshold
    # Pearson's r value for Correlation Threshold
    correlation_threshold: 0.001

# OUTPUTS AND DERIVATIVES
# -----------------------
post_processing:
  spatial_smoothing:
    run: On

  z-scoring:
    run: On

# PACKAGE INTEGRATIONS
# --------------------
PyPEER:

  # Template-space eye mask
  eye_mask_path: