workflows
¶
Module: workflows.align
¶
|
|
|
|
|
The registration workflow allows the user to use only one type of registration (such as center of mass or rigid body registration only). |
|
|
|
|
|
The Motion Correction workflow allows the user to align between-volumes DWI dataset. |
|
|
|
Check the dimensions of the input images. |
Module: workflows.base
¶
|
|
|
|
|
Check None presence before type casting. |
Module: workflows.combined_workflow
¶
|
Module: workflows.denoise
¶
|
|
|
|
|
|
|
|
|
Module: workflows.docstring_parser
¶
This was taken directly from the file docscrape.py of numpydoc package.
Copyright (C) 2008 Stefan van der Walt <stefan@mentat.za.net>, Pauli Virtanen <pav@iki.fi>
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
A line-based string reader. |
|
|
|
Deindent a list of lines maximally |
Module: workflows.flow_runner
¶
|
Transforms the logging level passed on the commandline into a proper logging level name. |
|
Wraps the process of building an argparser that reflects the workflow that we want to run along with some generic parameters like logging, force and output strategies. |
Module: workflows.io
¶
|
|
|
|
|
Module: workflows.mask
¶
|
Module: workflows.multi_io
¶
|
Create output filenames that work nicely with multiple input files from multiple directories (processing multiple subjects with one command) |
|
Return the longest common substring from the beginning of sa and sb. |
|
|
|
Generate a list of output files paths based on input files and output strategies. |
|
Concatenate list of inputs. |
|
|
|
Create an IOIterator from the parameters. |
|
Create an IOIterator using introspection. |
Module: workflows.reconst
¶
|
|
|
|
|
|
|
|
|
|
|
|
|
Module: workflows.segment
¶
|
|
|
|
|
|
|
Module: workflows.stats
¶
|
|
|
|
|
|
|
Applies statistical analysis on bundles and saves the results in a directory specified by |
Module: workflows.tracking
¶
|
|
|
Module: workflows.viz
¶
|
Module: workflows.workflow
¶
|
ResliceFlow
¶
- class dipy.workflows.align.ResliceFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- classmethod get_short_name()¶
Return A short name for the workflow used to subdivide.
The short name is used by CombinedWorkflows and the argparser to subdivide the commandline parameters avoiding the trouble of having subworkflows parameters with the same name.
For example, a combined workflow with dti reconstruction and csd reconstruction might en up with the b0_threshold parameter. Using short names, we will have dti.b0_threshold and csd.b0_threshold available.
Returns class name by default but it is strongly advised to set it to something shorter and easier to write on commandline.
- run(input_files, new_vox_size, order=1, mode='constant', cval=0, num_processes=1, out_dir='', out_resliced='resliced.nii.gz')¶
Reslice data with new voxel resolution defined by
new_vox_sz
Parameters¶
- input_filesstring
Path to the input volumes. This path may contain wildcards to process multiple inputs at once.
- new_vox_sizevariable float
new voxel size.
- orderint, optional
order of interpolation, from 0 to 5, for resampling/reslicing, 0 nearest interpolation, 1 trilinear etc.. if you don’t want any smoothing 0 is the option you need.
- modestring, optional
Points outside the boundaries of the input are filled according to the given mode ‘constant’, ‘nearest’, ‘reflect’ or ‘wrap’.
- cvalfloat, optional
Value used for points outside the boundaries of the input if mode=’constant’.
- num_processesint, optional
Split the calculation to a pool of children processes. This only applies to 4D data arrays. Default is 1. If < 0 the maximal number of cores minus
num_processes + 1
is used (enter -1 to use as many cores as possible). 0 raises an error.- out_dirstring, optional
Output directory. (default current directory)
- out_reslicedstring, optional
Name of the resliced dataset to be saved.
SlrWithQbxFlow
¶
- class dipy.workflows.align.SlrWithQbxFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- classmethod get_short_name()¶
Return A short name for the workflow used to subdivide.
The short name is used by CombinedWorkflows and the argparser to subdivide the commandline parameters avoiding the trouble of having subworkflows parameters with the same name.
For example, a combined workflow with dti reconstruction and csd reconstruction might en up with the b0_threshold parameter. Using short names, we will have dti.b0_threshold and csd.b0_threshold available.
Returns class name by default but it is strongly advised to set it to something shorter and easier to write on commandline.
- run(static_files, moving_files, x0='affine', rm_small_clusters=50, qbx_thr=(40, 30, 20, 15), num_threads=None, greater_than=50, less_than=250, nb_pts=20, progressive=True, out_dir='', out_moved='moved.trk', out_affine='affine.txt', out_stat_centroids='static_centroids.trk', out_moving_centroids='moving_centroids.trk', out_moved_centroids='moved_centroids.trk')¶
Streamline-based linear registration.
For efficiency we apply the registration on cluster centroids and remove small clusters.
Parameters¶
static_files : string moving_files : string x0 : string, optional
rigid, similarity or affine transformation model.
- rm_small_clustersint, optional
Remove clusters that have less than rm_small_clusters.
- qbx_thrvariable int, optional
Thresholds for QuickBundlesX.
- num_threadsint, optional
Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus |num_threads + 1| is used (enter -1 to use as many threads as possible). 0 raises an error. Only metrics using OpenMP will use this variable.
- greater_thanint, optional
Keep streamlines that have length greater than this value.
- less_thanint, optional
Keep streamlines have length less than this value.
- nb_ptsint, optional
Number of points for discretizing each streamline.
progressive : boolean, optional out_dir : string, optional
Output directory. (default current directory)
- out_movedstring, optional
Filename of moved tractogram.
- out_affinestring, optional
Filename of affine for SLR transformation.
- out_stat_centroidsstring, optional
Filename of static centroids.
- out_moving_centroidsstring, optional
Filename of moving centroids.
- out_moved_centroidsstring, optional
Filename of moved centroids.
Notes¶
The order of operations is the following. First short or long streamlines are removed. Second the tractogram or a random selection of the tractogram is clustered with QuickBundlesX. Then SLR [Garyfallidis15] is applied.
References¶
[Garyfallidis15]Garyfallidis et al. “Robust and efficient linear
registration of white-matter fascicles in the space of streamlines”, NeuroImage, 117, 124–140, 2015
[Garyfallidis14]Garyfallidis et al., “Direct native-space fiber
bundle alignment for group comparisons”, ISMRM, 2014.
[Garyfallidis17]Garyfallidis et al. Recognition of white matter
bundles using local and global streamline-based registration and clustering, NeuroImage, 2017.
ImageRegistrationFlow
¶
- class dipy.workflows.align.ImageRegistrationFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
The registration workflow allows the user to use only one type of registration (such as center of mass or rigid body registration only).
Alternatively, a registration can be done in a progressive manner. For example, using affine registration with progressive set to ‘True’ will involve center of mass, translation, rigid body and full affine registration. Whereas, when progressive is False the registration will include only center of mass and affine registration. The progressive registration will be slower but will improve the quality.
This can be controlled by using the progressive flag (True by default).
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- run(static_image_files, moving_image_files, transform='affine', nbins=32, sampling_prop=None, metric='mi', level_iters=(10000, 1000, 100), sigmas=(3.0, 1.0, 0.0), factors=(4, 2, 1), progressive=True, save_metric=False, out_dir='', out_moved='moved.nii.gz', out_affine='affine.txt', out_quality='quality_metric.txt')¶
Parameters¶
- static_image_filesstring
Path to the static image file.
- moving_image_filesstring
Path to the moving image file.
- transformstring, optional
com: center of mass, trans: translation, rigid: rigid body, rigid_isoscaling: rigid body + isotropic scaling, rigid_scaling: rigid body + scaling, affine: full affine including translation, rotation, shearing and scaling.
- nbinsint, optional
Number of bins to discretize the joint and marginal PDF.
- sampling_propint, optional
- Number ([0-100]) of voxels for calculating the PDF.
‘None’ implies all voxels.
- metricstring, optional
Similarity metric for gathering mutual information).
- level_itersvariable int, optional
- The number of iterations at each scale of the scale space.
level_iters[0] corresponds to the coarsest scale, level_iters[-1] the finest, where n is the length of the
sequence.
- sigmasvariable floats, optional
- Custom smoothing parameter to build the scale space (one parameter
for each scale).
- factorsvariable floats, optional
- Custom scale factors to build the scale space (one factor for each
scale).
- progressiveboolean, optional
Enable/Disable the progressive registration.
- save_metricboolean, optional
If true, quality assessment metric are saved in ‘quality_metric.txt’.
- out_dirstring, optional
- Directory to save the transformed image and the affine matrix
(default current directory).
- out_movedstring, optional
Name for the saved transformed image.
- out_affinestring, optional
Name for the saved affine matrix.
- out_qualitystring, optional
- Name of the file containing the saved quality
metric.
ApplyTransformFlow
¶
- class dipy.workflows.align.ApplyTransformFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- run(static_image_files, moving_image_files, transform_map_file, transform_type='affine', out_dir='', out_file='transformed.nii.gz')¶
Parameters¶
- static_image_filesstring
Path of the static image file.
- moving_image_filesstring
Path of the moving image(s). It can be a single image or a folder containing multiple images.
- transform_map_filestring
For the affine case, it should be a text(*.txt) file containing the affine matrix. For the diffeomorphic case, it should be a nifti file containing the mapping displacement field in each voxel with this shape (x, y, z, 3, 2).
- transform_typestring, optional
Select the transformation type to apply between ‘affine’ or ‘diffeomorphic’.
- out_dirstring, optional
Directory to save the transformed files (default current directory).
- out_filestring, optional
Name of the transformed file. It is recommended to use the flag –mix-names to prevent the output files from being overwritten.
SynRegistrationFlow
¶
- class dipy.workflows.align.SynRegistrationFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- run(static_image_files, moving_image_files, prealign_file='', inv_static=False, level_iters=(10, 10, 5), metric='cc', mopt_sigma_diff=2.0, mopt_radius=4, mopt_smooth=0.0, mopt_inner_iter=0, mopt_q_levels=256, mopt_double_gradient=True, mopt_step_type='', step_length=0.25, ss_sigma_factor=0.2, opt_tol=1e-05, inv_iter=20, inv_tol=0.001, out_dir='', out_warped='warped_moved.nii.gz', out_inv_static='inc_static.nii.gz', out_field='displacement_field.nii.gz')¶
Parameters¶
- static_image_filesstring
Path of the static image file.
- moving_image_filesstring
Path to the moving image file.
- prealign_filestring, optional
- The text file containing pre alignment information via an
affine matrix.
- inv_staticboolean, optional
Apply the inverse mapping to the static image.
- level_itersvariable int, optional
The number of iterations at each level of the gaussian pyramid.
- metricstring, optional
The metric to be used. metric available: cc (Cross Correlation), ssd (Sum Squared Difference), em (Expectation-Maximization).
- mopt_sigma_difffloat, optional
Metric option applied on Cross correlation (CC). The standard deviation of the Gaussian smoothing kernel to be applied to the update field at each iteration.
- mopt_radiusint, optional
Metric option applied on Cross correlation (CC). the radius of the squared (cubic) neighborhood at each voxel to be considered to compute the cross correlation.
- mopt_smoothfloat, optional
Metric option applied on Sum Squared Difference (SSD) and Expectation Maximization (EM). Smoothness parameter, the larger the value the smoother the deformation field. (default 1.0 for EM, 4.0 for SSD)
- mopt_inner_iterint, optional
Metric option applied on Sum Squared Difference (SSD) and Expectation Maximization (EM). This is number of iterations to be performed at each level of the multi-resolution Gauss-Seidel optimization algorithm (this is not the number of steps per Gaussian Pyramid level, that parameter must be set for the optimizer, not the metric). Default 5 for EM, 10 for SSD.
- mopt_q_levelsint, optional
Metric option applied on Expectation Maximization (EM). Number of quantization levels (Default: 256 for EM)
- mopt_double_gradientbool, optional
Metric option applied on Expectation Maximization (EM). if True, the gradient of the expected static image under the moving modality will be added to the gradient of the moving image, similarly, the gradient of the expected moving image under the static modality will be added to the gradient of the static image.
- mopt_step_typestring, optional
Metric option applied on Sum Squared Difference (SSD) and Expectation Maximization (EM). The optimization schedule to be used in the multi-resolution Gauss-Seidel optimization algorithm (not used if Demons Step is selected). Possible value: (‘gauss_newton’, ‘demons’). default: ‘gauss_newton’ for EM, ‘demons’ for SSD.
- step_lengthfloat, optional
- the length of the maximum displacement vector of the update
displacement field at each iteration.
- ss_sigma_factorfloat, optional
- parameter of the scale-space smoothing kernel. For example, the
std. dev. of the kernel will be factor*(2^i) in the isotropic case where i = 0, 1, …, n_scales is the scale.
- opt_tolfloat, optional
- the optimization will stop when the estimated derivative of the
energy profile w.r.t. time falls below this threshold.
- inv_iterint, optional
- the number of iterations to be performed by the displacement field
inversion algorithm.
- inv_tolfloat, optional
- the displacement field inversion algorithm will stop iterating
when the inversion error falls below this threshold.
- out_dirstring, optional
Directory to save the transformed files (default current directory).
- out_warpedstring, optional
Name of the warped file.
- out_inv_staticstring, optional
- Name of the file to save the static image after applying the
inverse mapping.
- out_fieldstring, optional
Name of the file to save the diffeomorphic map.
MotionCorrectionFlow
¶
- class dipy.workflows.align.MotionCorrectionFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
The Motion Correction workflow allows the user to align between-volumes DWI dataset.
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- run(input_files, bvalues_files, bvectors_files, b0_threshold=50, bvecs_tol=0.01, out_dir='', out_moved='moved.nii.gz', out_affine='affine.txt')¶
Parameters¶
- input_filesstring
Path to the input volumes. This path may contain wildcards to process multiple inputs at once.
- bvalues_filesstring
Path to the bvalues files. This path may contain wildcards to use multiple bvalues files at once.
- bvectors_filesstring
Path to the bvectors files. This path may contain wildcards to use multiple bvectors files at once.
- b0_thresholdfloat, optional
Threshold used to find b0 volumes.
- bvecs_tolfloat, optional
Threshold used to check that norm(bvec) = 1 +/- bvecs_tol b-vectors are unit vectors
- out_dirstring, optional
- Directory to save the transformed image and the affine matrix
(default current directory).
- out_movedstring, optional
Name for the saved transformed image.
- out_affinestring, optional
Name for the saved affine matrix.
BundleWarpFlow
¶
- class dipy.workflows.align.BundleWarpFlow(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Bases:
Workflow
- __init__(output_strategy='absolute', mix_names=False, force=False, skip=False)¶
Initialize the basic workflow object.
This object takes care of any workflow operation that is common to all the workflows. Every new workflow should extend this class.
- classmethod get_short_name()¶
Return A short name for the workflow used to subdivide.
The short name is used by CombinedWorkflows and the argparser to subdivide the commandline parameters avoiding the trouble of having subworkflows parameters with the same name.
For example, a combined workflow with dti reconstruction and csd reconstruction might en up with the b0_threshold parameter. Using short names, we will have dti.b0_threshold and csd.b0_threshold available.
Returns class name by default but it is strongly advised to set it to something shorter and easier to write on commandline.
- run(static_file, moving_file, dist=None, alpha=0.3, beta=20, max_iter=15, affine=True, out_dir='', out_linear_moved='linearly_moved.trk', out_nonlinear_moved='nonlinearly_moved.trk', out_warp_transform='warp_transform.npy', out_warp_kernel='warp_kernel.npy', out_dist='distance_matrix.npy', out_matched_pairs='matched_pairs.npy')¶
BundleWarp: streamline-based nonlinear registration.
BundleWarp is nonrigid registration method for deformable registration of white matter tracts.
Parameters¶
- static_filestring
Path to the static (reference) .trk file.
- moving_filestring
Path to the moving (target to be registered) .trk file.
- diststring, optional
Path to the precalculated distance matrix file.
- alphafloat, optional
Represents the trade-off between regularizing the deformation and having points match very closely. Lower value of alpha means high deformations. It is represented with λ in BundleWarp paper. NOTE: setting alpha<=0.01 will result in highly deformable registration that could extremely modify the original anatomy of the moving bundle. (default 0.3)
- betaint, optional
Represents the strength of the interaction between points Gaussian kernel size. (default 20)
- max_iterint, optional
Maximum number of iterations for deformation process in ml-CPD method. (default 15)
- affineboolean, optional
If False, use rigid registration as starting point. (default True)
- out_dirstring, optional
Output directory. (default current directory)
- out_linear_movedstring, optional
Filename of linearly moved bundle.
- out_nonlinear_movedstring, optional
Filename of nonlinearly moved (warped) bundle.
- out_warp_transformstring, optional
Filename of warp transformations generated by BundleWarp.
- out_warp_kernelstring, optional
Filename of regularization gaussian kernel generated by BundleWarp.
- out_diststring, optional
Filename of MDF distance matrix.
- out_matched_pairsstring, optional
Filename of matched pairs; treamline correspondences between two bundles.
References¶
[Chandio2023]Chandio et al. “BundleWarp, streamline-based nonlinear registration of white matter tracts.” bioRxiv (2023): 2023-01.