fw-gear-rtp2-preproc 0.2.2

RTP2 Pre-processing Diffusion MRI

RTP2-preproc (Preprocessing of dMRI data, part of RTP2 suite)

Overview

Usage

FAQ

Summary

Preprocesses the diffusion weighted data and coregisters with the anatomy files coming from Freesurferator and prepares data for RTP2-Pipeline gear

Cite

Lerma-Usabiaga, G., Liu, M., Paz-Alonso, P. M. & Wandell, B. A. Reproducible Tract Profiles 2 (RTP2) suite, from diffusion MRI acquisition to clinical practice and research. Sci. Rep. 13, 1\u201313 (2023) License: Other

Classification

Category: analysis

Gear Level:

• Project
• Subject
• Session
• Acquisition
• Analysis

---

[[TOC]]

---

Inputs

• DIFF

  • Name: DIFF
  • Type: file
  • Optional: false
  • Classification: **
  • Description: Diffusion NIfTI image
  • Notes: **

• BVAL

  • Name: BVAL
  • Type: file
  • Optional: false
  • Classification: file
  • Description: BVAL file
  • Notes: **

• BVEC

  • Name: BVEC
  • Type: file
  • Optional: false
  • Classification: file
  • Description: BVEC file
  • Notes: **

• ANAT

  • Name: ANAT
  • Type: file
  • Optional: false
  • Classification: **
  • Description: Freesurferator anatomical T1w NIfTI image
  • Notes: **

• FSMASK

  • Name: FSMASK
  • Type: zip
  • Optional: false
  • Classification: file
  • Description: Freesurferator brain mask
  • Notes: **

• RDIF

  • Name: RDIF
  • Type: file
  • Optional: true
  • Classification: **
  • Description: Optional reverse phase encoded (rpe) diffusion NIfTI image
  • Notes: **

• RBVL

  • Name: RBVL
  • Type: zip
  • Optional: true
  • Classification: file
  • Description: Optional reverse phase encoded (rpe) BVAL file
  • Notes: **

• RBVC

  • Name: RBVC
  • Type: file
  • Optional: true
  • Classification: **
  • Description: Optional reverse phase encoded (rpe) BVEC file
  • Notes: **

• QMAP

  • Name: QMAP
  • Type: file
  • Optional: true
  • Classification: **
  • Description: Quantitative map to be registered to the anatomical image. This map can be used to obtain tract and ROI metrics in RTP2-pipeline. Even though this option was created for qMRI maps, it really can be used with any scalar map with a value per voxel.
  • Notes: **

Config

• denoise

  • Name: denoise
  • Type: boolean
  • Description: Denoise data using PCA [default=false]
  • Default: false

• degibbs

  • Name: degibbs
  • Type: boolean
  • Description: Perform Gibbs ringing correction [default=false]
  • Default: false

• eddy

  • Name: eddy
  • Type: boolean
  • Description: Perform eddy current correction. If inverted phase encoding direction files are found, eddy will be done as part of topup [default=true]
  • Default: true

• pe_dir

  • Name: pe_dir
  • Type: string
  • Description: Phase Encoding Direction, optional field only necessary if eddy = true. This field will be automatically obtained from the json sidecar of the file. In old datasets, if the json file is not found, it will try to read it from here. By default the field is empty. The only acceptable values are AP, PA, LR, RL, IS, SI. If the values are not in the json sidecar file or any of these six values are not set in this field, the container will stop. [default=""]
  • Default: ""

• bias

  • Name: bias
  • Type: boolean
  • Description: Compute bias correction with ANTs on dwi data [default=false]
  • Default: false

• ricn

  • Name: ricn
  • Type: boolean
  • Description: Perform Rician background noise removal [default=false]
  • Default: false

• norm

  • Name: norm
  • Type: boolean
  • Description: Perform intensity normalization of dwi data [default=false]
  • Default: false

