NIPY logo
Home · Quickstart · Documentation · Citation · NiPy
Loading

Table Of Contents

Versions

ReleaseDevel
0.7.0pre-0.8
Download Github

Links

interfaces.ants.registration

Registration

Link to code

Wraps command antsRegistration

>>> import copy
>>> from nipype.interfaces.ants import Registration
>>> reg = Registration()
>>> reg.inputs.fixed_image = ['fixed1.nii', 'fixed2.nii']
>>> reg.inputs.moving_image = ['moving1.nii', 'moving2.nii']
>>> reg.inputs.output_transform_prefix = "output_"
>>> reg.inputs.initial_moving_transform = 'trans.mat'
>>> reg.inputs.transforms = ['Affine', 'SyN']
>>> reg.inputs.transform_parameters = [(2.0,), (0.25, 3.0, 0.0)]
>>> reg.inputs.number_of_iterations = [[1500, 200], [100, 50, 30]]
>>> reg.inputs.dimension = 3
>>> reg.inputs.write_composite_transform = True
>>> reg.inputs.collapse_output_transforms = False
>>> reg.inputs.metric = ['Mattes']*2
>>> reg.inputs.metric_weight = [1]*2 # Default (value ignored currently by ANTs)
>>> reg.inputs.radius_or_number_of_bins = [32]*2
>>> reg.inputs.sampling_strategy = ['Random', None]
>>> reg.inputs.sampling_percentage = [0.05, None]
>>> reg.inputs.convergence_threshold = [1.e-8, 1.e-9]
>>> reg.inputs.convergence_window_size = [20]*2
>>> reg.inputs.smoothing_sigmas = [[1,0], [2,1,0]]
>>> reg.inputs.shrink_factors = [[2,1], [3,2,1]]
>>> reg.inputs.use_estimate_learning_rate_once = [True, True]
>>> reg.inputs.use_histogram_matching = [True, True] # This is the default
>>> reg.inputs.output_warped_image = 'output_warped_image.nii.gz'
>>> reg1 = copy.deepcopy(reg)
>>> reg1.inputs.winsorize_lower_quantile = 0.025
>>> reg1.inputs.collapse_linear_transforms_to_fixed_image_header = False
>>> reg1.cmdline
'antsRegistration --collapse-linear-transforms-to-fixed-image-header 0 --collapse-output-transforms 0 --dimensionality 3 --initial-moving-transform [ trans.mat, 0 ] --interpolation Linear --output [ output_, output_warped_image.nii.gz ] --transform Affine[ 2.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32 ,Random,0.05 ] --convergence [ 1500x200, 1e-08, 20 ] --smoothing-sigmas 1x0 --shrink-factors 2x1 --use-estimate-learning-rate-once 1 --use-histogram-matching 1 --transform SyN[ 0.25, 3.0, 0.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32  ] --convergence [ 100x50x30, 1e-09, 20 ] --smoothing-sigmas 2x1x0 --shrink-factors 3x2x1 --use-estimate-learning-rate-once 1 --use-histogram-matching 1 --winsorize-image-intensities [ 0.025, 1.0 ]  --write-composite-transform 1'
>>> reg1.run()  
>>> reg2 = copy.deepcopy(reg)
>>> reg2.inputs.winsorize_upper_quantile = 0.975
>>> reg2.cmdline
'antsRegistration --collapse-linear-transforms-to-fixed-image-header 0 --collapse-output-transforms 0 --dimensionality 3 --initial-moving-transform [ trans.mat, 0 ] --interpolation Linear --output [ output_, output_warped_image.nii.gz ] --transform Affine[ 2.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32 ,Random,0.05 ] --convergence [ 1500x200, 1e-08, 20 ] --smoothing-sigmas 1x0 --shrink-factors 2x1 --use-estimate-learning-rate-once 1 --use-histogram-matching 1 --transform SyN[ 0.25, 3.0, 0.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32  ] --convergence [ 100x50x30, 1e-09, 20 ] --smoothing-sigmas 2x1x0 --shrink-factors 3x2x1 --use-estimate-learning-rate-once 1 --use-histogram-matching 1 --winsorize-image-intensities [ 0.0, 0.975 ]  --write-composite-transform 1'
>>> reg3 = copy.deepcopy(reg)
>>> reg3.inputs.winsorize_lower_quantile = 0.025
>>> reg3.inputs.winsorize_upper_quantile = 0.975
>>> reg3.cmdline
'antsRegistration --collapse-linear-transforms-to-fixed-image-header 0 --collapse-output-transforms 0 --dimensionality 3 --initial-moving-transform [ trans.mat, 0 ] --interpolation Linear --output [ output_, output_warped_image.nii.gz ] --transform Affine[ 2.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32 ,Random,0.05 ] --convergence [ 1500x200, 1e-08, 20 ] --smoothing-sigmas 1x0 --shrink-factors 2x1 --use-estimate-learning-rate-once 1 --use-histogram-matching 1 --transform SyN[ 0.25, 3.0, 0.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32  ] --convergence [ 100x50x30, 1e-09, 20 ] --smoothing-sigmas 2x1x0 --shrink-factors 3x2x1 --use-estimate-learning-rate-once 1 --use-histogram-matching 1 --winsorize-image-intensities [ 0.025, 0.975 ]  --write-composite-transform 1'
Test collapse transforms flag
>>> reg4 = copy.deepcopy(reg)
>>> reg4.inputs.collapse_output_transforms = True
>>> outputs = reg4._list_outputs()
>>> print outputs 
{'reverse_invert_flags': [True, False], 'inverse_composite_transform': ['.../nipype/testing/data/output_InverseComposite.h5'], 'forward_invert_flags': [False, False], 'reverse_transforms': ['.../nipype/testing/data/output_0GenericAffine.mat', '.../nipype/testing/data/output_1InverseWarp.nii.gz'], 'composite_transform': ['.../nipype/testing/data/output_Composite.h5'], 'forward_transforms': ['.../nipype/testing/data/output_0GenericAffine.mat', '.../nipype/testing/data/output_1Warp.nii.gz']}
>>> reg4.aggregate_outputs() 

