algorithms.registration.histogram_registration

Module: algorithms.registration.histogram_registration

Inheritance diagram for nipy.algorithms.registration.histogram_registration:

Intensity-based image registration

Class

HistogramRegistration

class nipy.algorithms.registration.histogram_registration.HistogramRegistration(from_img, to_img, from_bins=256, to_bins=None, from_mask=None, to_mask=None, similarity='crl1', interp='pv', smooth=0, renormalize=False, dist=None)

Bases: object

A class to represent a generic intensity-based image registration algorithm.

__init__(from_img, to_img, from_bins=256, to_bins=None, from_mask=None, to_mask=None, similarity='crl1', interp='pv', smooth=0, renormalize=False, dist=None)

Creates a new histogram registration object.

Parameters:

from_imgnipy-like image

From image

to_imgnipy-like image

To image

from_binsinteger

Number of histogram bins to represent the from image

to_binsinteger

Number of histogram bins to represent the to image

from_maskarray-like

Mask to apply to the from image

to_maskarray-like

Mask to apply to the to image

similaritystr or callable

Cost-function for assessing image similarity. If a string, one of ‘cc’: correlation coefficient, ‘cr’: correlation ratio, ‘crl1’: L1-norm based correlation ratio, ‘mi’: mutual information, ‘nmi’: normalized mutual information, ‘slr’: supervised log-likelihood ratio. If a callable, it should take a two-dimensional array representing the image joint histogram as an input and return a float.

dist: None or array-like

Joint intensity probability distribution model for use with the ‘slr’ measure. Should be of shape (from_bins, to_bins).

interpstr

Interpolation method. One of ‘pv’: Partial volume, ‘tri’: Trilinear, ‘rand’: Random interpolation. See joint_histogram.c

smoothfloat

Standard deviation in millimeters of an isotropic Gaussian kernel used to smooth the To image. If 0, no smoothing is applied.

eval(T)

Evaluate similarity function given a world-to-world transform.

Parameters:

TTransform

Transform object implementing apply method

eval_gradient(T, epsilon=0.1)

Evaluate the gradient of the similarity function wrt transformation parameters.

The gradient is approximated using central finite differences at the transformation specified by T. The input transformation object T is modified in place unless it has a copy method.

Parameters:

TTransform

Transform object implementing apply method

epsilonfloat

Step size for finite differences in units of the transformation parameters

Returns:

gndarray

Similarity gradient estimate

eval_hessian(T, epsilon=0.1, diag=False)

Evaluate the Hessian of the similarity function wrt transformation parameters.

The Hessian or its diagonal is approximated at the transformation specified by T using central finite differences. The input transformation object T is modified in place unless it has a copy method.

Parameters:

TTransform

Transform object implementing apply method

epsilonfloat

Step size for finite differences in units of the transformation parameters

diagbool

If True, approximate the Hessian by a diagonal matrix.

Returns:

Hndarray

Similarity Hessian matrix estimate

explore(T, *args)

Evaluate the similarity at the transformations specified by sequences of parameter values.

For instance:

s, p = explore(T, (0, [-1,0,1]), (4, [-2.,2]))

Parameters:

Tobject

Transformation around which the similarity function is to be evaluated. It is modified in place unless it has a copy method.

argstuple

Each element of args is a sequence of two elements, where the first element specifies a transformation parameter axis and the second element gives the successive parameter values to evaluate along that axis.

Returns:

sndarray

Array of similarity values

pndarray

Corresponding array of evaluated transformation parameters

property interp

optimize(T, optimizer='powell', **kwargs)

Optimize transform T with respect to similarity measure.

The input object T will change as a result of the optimization.

Parameters:

Tobject or str

An object representing a transformation that should implement apply method and param attribute or property. If a string, one of ‘rigid’, ‘similarity’, or ‘affine’. The corresponding transformation class is then initialized by default.

optimizerstr

Name of optimization function (one of ‘powell’, ‘steepest’, ‘cg’, ‘bfgs’, ‘simplex’)

**kwargsdict

keyword arguments to pass to optimizer

Returns:

Tobject

Locally optimal transformation

set_fov(spacing=None, corner=(0, 0, 0), size=None, npoints=None)

Defines a subset of the from image to restrict joint histogram computation.

Parameters:

spacingsequence (3,) of positive integers

Subsampling of image in voxels, where None (default) results in the subsampling to be automatically adjusted to roughly match a cubic grid with npoints voxels

cornersequence (3,) of positive integers

Bounding box origin in voxel coordinates

sizesequence (3,) of positive integers

Desired bounding box size

npointspositive integer

Desired number of voxels in the bounding box. If a spacing argument is provided, then npoints is ignored.

property similarity

subsample(spacing=None, npoints=None)

Functions

nipy.algorithms.registration.histogram_registration.approx_gradient(f, x, epsilon)

Approximate the gradient of a function using central finite differences

Parameters:

f: callable

The function to differentiate

x: ndarray

Point where the function gradient is to be evaluated

epsilon: float

Stepsize for finite differences

Returns:

g: ndarray

Function gradient at x

nipy.algorithms.registration.histogram_registration.approx_hessian(f, x, epsilon)

Approximate the full Hessian matrix of a function using central finite differences

Parameters:

f: callable

The function to differentiate

x: ndarray

Point where the Hessian is to be evaluated

epsilon: float

Stepsize for finite differences

Returns:

H: ndarray

Hessian matrix at x

nipy.algorithms.registration.histogram_registration.approx_hessian_diag(f, x, epsilon)

Approximate the Hessian diagonal of a function using central finite differences

Parameters:

f: callable

The function to differentiate

x: ndarray

Point where the Hessian is to be evaluated

epsilon: float

Stepsize for finite differences

Returns:

h: ndarray

Diagonal of the Hessian at x

nipy.algorithms.registration.histogram_registration.clamp(x, bins, mask=None)

Clamp array values that fall within a given mask in the range [0..bins-1] and reset masked values to -1.

Parameters:

xndarray

The input array

binsnumber

Desired number of bins

maskndarray, tuple or slice

Anything such that x[mask] is an array.

Returns:

yndarray

Clamped array, masked items are assigned -1

binsnumber

Adjusted number of bins

nipy.algorithms.registration.histogram_registration.ideal_spacing(data, npoints)

Tune spacing factors so that the number of voxels in the output block matches a given number.

Parameters:

datandarray or sequence

Data image to subsample

npointsnumber

Target number of voxels (negative values will be ignored)

Returns:

spacing: ndarray

Spacing factors

nipy.algorithms.registration.histogram_registration.smallest_bounding_box(msk)

Extract the smallest bounding box from a mask

Parameters:

mskndarray

Array of boolean

Returns:

corner: ndarray

3-dimensional coordinates of bounding box corner

size: ndarray

3-dimensional size of bounding box

nipy.algorithms.registration.histogram_registration.smooth_image(data, affine, sigma)

Smooth an image by an isotropic Gaussian filter

Parameters:

data: ndarray

Image data array

affine: ndarray

Image affine transform

sigma: float

Filter standard deviation in mm

Returns:

sdata: ndarray

Smoothed data array