• nval

  • Name: nval
  • Type: number
  • Description: Normalize the intensity of the FA white matter mask to this number [default=1000]
  • Default: 1000

• anatalign

  • Name: anatalign
  • Type: boolean
  • Description: Align dwi data with anatomy [default=true]
  • Default: true

• doreslice

  • Name: doreslice
  • Type: boolean
  • Description: Do reslicing [default=false]
  • Default: false

• reslice

  • Name: reslice
  • Type: number
  • Description: Optional. By default reslicing is not done. If you want it done, set doreslice=true and set a number (e.g., 1) here to reslice the dwi data to this isotropic voxel size (in mm) [default=1]
  • Default: 1

• save_extra_output

  • Name: save_extra_output
  • Type: boolean
  • Description: Save all the intermediate files (both .mif and .nii.gz), for QC and debugging. The results from eddyqc are always saved on the output. [default=false]
  • Default: false

• bias_method

  • Name: bias_method
  • Type: string
  • Description: ants or fsl option for dwibiascorrect: performs B1 field inhomogeneity correction for a DWI volume series [default=ants]
  • Default: ants

• antsb

  • Name: antsb
  • Type: string
  • Description: b params for ANTs (when called from dwibiascorrect ants, it goes to N4BiasFieldCorrection option -b). It is a comma-separated pair of values enclosed by square brackets. The first parameter corresponds to initial mesh resolution in mm, the second one corresponds to spline order. . [initial mesh resolution in mm, spline order] This value is optimised for human adult data and needs to be adjusted for rodent data. --bspline-fitting [splineDistance,<splineOrder=3>] [initialMeshResolution,<splineOrder=3>] These options describe the b-spline fitting parameters. The initial b-spline mesh at the coarsest resolution is specified either as the number of elements in each dimension, e.g. 2x2x3 for 3-D images, or it can be specified as a single scalar parameter which describes the isotropic sizing of the mesh elements. The latter option is typically preferred. For each subsequent level, the spline distance decreases in half, or equivalently, the number of mesh elements doubles Cubic splines (order = 3) are typically used. [default=[150,3]]
  • Default: [150,3]

• antsc

  • Name: antsc
  • Type: string
  • Description: c params for ANTs (when called from dwibiascorrect ants, it goes to N4BiasFieldCorrection option -c). It is a comma-separated pair of values enclosed by square brackets. The first parameter corresponds to numberOfIterations, the second one to convergenceThreshold. --convergence [<numberOfIterations=50x50x50x50>,<convergenceThreshold=0.0>] Convergence is determined by calculating the coefficient of variation between subsequent iterations. When this value is less than the specified threshold from the previous iteration or the maximum number of iterations is exceeded the program terminates. Multiple resolutions can be specified by using 'x' between the number of iterations at each resolution, e.g. 100x50x50. [default=[200x200,1e-6]]
  • Default: [200x200,1e-6]

• antss

  • Name: antss
  • Type: string
  • Description: *param s for ANTs: when called from dwibiascorrect ants, N4BiasFieldCorrection option -s [shrink-factor] applied to spatial dimensions; it lessens computation time by resampling the input image. The shrink factor, specified as a single integer, describes this resampling. Shrink factors <= 4 are commonly used [default=2]

• • Default: 2

• eddy_data_is_shelled

  • Name: eddy_data_is_shelled
  • Type: boolean
  • Description: At the moment eddy works for single- or multi-shell diffusion data, i.e. it doesn't work for DSI data. In order to ensure that the data is shelled, eddy checks it and only proceeds if that's the case. The checking is performed through a set of heuristics such as i) how many shells are there? ii) what are the absolute numbers of directions for each shell? iii) what are the relative numbers of directions for each shell? etc. However, some popular schemes (e.g., if you acquire a mini shell with low b-value and few directions) get caught in this test, even though eddy works perfectly well on the data. eddy_data_is_shelled, if set, will bypass any checking and eddy will proceed as if data was shelled. Please be aware that if you have to use this flag you may be in untested territory and that it is a good idea to check your data extra carefully after having run eddy on it [default=true]
  • Default: true

