# RTP2-preproc (Preprocessing of dMRI data, part of RTP2 suite)
## Overview
*[Usage](#usage)*
*[FAQ](#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
- [x] 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](#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 garikoitz@gmail.com 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
1. Select files as input to gear
1. 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
- [x] 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](FAQ.md)
## Contributing
If you want to contribute to this gear please contact garikoitz@gmail.com.
[For more information about how to get started contributing to that gear,
checkout [CONTRIBUTING.md](CONTRIBUTING.md).]
<!-- markdownlint-disable-file -->
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/flywheel-io/scientific-solutions/gears/rtp2-preproc",
"name": "fw-gear-rtp2-preproc",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "Flywheel, Gears",
"author": "Flywheel",
"author_email": "support@flywheel.io",
"download_url": null,
"platform": null,
"description": "# RTP2-preproc (Preprocessing of dMRI data, part of RTP2 suite)\n\n## Overview\n\n*[Usage](#usage)*\n\n*[FAQ](#faq)*\n\n### Summary\n\n\n\n\n*Preprocesses the diffusion weighted data and coregisters with the anatomy files coming from Freesurferator and prepares data for RTP2-Pipeline gear*\n\n### Cite\n\n*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)*\n*License:* *Other*\n\n### Classification\n\n*Category:* *analysis*\n\n*Gear Level:*\n\n- [ ] Project\n- [ ] Subject\n- [ ] Session\n- [ ] Acquisition\n- [x] Analysis\n\n----\n\n[[_TOC_]]\n\n----\n\n### Inputs\n\n- *DIFF*\n - __Name__: *DIFF*\n - __Type__: *file*\n - __Optional__: *false*\n - __Classification__: **\n - __Description__: *Diffusion NIfTI image*\n - __Notes__: **\n\n- *BVAL*\n - __Name__: *BVAL*\n - __Type__: *file*\n - __Optional__: *false*\n - __Classification__: *file*\n - __Description__: *BVAL file*\n - __Notes__: **\n \n- *BVEC*\n - __Name__: *BVEC*\n - __Type__: *file*\n - __Optional__: *false*\n - __Classification__: *file*\n - __Description__: *BVEC file*\n - __Notes__: ** \n\n- *ANAT*\n - __Name__: *ANAT*\n - __Type__: *file*\n - __Optional__: *false*\n - __Classification__: **\n - __Description__: *Freesurferator anatomical T1w NIfTI image*\n - __Notes__: **\n\n- *FSMASK*\n - __Name__: *FSMASK*\n - __Type__: *zip*\n - __Optional__: *false*\n - __Classification__: *file*\n - __Description__: *Freesurferator brain mask*\n - __Notes__: **\n\n- *RDIF*\n - __Name__: *RDIF*\n - __Type__: *file*\n - __Optional__: *true*\n - __Classification__: **\n - __Description__: *Optional reverse phase encoded (rpe) diffusion NIfTI image*\n - __Notes__: **\n\n- *RBVL*\n - __Name__: *RBVL*\n - __Type__: *zip*\n - __Optional__: *true*\n - __Classification__: *file*\n - __Description__: *Optional reverse phase encoded (rpe) BVAL file*\n - __Notes__: **\n\n- *RBVC*\n - __Name__: *RBVC*\n - __Type__: *file*\n - __Optional__: *true*\n - __Classification__: **\n - __Description__: *Optional reverse phase encoded (rpe) BVEC file*\n - __Notes__: **\n \n- *QMAP*\n - __Name__: *QMAP*\n - __Type__: *file*\n - __Optional__: *true*\n - __Classification__: **\n - __Description__: *Quantitative map to be registered to the anatomical image.\n This map can be used to obtain tract and ROI metrics in RTP2-pipeline. \n Even though this option was created for qMRI maps, it really can be used \n with any scalar map with a value per voxel.*\n - __Notes__: **\n\n### Config\n\n- *denoise*\n - __Name__: *denoise*\n - __Type__: *boolean*\n - __Description__: *Denoise data using PCA [default=false]*\n - __Default__: *false*\n \n- *degibbs*\n - __Name__: *degibbs*\n - __Type__: *boolean*\n - __Description__: *Perform Gibbs ringing correction [default=false]*\n - __Default__: *false* \n \n- *eddy*\n - __Name__: *eddy*\n - __Type__: *boolean*\n - __Description__: *Perform eddy current correction. If inverted phase encoding\n direction files are found, eddy will be done as part of topup [default=true]*\n - __Default__: *true* \n\n- *pe_dir*\n - __Name__: *pe_dir*\n - __Type__: *string*\n - __Description__: *Phase Encoding Direction, optional field only necessary \n 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 \n 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 \n 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=\"\"]*\n - __Default__: *\"\"* \n\n- *bias*\n - __Name__: *bias*\n - __Type__: *boolean*\n - __Description__: *Compute bias correction with ANTs on dwi data [default=false]*\n - __Default__: *false* \n\n- *ricn*\n - __Name__: *ricn*\n - __Type__: *boolean*\n - __Description__: *Perform Rician background noise removal [default=false]*\n - __Default__: *false* \n\n\n- *norm*\n - __Name__: *norm*\n - __Type__: *boolean*\n - __Description__: *Perform intensity normalization of dwi data [default=false]*\n - __Default__: *false* \n\n\n- *nval*\n - __Name__: *nval*\n - __Type__: *number*\n - __Description__: *Normalize the intensity of the FA white matter mask to this number [default=1000]*\n - __Default__: *1000* \n\n\n- *anatalign*\n - __Name__: *anatalign*\n - __Type__: *boolean*\n - __Description__: *Align dwi data with anatomy [default=true]*\n - __Default__: *true* \n\n\n- *doreslice*\n - __Name__: *doreslice*\n - __Type__: *boolean*\n - __Description__: *Do reslicing [default=false]*\n - __Default__: *false* \n\n- *reslice*\n - __Name__: *reslice*\n - __Type__: *number*\n - __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]*\n - __Default__: *1* \n\n- *save_extra_output*\n - __Name__: *save_extra_output*\n - __Type__: *boolean*\n - __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]*\n - __Default__: *false* \n\n\n- *bias_method*\n - __Name__: *bias_method*\n - __Type__: *string*\n - __Description__: *ants or fsl option for dwibiascorrect: performs B1 field inhomogeneity correction for a DWI volume series [default=ants]*\n - __Default__: *ants* \n \n\n- *antsb*\n - __Name__: *antsb*\n - __Type__: *string*\n - __Description__: *b params for ANTs (when called from dwibiascorrect ants, \n it goes to N4BiasFieldCorrection option -b). It is a comma-separated pair \n of values enclosed by square brackets. The first parameter corresponds \n to initial mesh resolution in mm, the second one\n corresponds to spline order. . [initial mesh resolution in mm, spline order]\n This value is optimised for human adult data and needs to be adjusted for \n rodent data. --bspline-fitting [splineDistance,<splineOrder=3>] \n [initialMeshResolution,<splineOrder=3>] These options describe the b-spline \n fitting parameters. The initial b-spline mesh at the coarsest resolution is \n specified either as the number of elements in each dimension, e.g. 2x2x3 for \n 3-D images, or it can be specified as a single scalar parameter which \n describes the isotropic sizing of the mesh elements. The latter option is \n typically preferred. For each subsequent level, the spline distance decreases \n in half, or equivalently, the number of mesh elements doubles Cubic splines \n (order = 3) are typically used. [default=[150,3]]*\n - __Default__: *[150,3]* \n \n\n- *antsc*\n - __Name__: *antsc*\n - __Type__: *string*\n - __Description__: *c params for ANTs (when called from dwibiascorrect ants, it \n goes to N4BiasFieldCorrection option -c). It is a comma-separated pair of \n values enclosed by square brackets. The first parameter corresponds to \n numberOfIterations, the second one to convergenceThreshold. --convergence \n [<numberOfIterations=50x50x50x50>,<convergenceThreshold=0.0>] Convergence \n is determined by calculating the coefficient of variation between subsequent \n iterations. When this value is less than the specified threshold from the \n previous iteration or the maximum number of iterations is exceeded the program \n terminates. Multiple resolutions can be specified by using 'x' between the number \n of iterations at each resolution, e.g. 100x50x50. [default=[200x200,1e-6]]*\n - __Default__: *[200x200,1e-6]* \n\n\n- *antss*\n - __Name__: *antss*\n - __Type__: *string*\n - __Description__: *param s for ANTs: when called from dwibiascorrect ants,\n N4BiasFieldCorrection option -s [shrink-factor] applied to spatial dimensions; it\n lessens computation time by resampling the input image. The shrink factor, specified\n as a single integer, describes this resampling. Shrink factors <= 4 are commonly used\n [default=2]\n*\n - __Default__: *2* \n\n\n- *eddy_data_is_shelled*\n - __Name__: *eddy_data_is_shelled*\n - __Type__: *boolean*\n - __Description__: *At the moment eddy works for single- or multi-shell diffusion\n data, i.e. it doesn't work for DSI data. In order to ensure that the data is shelled,\n eddy checks it and only proceeds if that's the case. The checking is performed through\n a set of heuristics such as i) how many shells are there? ii) what are the absolute\n numbers of directions for each shell? iii) what are the relative numbers of directions\n for each shell? etc. However, some popular schemes (e.g., if you acquire a mini shell\n with low b-value and few directions) get caught in this test, even though eddy works\n perfectly well on the data. eddy_data_is_shelled, if set, will bypass any checking and\n eddy will proceed as if data was shelled. Please be aware that if you have to use this\n flag you may be in untested territory and that it is a good idea to check your data\n extra carefully after having run eddy on it [default=true]*\n - __Default__: *true* \n\n- *eddy_slm*\n - __Name__: *eddy_slm*\n - __Type__: *string*\n - __Description__: *Second level model that specifies the mathematical form for how\n the diffusion gradients cause eddy currents. For high quality data with 60 directions,\n or more, sampled on the whole sphere we have not found any advantage of performing\n second level modeling. Hence, our recommendation for such data is to use none. If the\n data has few directions and/or has not been sampled on the whole sphere it is better to\n use linear [default=linear]*\n - __Default__: *linear* \n\n- *eddy_niter*\n - __Name__: *eddy_niter*\n - __Description__: *eddy does not check for convergence. Instead, it runs a fixed\n number of iterations given by this parameter. If, on visual inspection, one finds\n residual movement or EC-induced distortions it is possible that eddy has not fully\n converged. In that case you can increase the number of iterations [default=5]*\n - __Type__: *number*\n - __Default__: *5* \n\n\n- *eddy_repol*\n - __Name__: *eddy_repol*\n - __Type__: *boolean*\n - __Description__: *When set this flag instructs eddy to remove any slices \n deemed as outliers and replace them with predictions made by the Gaussian \n Process. Exactly what constitutes an outlier is affected by the parameters \n --ol_nstd, --ol_nvox, --ol_type, --ol_pos and --ol_sqr. If the defaults are \n used for all those parameters an outlier is defined as a slice whose average \n intensity is at least four standard deviations lower than the expected \n intensity, where the expectation is given by the Gaussian Process prediction. \n The default is to not do outlier replacement since we don't want to risk people \n using it unawares. However, our experience and tests indicate that it is \n always a good idea to use --repol.*\n - __Default__: *true* \n\n\n- *topup_lambda*\n - __Name__: *topup_lambda*\n - __Type__: *string*\n - __Description__: *parameter lambda in topup. It sets the relative weight between\n sum-of-squared differences and regularization for each level [default=0.005,0.001,\n 0.0001,0.000015,0.000005,0.0000005,0.00000005,0.0000000005,0.00000000001]*\n - __Default__: *0.005,0.001,0.0001,0.000015,0.000005,0.0000005,0.00000005,0.0000000005,0.00000000001* \n\n\n### Outputs\n\nThe [Files](#files) section describes the default files output by the gear.\n\n\nIf the `save_extra_output` config option is set to True, all intermediate \nprocessed files in `.mif` format, as well as all the files from running eddy \n(files starting with `eddy_`) will be included in the output. Please refer to \nthe 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 \nfor other gears.\n\n\n#### Files\n\n\n- *ants0GenericAffine.mat*\n - __Name__: *ants0GenericAffine.mat*\n - __Type__: *Matlab mat file*\n - __Optional__: *false*\n - __Classification__: *Matlab mat file*\n - __Description__: *ANTs registration file, can be used in downstream gears*\n \n- *ants0GenericAffine.txt*\n - __Name__: *ants0GenericAffine.txt*\n - __Type__: *text*\n - __Optional__: *false*\n - __Classification__: *text*\n - __Description__: *ANTs registration file, can be used in downstream gears*\n \n- *antsInverseWarped.nii.gz*\n - __Name__: *antsInverseWarped.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *ANTs registration file, can be used in downstream gears*\n\n- *antsWarped.nii.gz*\n - __Name__: *antsWarped.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *ANTs registration file, can be used in downstream gears*\n\n- *b0_anatalign.nii.gz*\n - __Name__: *b0_anatalign.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *output space b0s*\n\n- *b0_anatalign_brain.nii.gz*\n - __Name__: *b0_anatalign_brain.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *output space b0s*\n\n- *b0_anatalign_brain_mask.nii.gz*\n - __Name__: *b0_anatalign_brain_mask.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *output space b0s, brainmasked dwi b0 data*\n\n\n- *b0_dwi.nii.gz*\n - __Name__: *b0_dwi.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *output space b0s*\n\n\n- *b0_dwi_brain.nii.gz*\n - __Name__: *b0_dwi_brain.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *b0 dwi algidned with anatomy data*\n\n\n- *b0_dwi_brain_mask.nii.gz*\n - __Name__: *b0_dwi_brain_mask.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *bo dwi brainmasked*\n\n\n- *dwi.bvals*\n - __Name__: *dwi.bvals*\n - __Type__: *bval*\n - __Optional__: *false*\n - __Classification__: *bval*\n - __Description__: *bval value after all corrections, ready to be used in rtp2-pipeline*\n\n\n- *dwi.bvecs*\n - __Name__: *dwi.bvecs*\n - __Type__: *bvec*\n - __Optional__: *false*\n - __Classification__: *bvec*\n - __Description__: *bvec value after all corrections, ready to be used in rtp2-pipeline*\n\n\n- *dwi.nii.gz*\n - __Name__: *dwi.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *preprocessed dwi data ready to be used in rtp2-pipeline*\n \n- *dwi2anatalign_mrtrix.txt*\n - __Name__: *dwi2anatalign_mrtrix.txt*\n - __Type__: *text*\n - __Optional__: *false*\n - __Classification__: *text*\n - __Description__: *Result of anatomy align that can be plotted*\n\n\n- *dwi_denoise_degibbs_eddy_bias_ricn_anatalign_1p5mm.json*\n - __Name__: *dwi_denoise_degibbs_eddy_bias_ricn_anatalign_1p5mm.json*\n - __Type__: *json*\n - __Optional__: *false*\n - __Classification__: *json*\n - __Description__: **\n\n- *t1.nii.gz*\n - __Name__: *t1.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *freesurfer's t1 file, ready to be used in rtp2-pipeline. \n It converts the file to RAS. If it was already, then no change to the input file.*\n\n- *t1_brain.nii.gz*\n - __Name__: *t1_brain.nii.gz*\n - __Type__: *nifti*\n - __Optional__: *false*\n - __Classification__: *nifti*\n - __Description__: *freesurfers brain file, ready to be used in rtp2-pipeline.\n It converts the file to RAS. If it was already, then no change to the input file.*\n \n \n- *eddy_parameters*\n - __Name__: *eddy_parameters*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *This is a text file with one row for each volume in --imain and \n one column for each parameter. The first six columns correspond to subject \n movement starting with three translations followed by three rotations. The \n remaining columns pertain to the EC-induced fields and the number and \n interpretation of them will depend of which EC model was specified.*\n\n\n- *eddy_movement_rms*\n - __Name__: *eddy_movement_rms*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *A summary of the \"total movement\" in each volume is created by\n calculating the displacement of each voxel and then averaging the squares of those \n displacements across all intracerebral voxels (as determined by --mask and finally \n taking the square root of that. The file has two columns where the first contains \n the RMS movement relative the first volume and the second column the RMS relative \n the previous volume.*\n\n- *eddy_restricted_movement_rms*\n - __Name__: *eddy_restricted_movement_rms*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *There is an inherent ambiguity between any EC component that has a\n non-zero mean across the FOV and subject movement (translation) in the PE direction. \n They will affect the data in identical (or close to identical if a susceptibility \n field is specified) ways. That means that both these parameters are estimated by \n eddy with large uncertainty. This doesn't matter for the correction of the images, \n it makes no difference if we estimate a large constant EC components and small \n movement or if we estimate a small EC component and large movement. The corrected \n images will be (close to) identical. But it matters if one wants to know how much \n the subject moved. We therefore supplies this file that estimates the movement RMS \n as above, but which disregards translation in the PE direction.*\n\n- *eddy_post_eddy_shell_alignment_parameters*\n - __Name__: *eddy_post_eddy_shell_alignment_parameters*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *This is a text file with the rigid body movement parameters between\n the different shells as estimated by a post-hoc mutual information based \n registration (see --dont_peas for details). These parameters will be estimated even \n if --dont_peas has been set, but in that case they have not been applied to the \n corrected images in my_eddy_output.nii.gz.*\n\n- *eddy_post_eddy_shell_PE_translation_parameters*\n - __Name__: *eddy_post_eddy_shell_PE_translation_parameters*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *This is a text file with the translation along the PE-direction \n between the different shells as estimated by a post-hoc mutual information based \n registration (see --dont_sep_offs_move for details). These parameters will be \n estimated even if --dont_sep_offs_move has been set, but in that case they have not \n been applied to the corrected images in my_eddy_output.nii.gz.*\n\n- *eddy_outlier_report*\n - __Name__: *eddy_outlier_report*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *This is a text-file with a plain language report on what outlier \n slices eddy has found. This file is always created, as are the other \n my_eddy_output.eddy_outlier_* files described below, even if the --repol flag has \n not been set. Internally eddy will always detect and replace outliers to make sure \n they don't affect the estimation of EC/movement, and if --repol has not been set it \n will re-introduce the original slices before writing my_eddy_output.nii.gz.*\n\n- *eddy_outlier_map*\n - __Name__: *eddy_outlier_map*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *Numeric matrix in ASCII format. Consist of an initial line of text,\n after which there is one row for each volume and one column for each slice. Each row \n corresponding to a b=0 volume is all zeros since eddy don't consider outliers in \n these. All numbers are either 0, meaning that scan-slice is not an outliers, or 1 \n meaning that is is.*\n \n \n- *eddy_outlier_n_stdev_map*\n - __Name__: *eddy_outlier_n_stdev_map*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *Numeric matrix in ASCII format. Consist of an initial line of text,\n after which there is one row for each volume and one column for each slice. Each row \n corresponding to a b=0 volume is all zeros since eddy don't consider outliers in \n these. The numbers denote how many standard deviations off the mean difference \n between observation and prediction is.*\n \n \n- *eddy_outlier_n_sqr_stdev_map*\n - __Name__: *eddy_outlier_n_sqr_stdev_map*\n - __Type__: *text*\n - __Optional__: *true*\n - __Classification__: *text*\n - __Description__: *Numeric matrix in ASCII format. Consist of an initial line of text,\n after which there is one row for each volume and one column for each slice. Each row \n corresponding to a b=0 volume is all zeros since eddy don't consider outliers in \n these. The numbers denote how many standard deviations off the square root of the \n mean squared difference between observation and prediction is.*\n\n\n\n- *eddy_outlier_free_data.nii.gz*\n - __Name__: *eddy_outlier_free_data*\n - __Type__: *nifti*\n - __Optional__: *true*\n - __Classification__: *nifti*\n - __Description__: * Only written if the --repol flag was set. This is the original data\n given by --imain not corrected for susceptibility or EC-induced distortions or \n subject movement, but with outlier slices replaced by the Gaussian Process \n predictions. This file is generated for anyone who might want to use eddy for \n outlier correction but who want to use some other method to correct for distortions \n and movement. Though why anyone would want to do that is not clear to us. \n\n\n#### Metadata\n\nThis gear does not create metadata. \n \n### Pre-requisites\n\nThis gear requires Freesurferator to be run and diffusion weighted data\n\n#### Prerequisite Gear Runs\n\n \n1. __*freesurferator*\n - Level: *Analysis*\n \n#### Prerequisite Files\n\nThere are no other required files. \n \n#### Prerequisite Metadata\n\nThere is no other required metadata. \n \n## Usage\nThis gear needs Freesurfer's T1 and brainmask files to run, on top of the DWI data. \nThen, you can use the defaults so that the data is prepared correctly for RTP2-pipeline. \nanatalign needs to be set to True to work in RTP2-pipeline, we left the option open if \nsome user wants to use this gear independently and have the DWI in diffusion space. \n\n## Support\nPlease email garikoitz@gmail.com for help solving bugs of functional gaps. \n\n## Roadmap\n\n- Include other types of files (qMRI) to coregister with ANTs, so that then can be used in RTP2-pipeline to obtain metrics\n\n\n### Description\n\nThis gear gear implemented MRtrix's preprocessing routine, using FSL and ANT tools\nwhen required. It does the anatomy correction as well as the coregistration between \nthe anatomy and the DWI data.\n\n#### File Specifications\n\nThis section contains specifications on any input files that the gear may need\n\n##### *{Input-File}*\n\nA description of the input file\n\n### Workflow\n\nDescription of workflow\n\n1. Upload files to container\n1. Select files as input to gear\n1. Gear places output in Analysis, that can be then be used in RTP2-pipeline gear\n\nFreesurterator is a prerequisite. From Freesurferator the T1.nii.gz as ANAT and the\nbrainmask.nii.gz as FSMASK has to be selected. On top of that, add the DWI data \n(remember the add the RPE if it was acquired).\n\n\n### Use Cases\n\n#### Use Case 1\n\n__*Conditions__*:\n\n- *{A list of conditions that result in this use case}*\n- [ ] Possibly a list of check boxes indicating things that are absent\n- [x] and things that are present\n\nThere are no use cases, this gear will preprocess DWI data using different options \nbased on the configuration and will output data ready to go to RTP2-pipeline.\n\n### Logging\n\nIt throws the log from the registration system. \n\n## FAQ\n\n[FAQ.md](FAQ.md)\n\n## Contributing\n\nIf you want to contribute to this gear please contact garikoitz@gmail.com. \n\n[For more information about how to get started contributing to that gear,\ncheckout [CONTRIBUTING.md](CONTRIBUTING.md).]\n<!-- markdownlint-disable-file -->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "RTP2 Pre-processing Diffusion MRI",
"version": "0.2.3",
"project_urls": {
"Homepage": "https://gitlab.com/flywheel-io/scientific-solutions/gears/rtp2-preproc",
"Repository": "https://gitlab.com/flywheel-io/scientific-solutions/gears/rtp2-preproc"
},
"split_keywords": [
"flywheel",
" gears"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ed554e82fdc04fc54073ef7031dc9ac6df332c75842ff62394efc5bc97ecc8c",
"md5": "b8ed5490f7feaadc95cfca9d5178a09c",
"sha256": "6119a71da142e19a6547905b96e6f26ec8fb77d6595909d71592e9a218acb67f"
},
"downloads": -1,
"filename": "fw_gear_rtp2_preproc-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8ed5490f7feaadc95cfca9d5178a09c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 25515,
"upload_time": "2024-11-07T17:00:16",
"upload_time_iso_8601": "2024-11-07T17:00:16.168497Z",
"url": "https://files.pythonhosted.org/packages/5e/d5/54e82fdc04fc54073ef7031dc9ac6df332c75842ff62394efc5bc97ecc8c/fw_gear_rtp2_preproc-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-07 17:00:16",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "flywheel-io",
"gitlab_project": "scientific-solutions",
"lcname": "fw-gear-rtp2-preproc"
}
JSON