bad coregistrations

[shnizzedy]

Describe the bug

XCP-CPAC_compare.pdf

subjects with bad coregistrations

HRC

20415

NKI

A00033752, A00052461, A00053171, A00057372, A00060846, A00062361, A00066237, A00066580, A00076594, A00077412, A00079724

Preconfig

• fmriprep-options
• fx-options
• rbc-options

Expected behavior

• bad coregistrations retry or fail

Acceptance criteria

• bad coregistrations retry or fail

C-PAC version

v1.8.4, v1.8.5-dev

Container platform

Singularity

Docker and/or Singularity version(s)

Singularity 3.8.5-2.el7

Additional context

🔗 workng doc

[shnizzedy]

run	seed	native space	template space
sub-A00062361_ses-BAS1	77742777

[shnizzedy]

Three subjects with this registration configuration

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: 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: /usr/share/fsl/5.0/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: /usr/share/fsl/5.0/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: /usr/share/fsl/5.0/data/standard/MNI152_T1_${resolution_for_anat}_brain_mask.nii.gz

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

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

        # 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

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

        # Template to be used during registration.
        # It is for monkey pipeline specifically. 
        FNIRT_T1w_brain_template: 

        # Template to be used during registration.
        # It is for monkey pipeline specifically. 
        FNIRT_T1w_template: 

        # 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: /usr/share/fsl/5.0/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: 

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

    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: 

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

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

        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: /usr/share/fsl/5.0/etc/flirtsch/bbr.sch

        # 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

    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: 

      ANTs: 

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

        # 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: /usr/share/fsl/5.0/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: 2mm

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

      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: /usr/share/fsl/5.0/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: /usr/share/fsl/5.0/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: /usr/share/fsl/5.0/data/standard/MNI152_T1_${func_resolution}_brain_mask.nii.gz

          # a standard template for resampling if using float resolution
          T1w_template_for_resample: /usr/share/fsl/5.0/data/standard/MNI152_T1_${func_resolution}_brain.nii.gz

        EPI_template: 

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

          # EPI template mask.
          EPI_template_mask_funcreg: 

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

      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: /usr/share/fsl/5.0/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: single_step_resampling_from_stc