• eddy_slm

  • Name: eddy_slm
  • Type: string
  • Description: Second level model that specifies the mathematical form for how the diffusion gradients cause eddy currents. For high quality data with 60 directions, or more, sampled on the whole sphere we have not found any advantage of performing second level modeling. Hence, our recommendation for such data is to use none. If the data has few directions and/or has not been sampled on the whole sphere it is better to use linear [default=linear]
  • Default: linear

• eddy_niter

  • Name: eddy_niter
  • Description: eddy does not check for convergence. Instead, it runs a fixed number of iterations given by this parameter. If, on visual inspection, one finds residual movement or EC-induced distortions it is possible that eddy has not fully converged. In that case you can increase the number of iterations [default=5]
  • Type: number
  • Default: 5

• eddy_repol

  • Name: eddy_repol
  • Type: boolean
  • Description: When set this flag instructs eddy to remove any slices deemed as outliers and replace them with predictions made by the Gaussian Process. Exactly what constitutes an outlier is affected by the parameters --ol_nstd, --ol_nvox, --ol_type, --ol_pos and --ol_sqr. If the defaults are used for all those parameters an outlier is defined as a slice whose average intensity is at least four standard deviations lower than the expected intensity, where the expectation is given by the Gaussian Process prediction. The default is to not do outlier replacement since we don't want to risk people using it unawares. However, our experience and tests indicate that it is always a good idea to use --repol.
  • Default: true

• topup_lambda

  • Name: topup_lambda
  • Type: string
  • Description: parameter lambda in topup. It sets the relative weight between sum-of-squared differences and regularization for each level [default=0.005,0.001, 0.0001,0.000015,0.000005,0.0000005,0.00000005,0.0000000005,0.00000000001]
  • Default: 0.005,0.001,0.0001,0.000015,0.000005,0.0000005,0.00000005,0.0000000005,0.00000000001

Outputs

The Files section describes the default files output by the gear.

If the save_extra_output config option is set to True, all intermediate processed files in .mif format, as well as all the files from running eddy (files starting with eddy_) will be included in the output. Please refer to the user manuals for eddy and MRtrix to learn about the different files. ANTs registration files are always saved by default on purpose because they can use for other gears.

Files

• ants0GenericAffine.mat

  • Name: ants0GenericAffine.mat
  • Type: Matlab mat file
  • Optional: false
  • Classification: Matlab mat file
  • Description: ANTs registration file, can be used in downstream gears

• ants0GenericAffine.txt

  • Name: ants0GenericAffine.txt
  • Type: text
  • Optional: false
  • Classification: text
  • Description: ANTs registration file, can be used in downstream gears

• antsInverseWarped.nii.gz

  • Name: antsInverseWarped.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: ANTs registration file, can be used in downstream gears

• antsWarped.nii.gz

  • Name: antsWarped.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: ANTs registration file, can be used in downstream gears

• b0_anatalign.nii.gz

  • Name: b0_anatalign.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: output space b0s

• b0_anatalign_brain.nii.gz

  • Name: b0_anatalign_brain.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: output space b0s

• b0_anatalign_brain_mask.nii.gz

  • Name: b0_anatalign_brain_mask.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: output space b0s, brainmasked dwi b0 data

• b0_dwi.nii.gz

  • Name: b0_dwi.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: output space b0s

• b0_dwi_brain.nii.gz

  • Name: b0_dwi_brain.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: b0 dwi algidned with anatomy data

• b0_dwi_brain_mask.nii.gz

  • Name: b0_dwi_brain_mask.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: bo dwi brainmasked

• dwi.bvals

  • Name: dwi.bvals
  • Type: bval
  • Optional: false
  • Classification: bval
  • Description: bval value after all corrections, ready to be used in rtp2-pipeline

