nipype.interfaces.ants.utils module

ANTs’ utilities.

AI

Link to code

Bases: ANTSCommand

Wrapped executable: antsAI.

Calculate the optimal linear transform parameters for aligning two images.

Examples

>>> AI(
...     fixed_image='structural.nii',
...     moving_image='epi.nii',
...     metric=('Mattes', 32, 'Regular', 1),
... ).cmdline
'antsAI -c [10,1e-06,10] -d 3 -m Mattes[structural.nii,epi.nii,32,Regular,1]
-o initialization.mat -p 0 -s [20,0.12] -t Affine[0.1] -v 0'

>>> AI(fixed_image='structural.nii',
...    moving_image='epi.nii',
...    metric=('Mattes', 32, 'Regular', 1),
...    search_grid=(12, (1, 1, 1)),
... ).cmdline
'antsAI -c [10,1e-06,10] -d 3 -m Mattes[structural.nii,epi.nii,32,Regular,1]
-o initialization.mat -p 0 -s [20,0.12] -g [12.0,1x1x1] -t Affine[0.1] -v 0'
fixed_image : a pathlike object or string representing an existing file
Image to which the moving_image should be transformed.
metric : a tuple of the form: (‘Mattes’ or ‘GC’ or ‘MI’, an integer (int or long), ‘Regular’ or ‘Random’ or ‘None’, 0.0 <= a floating point number <= 1.0)
The metric(s) to use. Maps to a command-line argument: -m %s.
moving_image : a pathlike object or string representing an existing file
Image that will be transformed to fixed_image.
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
convergence : a tuple of the form: (1 <= a long integer <= 10000, a float, 1 <= a long integer <= 100)
Convergence. Maps to a command-line argument: -c [%d,%g,%d]. (Nipype default value: (10, 1e-06, 10))
dimension : 3 or 2
Dimension of output image. Maps to a command-line argument: -d %d. (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
fixed_image_mask : a pathlike object or string representing an existing file
Fixed mage mask. Maps to a command-line argument: -x %s.
moving_image_mask : a pathlike object or string representing an existing file
Moving mage mask. Requires inputs: fixed_image_mask.
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
output_transform : a pathlike object or string representing a file
Output file name. Maps to a command-line argument: -o %s. (Nipype default value: initialization.mat)
principal_axes : a boolean
Align using principal axes. Maps to a command-line argument: -p %d. Mutually exclusive with inputs: blobs. (Nipype default value: False)
search_factor : a tuple of the form: (a float, 0.0 <= a floating point number <= 1.0)
Search factor. Maps to a command-line argument: -s [%g,%g]. (Nipype default value: (20, 0.12))
search_grid : a tuple of the form: (a float, a tuple of the form: (a float, a float, a float)) or a tuple of the form: (a float, a tuple of the form: (a float, a float))
Translation search grid in mm. Maps to a command-line argument: -g %s.
transform : a tuple of the form: (‘Affine’ or ‘Rigid’ or ‘Similarity’, a floating point number > 0.0)
Several transform options are available. Maps to a command-line argument: -t %s[%g]. (Nipype default value: ('Affine', 0.1))
verbose : a boolean
Enable verbosity. Maps to a command-line argument: -v %d. (Nipype default value: False)
output_transform : a pathlike object or string representing an existing file
Output file name.

AffineInitializer

Link to code

Bases: ANTSCommand

Wrapped executable: antsAffineInitializer.

Initialize an affine transform (as in antsBrainExtraction.sh)

>>> from nipype.interfaces.ants import AffineInitializer
>>> init = AffineInitializer()
>>> init.inputs.fixed_image = 'fixed1.nii'
>>> init.inputs.moving_image = 'moving1.nii'
>>> init.cmdline
'antsAffineInitializer 3 fixed1.nii moving1.nii transform.mat 15.000000 0.100000 0 10'
fixed_image : a pathlike object or string representing an existing file
Reference image. Maps to a command-line argument: %s (position: 1).
moving_image : a pathlike object or string representing an existing file
Moving image. Maps to a command-line argument: %s (position: 2).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
dimension : 3 or 2
Dimension. Maps to a command-line argument: %s (position: 0). (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
local_search : an integer (int or long)
determines if a local optimization is run at each search point for the set number of iterations.

Maps to a command-line argument: %d (position: 7). (Nipype default value: 10)

num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
out_file : a pathlike object or string representing a file
Output transform file. Maps to a command-line argument: %s (position: 3). (Nipype default value: transform.mat)
principal_axes : a boolean
Whether the rotation is searched around an initial principal axis alignment. Maps to a command-line argument: %d (position: 6). (Nipype default value: False)
radian_fraction : 0.0 <= a floating point number <= 1.0
Search this arc +/- principal axes. Maps to a command-line argument: %f (position: 5). (Nipype default value: 0.1)
search_factor : a float
Increments (degrees) for affine search. Maps to a command-line argument: %f (position: 4). (Nipype default value: 15.0)
out_file : a pathlike object or string representing a file
Output transform file.

AverageAffineTransform

Link to code

Bases: ANTSCommand

Wrapped executable: AverageAffineTransform.

Examples

>>> from nipype.interfaces.ants import AverageAffineTransform
>>> avg = AverageAffineTransform()
>>> avg.inputs.dimension = 3
>>> avg.inputs.transforms = ['trans.mat', 'func_to_struct.mat']
>>> avg.inputs.output_affine_transform = 'MYtemplatewarp.mat'
>>> avg.cmdline
'AverageAffineTransform 3 MYtemplatewarp.mat trans.mat func_to_struct.mat'
dimension : 3 or 2
Image dimension (2 or 3). Maps to a command-line argument: %d (position: 0).
output_affine_transform : a pathlike object or string representing a file
Outputfname.txt: the name of the resulting transform. Maps to a command-line argument: %s (position: 1).
transforms : a list of items which are a pathlike object or string representing an existing file
Transforms to average. Maps to a command-line argument: %s (position: 3).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
affine_transform : a pathlike object or string representing an existing file
Average transform file.

AverageImages

Link to code

Bases: ANTSCommand

Wrapped executable: AverageImages.

Examples

>>> from nipype.interfaces.ants import AverageImages
>>> avg = AverageImages()
>>> avg.inputs.dimension = 3
>>> avg.inputs.output_average_image = "average.nii.gz"
>>> avg.inputs.normalize = True
>>> avg.inputs.images = ['rc1s1.nii', 'rc1s1.nii']
>>> avg.cmdline
'AverageImages 3 average.nii.gz 1 rc1s1.nii rc1s1.nii'
dimension : 3 or 2
Image dimension (2 or 3). Maps to a command-line argument: %d (position: 0).
images : a list of items which are a pathlike object or string representing an existing file
Image to apply transformation to (generally a coregistered functional). Maps to a command-line argument: %s (position: 3).
normalize : a boolean
Normalize: if true, the 2nd image is divided by its mean. This will select the largest image to average into. Maps to a command-line argument: %d (position: 2).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
output_average_image : a pathlike object or string representing a file
The name of the resulting image. Maps to a command-line argument: %s (position: 1). (Nipype default value: average.nii)
output_average_image : a pathlike object or string representing an existing file
Average image file.

ComposeMultiTransform

Link to code

Bases: ANTSCommand

Wrapped executable: ComposeMultiTransform.

Take a set of transformations and convert them to a single transformation matrix/warpfield.

Examples

>>> from nipype.interfaces.ants import ComposeMultiTransform
>>> compose_transform = ComposeMultiTransform()
>>> compose_transform.inputs.dimension = 3
>>> compose_transform.inputs.transforms = ['struct_to_template.mat', 'func_to_struct.mat']
>>> compose_transform.cmdline
'ComposeMultiTransform 3 struct_to_template_composed.mat
struct_to_template.mat func_to_struct.mat'
transforms : a list of items which are a pathlike object or string representing an existing file
Transforms to average. Maps to a command-line argument: %s (position: 3).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
dimension : 3 or 2
Image dimension (2 or 3). Maps to a command-line argument: %d (position: 0). (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
output_transform : a pathlike object or string representing a file
The name of the resulting transform. Maps to a command-line argument: %s (position: 1).
reference_image : a pathlike object or string representing a file
Reference image (only necessary when output is warpfield). Maps to a command-line argument: %s (position: 2).
output_transform : a pathlike object or string representing an existing file
Composed transform file.

CreateJacobianDeterminantImage

Link to code

Bases: ANTSCommand

Wrapped executable: CreateJacobianDeterminantImage.

Examples

>>> from nipype.interfaces.ants import CreateJacobianDeterminantImage
>>> jacobian = CreateJacobianDeterminantImage()
>>> jacobian.inputs.imageDimension = 3
>>> jacobian.inputs.deformationField = 'ants_Warp.nii.gz'
>>> jacobian.inputs.outputImage = 'out_name.nii.gz'
>>> jacobian.cmdline
'CreateJacobianDeterminantImage 3 ants_Warp.nii.gz out_name.nii.gz'
deformationField : a pathlike object or string representing an existing file
Deformation transformation file. Maps to a command-line argument: %s (position: 1).
imageDimension : 3 or 2
Image dimension (2 or 3). Maps to a command-line argument: %d (position: 0).
outputImage : a pathlike object or string representing a file
Output filename. Maps to a command-line argument: %s (position: 2).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
doLogJacobian : 0 or 1
Return the log jacobian. Maps to a command-line argument: %d (position: 3).
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
useGeometric : 0 or 1
Return the geometric jacobian. Maps to a command-line argument: %d (position: 4).
jacobian_image : a pathlike object or string representing an existing file
Jacobian image.

ImageMath

Link to code

Bases: ANTSCommand, CopyHeaderInterface

Wrapped executable: ImageMath.

Operations over images.

Examples

>>> ImageMath(
...     op1='structural.nii',
...     operation='+',
...     op2='2').cmdline
'ImageMath 3 structural_maths.nii + structural.nii 2'

>>> ImageMath(
...     op1='structural.nii',
...     operation='Project',
...     op2='1 2').cmdline
'ImageMath 3 structural_maths.nii Project structural.nii 1 2'

>>> ImageMath(
...     op1='structural.nii',
...     operation='G',
...     op2='4').cmdline
'ImageMath 3 structural_maths.nii G structural.nii 4'

>>> ImageMath(
...     op1='structural.nii',
...     operation='TruncateImageIntensity',
...     op2='0.005 0.999 256').cmdline
'ImageMath 3 structural_maths.nii TruncateImageIntensity structural.nii 0.005 0.999 256'

By default, Nipype copies headers from the first input image (op1) to the output image. For the PadImage operation, the header cannot be copied from inputs to outputs, and so copy_header option is automatically set to False.

>>> pad = ImageMath(
...     op1='structural.nii',
...     operation='PadImage')
>>> pad.inputs.copy_header
False

While the operation is set to PadImage, setting copy_header = True will have no effect.

>>> pad.inputs.copy_header = True
>>> pad.inputs.copy_header
False

For any other operation, copy_header can be enabled/disabled normally:

>>> pad.inputs.operation = "ME"
>>> pad.inputs.copy_header = True
>>> pad.inputs.copy_header
True
op1 : a pathlike object or string representing an existing file
First operator. Maps to a command-line argument: %s (position: -2).
operation : ‘m’ or ‘vm’ or ‘+’ or ‘v+’ or ‘-‘ or ‘v-‘ or ‘/’ or ‘^’ or ‘max’ or ‘exp’ or ‘addtozero’ or ‘overadd’ or ‘abs’ or ‘total’ or ‘mean’ or ‘vtotal’ or ‘Decision’ or ‘Neg’ or ‘Project’ or ‘G’ or ‘MD’ or ‘ME’ or ‘MO’ or ‘MC’ or ‘GD’ or ‘GE’ or ‘GO’ or ‘GC’ or ‘TruncateImageIntensity’ or ‘Laplacian’ or ‘GetLargestComponent’ or ‘FillHoles’ or ‘PadImage’
Mathematical operations. Maps to a command-line argument: %s (position: 3).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
copy_header : a boolean
Copy headers of the original image into the output (corrected) file. (Nipype default value: True)
dimension : an integer (int or long)
Dimension of output image. Maps to a command-line argument: %d (position: 1). (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
op2 : a pathlike object or string representing an existing file or a unicode string
Second operator. Maps to a command-line argument: %s (position: -1).
output_image : a pathlike object or string representing a file
Output image file. Maps to a command-line argument: %s (position: 2).
output_image : a pathlike object or string representing an existing file
Output image file.

LabelGeometry

Link to code

Bases: ANTSCommand

Wrapped executable: LabelGeometryMeasures.

Extracts geometry measures using a label file and an optional image file

Examples

>>> from nipype.interfaces.ants import LabelGeometry
>>> label_extract = LabelGeometry()
>>> label_extract.inputs.dimension = 3
>>> label_extract.inputs.label_image = 'atlas.nii.gz'
>>> label_extract.cmdline
'LabelGeometryMeasures 3 atlas.nii.gz [] atlas.csv'

>>> label_extract.inputs.intensity_image = 'ants_Warp.nii.gz'
>>> label_extract.cmdline
'LabelGeometryMeasures 3 atlas.nii.gz ants_Warp.nii.gz atlas.csv'
intensity_image : a pathlike object or string representing an existing file
Intensity image to extract values from. This is an optional input. Maps to a command-line argument: %s (position: 2). (Nipype default value: [])
label_image : a pathlike object or string representing a file
Label image to use for extracting geometry measures. Maps to a command-line argument: %s (position: 1).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
dimension : 3 or 2
Image dimension (2 or 3). Maps to a command-line argument: %d (position: 0). (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
output_file : a unicode string
Name of output file. Maps to a command-line argument: %s (position: 3).
output_file : a pathlike object or string representing an existing file
CSV file of geometry measures.

MultiplyImages

Link to code

Bases: ANTSCommand

Wrapped executable: MultiplyImages.

Examples

>>> from nipype.interfaces.ants import MultiplyImages
>>> test = MultiplyImages()
>>> test.inputs.dimension = 3
>>> test.inputs.first_input = 'moving2.nii'
>>> test.inputs.second_input = 0.25
>>> test.inputs.output_product_image = "out.nii"
>>> test.cmdline
'MultiplyImages 3 moving2.nii 0.25 out.nii'
dimension : 3 or 2
Image dimension (2 or 3). Maps to a command-line argument: %d (position: 0).
first_input : a pathlike object or string representing an existing file
Image 1. Maps to a command-line argument: %s (position: 1).
output_product_image : a pathlike object or string representing a file
Outputfname.nii.gz: the name of the resulting image. Maps to a command-line argument: %s (position: 3).
second_input : a pathlike object or string representing an existing file or a float
Image 2 or multiplication weight. Maps to a command-line argument: %s (position: 2).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
output_product_image : a pathlike object or string representing an existing file
Average image file.

ResampleImageBySpacing

Link to code

Bases: ANTSCommand

Wrapped executable: ResampleImageBySpacing.

Resample an image with a given spacing.

Examples

>>> res = ResampleImageBySpacing(dimension=3)
>>> res.inputs.input_image = 'structural.nii'
>>> res.inputs.output_image = 'output.nii.gz'
>>> res.inputs.out_spacing = (4, 4, 4)
>>> res.cmdline  #doctest: +ELLIPSIS
'ResampleImageBySpacing 3 structural.nii output.nii.gz 4 4 4'

>>> res = ResampleImageBySpacing(dimension=3)
>>> res.inputs.input_image = 'structural.nii'
>>> res.inputs.output_image = 'output.nii.gz'
>>> res.inputs.out_spacing = (4, 4, 4)
>>> res.inputs.apply_smoothing = True
>>> res.cmdline  #doctest: +ELLIPSIS
'ResampleImageBySpacing 3 structural.nii output.nii.gz 4 4 4 1'

>>> res = ResampleImageBySpacing(dimension=3)
>>> res.inputs.input_image = 'structural.nii'
>>> res.inputs.output_image = 'output.nii.gz'
>>> res.inputs.out_spacing = (0.4, 0.4, 0.4)
>>> res.inputs.apply_smoothing = True
>>> res.inputs.addvox = 2
>>> res.inputs.nn_interp = False
>>> res.cmdline  #doctest: +ELLIPSIS
'ResampleImageBySpacing 3 structural.nii output.nii.gz 0.4 0.4 0.4 1 2 0'
input_image : a pathlike object or string representing an existing file
Input image file. Maps to a command-line argument: %s (position: 2).
out_spacing : a list of from 2 to 3 items which are a float or a tuple of the form: (a float, a float, a float) or a tuple of the form: (a float, a float)
Output spacing. Maps to a command-line argument: %s (position: 4).
addvox : an integer (int or long)
Addvox pads each dimension by addvox. Maps to a command-line argument: %d (position: 6). Requires inputs: apply_smoothing.
apply_smoothing : a boolean
Smooth before resampling. Maps to a command-line argument: %d (position: 5).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
dimension : an integer (int or long)
Dimension of output image. Maps to a command-line argument: %d (position: 1). (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
nn_interp : a boolean
Nn interpolation. Maps to a command-line argument: %d (position: -1). Requires inputs: addvox.
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
output_image : a pathlike object or string representing a file
Output image file. Maps to a command-line argument: %s (position: 3).
output_image : a pathlike object or string representing an existing file
Resampled file.

ThresholdImage

Link to code

Bases: ANTSCommand, CopyHeaderInterface

Wrapped executable: ThresholdImage.

Apply thresholds on images.

Examples

>>> thres = ThresholdImage(dimension=3)
>>> thres.inputs.input_image = 'structural.nii'
>>> thres.inputs.output_image = 'output.nii.gz'
>>> thres.inputs.th_low = 0.5
>>> thres.inputs.th_high = 1.0
>>> thres.inputs.inside_value = 1.0
>>> thres.inputs.outside_value = 0.0
>>> thres.cmdline  #doctest: +ELLIPSIS
'ThresholdImage 3 structural.nii output.nii.gz 0.500000 1.000000 1.000000 0.000000'

>>> thres = ThresholdImage(dimension=3)
>>> thres.inputs.input_image = 'structural.nii'
>>> thres.inputs.output_image = 'output.nii.gz'
>>> thres.inputs.mode = 'Kmeans'
>>> thres.inputs.num_thresholds = 4
>>> thres.cmdline  #doctest: +ELLIPSIS
'ThresholdImage 3 structural.nii output.nii.gz Kmeans 4'
copy_header : a boolean
Copy headers of the original image into the output (corrected) file. (Nipype default value: True)
input_image : a pathlike object or string representing an existing file
Input image file. Maps to a command-line argument: %s (position: 2).
args : a unicode string
Additional parameters to the command. Maps to a command-line argument: %s.
dimension : an integer (int or long)
Dimension of output image. Maps to a command-line argument: %d (position: 1). (Nipype default value: 3)
environ : a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value: {})
input_mask : a pathlike object or string representing an existing file
Input mask for Otsu, Kmeans. Maps to a command-line argument: %s. Requires inputs: num_thresholds.
inside_value : a float
Inside value. Maps to a command-line argument: %f (position: 6). Requires inputs: th_low.
mode : ‘Otsu’ or ‘Kmeans’
Whether to run Otsu / Kmeans thresholding. Maps to a command-line argument: %s (position: 4). Mutually exclusive with inputs: th_low, th_high. Requires inputs: num_thresholds.
num_threads : an integer (int or long)
Number of ITK threads to use. (Nipype default value: 1)
num_thresholds : an integer (int or long)
Number of thresholds. Maps to a command-line argument: %d (position: 5).
output_image : a pathlike object or string representing a file
Output image file. Maps to a command-line argument: %s (position: 3).
outside_value : a float
Outside value. Maps to a command-line argument: %f (position: 7). Requires inputs: th_low.
th_high : a float
Upper threshold. Maps to a command-line argument: %f (position: 5). Mutually exclusive with inputs: mode.
th_low : a float
Lower threshold. Maps to a command-line argument: %f (position: 4). Mutually exclusive with inputs: mode.
output_image : a pathlike object or string representing an existing file
Resampled file.