workflows

Module: workflows.align

ResliceFlow([output_strategy, mix_names, ...])

SlrWithQbxFlow([output_strategy, mix_names, ...])

ImageRegistrationFlow([output_strategy, ...])

The registration workflow allows the user to use only one type of registration (such as center of mass or rigid body registration only).

ApplyTransformFlow([output_strategy, ...])

SynRegistrationFlow([output_strategy, ...])

MotionCorrectionFlow([output_strategy, ...])

The Motion Correction workflow allows the user to align between-volumes DWI dataset.

BundleWarpFlow([output_strategy, mix_names, ...])

check_dimensions(static, moving)

Check the dimensions of the input images.

Module: workflows.base

IntrospectiveArgumentParser([prog, usage, ...])

get_args_default(func)

none_or_dtype(dtype)

Check None presence before type casting.

Module: workflows.combined_workflow

CombinedWorkflow([output_strategy, ...])

Module: workflows.denoise

Patch2SelfFlow([output_strategy, mix_names, ...])

NLMeansFlow([output_strategy, mix_names, ...])

LPCAFlow([output_strategy, mix_names, ...])

MPPCAFlow([output_strategy, mix_names, ...])

GibbsRingingFlow([output_strategy, ...])

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:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. 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.

Reader(data)

A line-based string reader.

NumpyDocString(docstring[, config])

dedent_lines(lines)

Deindent a list of lines maximally

Module: workflows.flow_runner

get_level(lvl)

Transforms the logging level passed on the commandline into a proper logging level name.

run_flow(flow)

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

IoInfoFlow([output_strategy, mix_names, ...])

FetchFlow([output_strategy, mix_names, ...])

SplitFlow([output_strategy, mix_names, ...])

Module: workflows.mask

MaskFlow([output_strategy, mix_names, ...])

Module: workflows.multi_io

IOIterator([output_strategy, mix_names])

Create output filenames that work nicely with multiple input files from multiple directories (processing multiple subjects with one command)

common_start(sa, sb)

Return the longest common substring from the beginning of sa and sb.

slash_to_under(dir_str)

connect_output_paths(inputs, out_dir, out_files)

Generate a list of output files paths based on input files and output strategies.

concatenate_inputs(multi_inputs)

Concatenate list of inputs.

basename_without_extension(fname)

io_iterator(inputs, out_dir, fnames[, ...])

Create an IOIterator from the parameters.

io_iterator_(frame, fnc[, output_strategy, ...])

Create an IOIterator using introspection.

Module: workflows.reconst

ReconstMAPMRIFlow([output_strategy, ...])

ReconstDtiFlow([output_strategy, mix_names, ...])

ReconstCSDFlow([output_strategy, mix_names, ...])

ReconstCSAFlow([output_strategy, mix_names, ...])

ReconstDkiFlow([output_strategy, mix_names, ...])

ReconstIvimFlow([output_strategy, ...])

ReconstRUMBAFlow([output_strategy, ...])

Module: workflows.segment

MedianOtsuFlow([output_strategy, mix_names, ...])

RecoBundlesFlow([output_strategy, ...])

LabelsBundlesFlow([output_strategy, ...])

EVACPlusFlow([output_strategy, mix_names, ...])

Module: workflows.stats

SNRinCCFlow([output_strategy, mix_names, ...])

BundleAnalysisTractometryFlow([...])

LinearMixedModelsFlow([output_strategy, ...])

BundleShapeAnalysis([output_strategy, ...])

buan_bundle_profiles(model_bundle_folder, ...)

Applies statistical analysis on bundles and saves the results in a directory specified by out_dir.

Module: workflows.tracking

LocalFiberTrackingPAMFlow([output_strategy, ...])

PFTrackingPAMFlow([output_strategy, ...])

Module: workflows.viz

HorizonFlow([output_strategy, mix_names, ...])

Module: workflows.workflow

Workflow([output_strategy, mix_names, ...])

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.