• dwi.bvecs

  • Name: dwi.bvecs
  • Type: bvec
  • Optional: false
  • Classification: bvec
  • Description: bvec value after all corrections, ready to be used in rtp2-pipeline

• dwi.nii.gz

  • Name: dwi.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: preprocessed dwi data ready to be used in rtp2-pipeline

• dwi2anatalign_mrtrix.txt

  • Name: dwi2anatalign_mrtrix.txt
  • Type: text
  • Optional: false
  • Classification: text
  • Description: Result of anatomy align that can be plotted

• dwi_denoise_degibbs_eddy_bias_ricn_anatalign_1p5mm.json

  • Name: dwi_denoise_degibbs_eddy_bias_ricn_anatalign_1p5mm.json
  • Type: json
  • Optional: false
  • Classification: json
  • Description: **

• t1.nii.gz

  • Name: t1.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: freesurfer's t1 file, ready to be used in rtp2-pipeline. It converts the file to RAS. If it was already, then no change to the input file.

• t1_brain.nii.gz

  • Name: t1_brain.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: freesurfers brain file, ready to be used in rtp2-pipeline. It converts the file to RAS. If it was already, then no change to the input file.

• eddy_parameters

  • Name: eddy_parameters
  • Type: text
  • Optional: true
  • Classification: text
  • Description: This is a text file with one row for each volume in --imain and one column for each parameter. The first six columns correspond to subject movement starting with three translations followed by three rotations. The remaining columns pertain to the EC-induced fields and the number and interpretation of them will depend of which EC model was specified.

