# 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, rng=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, rng=None)

    > Creates a new histogram registration object.

    Parameters:
      from_img nipy-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).

      interp str

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

      smooth float

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

        rngNone `numpy.random.Generator`

          Random number generator.

  eval(T)

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

    Parameters:
      T Transform

        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:
      T Transform

        Transform object implementing `apply` method

      epsilon float

        Step size for finite differences in units of the transformation parameters

    Returns:
      g ndarray

        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:
      T Transform

        Transform object implementing `apply` method

      epsilon float

        Step size for finite differences in units of the transformation parameters

      diag bool

        If True, approximate the Hessian by a diagonal matrix.

    Returns:
      H ndarray

        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:
      T object

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

      args tuple

        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:
      s ndarray

        Array of similarity values

      p ndarray

        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:
      T object 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.

      optimizer str

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

      **kwargs dict

        keyword arguments to pass to optimizer

    Returns:
      T object

        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:
      spacing sequence (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

      corner sequence (3,) of positive integers

        Bounding box origin in voxel coordinates

      size sequence (3,) of positive integers

        Desired bounding box size

      npoints positive 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:
    x ndarray

      The input array

    bins number

      Desired number of bins

    mask ndarray, tuple or slice

      Anything such that x[mask] is an array.

  Returns:
    y ndarray

      Clamped array, masked items are assigned -1

    bins number

      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:
    data ndarray or sequence

      Data image to subsample

    npoints number

      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:
    msk ndarray

      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