Inputs:

[Mandatory]
fixed_image: (an existing file name)
        image to apply transformation to (generally a coregistered functional)
metric: (a list of items which are 'CC' or 'MeanSquares' or 'Demons' or 'GC' or 'MI' or
         'Mattes')
metric_weight: (a list of items which are a float, nipype default value: [])
        Note that the metricWeight is currently not used. Rather, it is a temporary place
        holder until multivariate metrics are available for a single stage.
        requires: metric
moving_image: (an existing file name)
        image to apply transformation to (generally a coregistered functional)
transforms: (a list of items which are 'Rigid' or 'Affine' or 'CompositeAffine' or
         'Similarity' or 'Translation' or 'BSpline' or 'GaussianDisplacementField' or
         'TimeVaryingVelocityField' or 'TimeVaryingBSplineVelocityField' or 'SyN' or
         'BSplineSyN' or 'Exponential' or 'BSplineExponential')

[Optional]
args: (a string)
        Additional parameters to the command
collapse_linear_transforms_to_fixed_image_header: (a boolean, nipype default value:
         False)
collapse_output_transforms: (a boolean)
        Collapse output transforms. Specifically, enabling this option combines all adjacent
        linear transforms and composes all adjacent displacement field transforms before writing
        the results to disk.
convergence_threshold: (a list of at least 1 items which are a float, nipype default
         value: [9.9999999999999995e-07])
        requires: number_of_iterations
convergence_window_size: (a list of at least 1 items which are an integer, nipype default
         value: [10])
        requires: convergence_threshold
dimension: (3 or 2, nipype default value: 3)
        image dimension (2 or 3)
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
interpolation: ('Linear' or 'NearestNeighbor' or 'CosineWindowedSinc' or
         'WelchWindowedSinc' or 'HammingWindowedSinc' or 'LanczosWindowedSinc', nipype default
         value: Linear)
num_threads: (an integer, nipype default value: -1)
        Number of ITK threads to use
number_of_iterations: (a list of items which are a list of items which are an integer)
output_inverse_warped_image: (a boolean or a file name)
        requires: output_warped_image
output_transform_prefix: (a string, nipype default value: transform)
output_warped_image: (a boolean or a file name)
radius_or_number_of_bins: (a list of items which are an integer, nipype default value:
         [])
        requires: metric_weight
sampling_percentage: (a list of at least 1 items which are 0.0 <= a floating point number
         <= 1.0 or None)
        requires: sampling_strategy
sampling_strategy: (a list of at least 1 items which are 'Dense' or 'Regular' or 'Random'
         or None, nipype default value: ['Dense'])
        requires: metric_weight
shrink_factors: (a list of items which are a list of items which are an integer)
smoothing_sigmas: (a list of items which are a list of items which are an integer)
transform_parameters: (a list of items which are a float or a tuple of the form: (a
         float) or a tuple of the form: (a float, a float, a float))
use_estimate_learning_rate_once: (a list of items which are a boolean)
use_histogram_matching: (a list of items which are a boolean, nipype default value: [])
winsorize_lower_quantile: (0.0 <= a floating point number <= 1.0, nipype default value:
         0.0)
        The Lower quantile to clip image ranges
winsorize_upper_quantile: (0.0 <= a floating point number <= 1.0, nipype default value:
         1.0)
        The Upper quantile to clip image ranges
write_composite_transform: (a boolean, nipype default value: False)

Outputs:

composite_transform: (a list of items which are a file name)
        Composite transform file
forward_invert_flags: (a list of items which are a boolean)
        List of flags corresponding to the forward transforms
forward_transforms: (a list of items which are a file name)
        List of output transforms for forward registration
inverse_composite_transform: (a list of items which are a file name)
        Inverse composite transform file
reverse_invert_flags: (a list of items which are a boolean)
        List of flags corresponding to the reverse transforms
reverse_transforms: (a list of items which are a file name)
        List of output transforms for reverse registration