• eddy_movement_rms

  • Name: eddy_movement_rms
  • Type: text
  • Optional: true
  • Classification: text
  • Description: A summary of the "total movement" in each volume is created by calculating the displacement of each voxel and then averaging the squares of those displacements across all intracerebral voxels (as determined by --mask and finally taking the square root of that. The file has two columns where the first contains the RMS movement relative the first volume and the second column the RMS relative the previous volume.

• eddy_restricted_movement_rms

  • Name: eddy_restricted_movement_rms
  • Type: text
  • Optional: true
  • Classification: text
  • Description: There is an inherent ambiguity between any EC component that has a non-zero mean across the FOV and subject movement (translation) in the PE direction. They will affect the data in identical (or close to identical if a susceptibility field is specified) ways. That means that both these parameters are estimated by eddy with large uncertainty. This doesn't matter for the correction of the images, it makes no difference if we estimate a large constant EC components and small movement or if we estimate a small EC component and large movement. The corrected images will be (close to) identical. But it matters if one wants to know how much the subject moved. We therefore supplies this file that estimates the movement RMS as above, but which disregards translation in the PE direction.

• eddy_post_eddy_shell_alignment_parameters

  • Name: eddy_post_eddy_shell_alignment_parameters
  • Type: text
  • Optional: true
  • Classification: text
  • Description: This is a text file with the rigid body movement parameters between the different shells as estimated by a post-hoc mutual information based registration (see --dont_peas for details). These parameters will be estimated even if --dont_peas has been set, but in that case they have not been applied to the corrected images in my_eddy_output.nii.gz.

• eddy_post_eddy_shell_PE_translation_parameters

  • Name: eddy_post_eddy_shell_PE_translation_parameters
  • Type: text
  • Optional: true
  • Classification: text
  • Description: This is a text file with the translation along the PE-direction between the different shells as estimated by a post-hoc mutual information based registration (see --dont_sep_offs_move for details). These parameters will be estimated even if --dont_sep_offs_move has been set, but in that case they have not been applied to the corrected images in my_eddy_output.nii.gz.

• eddy_outlier_report

  • Name: eddy_outlier_report
  • Type: text
  • Optional: true
  • Classification: text
  • Description: This is a text-file with a plain language report on what outlier slices eddy has found. This file is always created, as are the other my_eddy_output.eddy_outlier_ files described below, even if the --repol flag has not been set. Internally eddy will always detect and replace outliers to make sure they don't affect the estimation of EC/movement, and if --repol has not been set it will re-introduce the original slices before writing my_eddy_output.nii.gz.*

• eddy_outlier_map

  • Name: eddy_outlier_map
  • Type: text
  • Optional: true
  • Classification: text
  • Description: Numeric matrix in ASCII format. Consist of an initial line of text, after which there is one row for each volume and one column for each slice. Each row corresponding to a b=0 volume is all zeros since eddy don't consider outliers in these. All numbers are either 0, meaning that scan-slice is not an outliers, or 1 meaning that is is.

• eddy_outlier_n_stdev_map

  • Name: eddy_outlier_n_stdev_map
  • Type: text
  • Optional: true
  • Classification: text
  • Description: Numeric matrix in ASCII format. Consist of an initial line of text, after which there is one row for each volume and one column for each slice. Each row corresponding to a b=0 volume is all zeros since eddy don't consider outliers in these. The numbers denote how many standard deviations off the mean difference between observation and prediction is.

• eddy_outlier_n_sqr_stdev_map

  • Name: eddy_outlier_n_sqr_stdev_map
  • Type: text
  • Optional: true
  • Classification: text
  • Description: Numeric matrix in ASCII format. Consist of an initial line of text, after which there is one row for each volume and one column for each slice. Each row corresponding to a b=0 volume is all zeros since eddy don't consider outliers in these. The numbers denote how many standard deviations off the square root of the mean squared difference between observation and prediction is.

• eddy_outlier_free_data.nii.gz

  • Name: eddy_outlier_free_data
  • Type: nifti
  • Optional: true
  • Classification: nifti
  • Description: * Only written if the --repol flag was set. This is the original data given by --imain not corrected for susceptibility or EC-induced distortions or subject movement, but with outlier slices replaced by the Gaussian Process predictions. This file is generated for anyone who might want to use eddy for outlier correction but who want to use some other method to correct for distortions and movement. Though why anyone would want to do that is not clear to us.

Metadata

This gear does not create metadata.

Pre-requisites

This gear requires Freesurferator to be run and diffusion weighted data

Prerequisite Gear Runs

1. __freesurferator
   • Level: Analysis

Prerequisite Files

There are no other required files.

Prerequisite Metadata

There is no other required metadata.

Usage

This gear needs Freesurfer's T1 and brainmask files to run, on top of the DWI data. Then, you can use the defaults so that the data is prepared correctly for RTP2-pipeline. anatalign needs to be set to True to work in RTP2-pipeline, we left the option open if some user wants to use this gear independently and have the DWI in diffusion space.

Support

Please email [e-mail] for help solving bugs of functional gaps.

Roadmap

• Include other types of files (qMRI) to coregister with ANTs, so that then can be used in RTP2-pipeline to obtain metrics

Description

This gear gear implemented MRtrix's preprocessing routine, using FSL and ANT tools when required. It does the anatomy correction as well as the coregistration between the anatomy and the DWI data.

File Specifications

This section contains specifications on any input files that the gear may need

{Input-File}

A description of the input file

Workflow

Description of workflow

1. Upload files to container
2. Select files as input to gear
3. Gear places output in Analysis, that can be then be used in RTP2-pipeline gear

Freesurterator is a prerequisite. From Freesurferator the T1.nii.gz as ANAT and the brainmask.nii.gz as FSMASK has to be selected. On top of that, add the DWI data (remember the add the RPE if it was acquired).

Use Cases

Use Case 1

*Conditions*:

• {A list of conditions that result in this use case}
• Possibly a list of check boxes indicating things that are absent
• and things that are present

There are no use cases, this gear will preprocess DWI data using different options based on the configuration and will output data ready to go to RTP2-pipeline.

Logging

It throws the log from the registration system.

FAQ

FAQ.md

Contributing

If you want to contribute to this gear please contact [e-mail].

[For more information about how to get started contributing to that gear, checkout CONTRIBUTING.md.]