Module imagingbook.common
Package imagingbook.common.math

Class MahalanobisDistance

java.lang.Object
imagingbook.common.math.MahalanobisDistance
public class MahalanobisDistance extends Object

This class implements the Mahalanobis distance using the Apache Commons Math library. No statistical bias correction is used. See the Appendix G (Sections G.2-G.3) of [1] for additional details and examples.

[1] W. Burger, M.J. Burge, Digital Image Processing – An Algorithmic Introduction, 3rd ed, Springer (2022).

Version:
2023/01/01

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    DefaultAbsolutePositivityThreshold
    Tolerance used for validating positvity in the Cholesky decomposition.
    static final double
    DefaultMinimumDiagonalValue
    The default minimum diagonal value used to condition the covariance matrix.
    static final double
    DefaultRelativeSymmetryThreshold
    Tolerance used for validating symmetry in the Cholesky decomposition.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MahalanobisDistance(double[][] cov)
    Constructor, creates a new MahalanobisDistance instance from the m x m covariance matrix and the m-dimensional mean vector of a distribution of m-dimensional data.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    distance(double[] a, double[] b)
    Returns the Mahalanobis distance between the given points.
    double
    distance2(double[] a, double[] b)
    Returns the squared Mahalanobis distance between the given points a, b: d^2(a,b) = (a-b)^T .
    static MahalanobisDistance
    fromSamples(double[][] samples)
    Creates a new MahalanobisDistance instance from an array of m-dimensional samples, e.g., samples = {{x1,y1}, {x2,y2},...,{xn,yn}} for a vector of n two-dimensional samples.
    static MahalanobisDistance
    fromSamples(double[][] samples, double minDiagVal)
    Creates a new MahalanobisDistance instance from an array of m-dimensional samples, e.g.
    double[][]
    getCovarianceMatrix()
    Returns the covariance matrix used for distance calculations.
    int
    getDimension()
    Returns the sample dimension (M) for this instance.
    double[][]
    getInverseCovarianceMatrix()
    Returns the inverse of the conditioned covariance matrix.
    double[][]
    getWhiteningTransformation()
    Returns the 'root' (U) of the inverse covariance matrix S^{-1}, such that S^{-1} = U^T .
    double[][]
    getWhiteningTransformation(double relativeSymmetryThreshold, double absolutePositivityThreshold)
    Returns the 'root' (U) of the inverse covariance matrix S^{-1}, such that S^{-1} = U^T .

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • MahalanobisDistance

      public MahalanobisDistance(double[][] cov)
      Constructor, creates a new MahalanobisDistance instance from the m x m covariance matrix and the m-dimensional mean vector of a distribution of m-dimensional data. The covariance matrix is assumed to be properly conditioned, i.e., has all-positive diagonal values.
      Parameters:
      cov - the covariance matrix of size m x m

  • Method Details

    • fromSamples

      public static MahalanobisDistance fromSamples(double[][] samples)
      Creates a new MahalanobisDistance instance from an array of m-dimensional samples, e.g., samples = {{x1,y1}, {x2,y2},...,{xn,yn}} for a vector of n two-dimensional samples. Uses DefaultMinimumDiagonalValue to condition the covariance matrix.
      Parameters:
      samples - a sequence of m-dimensional samples, i.e., samples[k][i] represents the i-th component of the k-th sample
      Returns:
      a MahalanobisDistance instance

    • fromSamples

      public static MahalanobisDistance fromSamples(double[][] samples, double minDiagVal)
      Creates a new MahalanobisDistance instance from an array of m-dimensional samples, e.g. samples = {{x1,y1}, {x2,y2},...,{xn,yn}} for a vector of two-dimensional samples (n = 2).
      Parameters:
      samples - a vector of length n with m-dimensional samples, i.e., samples[k][i] represents the i-th component of the k-th sample
      minDiagVal - the minimum diagonal value used to condition the covariance matrix to avoid singularity (see DefaultMinimumDiagonalValue)
      Returns:
      a MahalanobisDistance instance

    • getDimension

      public int getDimension()
      Returns the sample dimension (M) for this instance.
      Returns:
      the sample dimension

    • getCovarianceMatrix

      public double[][] getCovarianceMatrix()
      Returns the covariance matrix used for distance calculations.
      Returns:
      the conditioned covariance matrix

    • getInverseCovarianceMatrix

      public double[][] getInverseCovarianceMatrix()
      Returns the inverse of the conditioned covariance matrix.
      Returns:
      the inverse of the conditioned covariance matrix

    • getWhiteningTransformation

      public double[][] getWhiteningTransformation()
      Returns the 'root' (U) of the inverse covariance matrix S^{-1}, such that S^{-1} = U^T . U This matrix can be used to pre-transform the original sample vectors X (by X → U . X) to a space where distance (in the Mahalanobis sense) can be measured with the usual Euclidean norm. The matrix U is invertible in case the reverse transformation is required.
      Returns:
      the m x m matrix for pre-transforming the original (m-dimensional) sample vectors

    • getWhiteningTransformation

      public double[][] getWhiteningTransformation(double relativeSymmetryThreshold, double absolutePositivityThreshold)
      Returns the 'root' (U) of the inverse covariance matrix S^{-1}, such that S^{-1} = U^T . U This matrix can be * used to pre-transform the original sample vectors X (by X → U . X) to a space where distance (in the * Mahalanobis sense) can be measured with the usual Euclidean norm. The matrix U is invertible in case the reverse * transformation is required.
      Parameters:
      relativeSymmetryThreshold - maximum deviation from symmetry (see DefaultRelativeSymmetryThreshold)
      absolutePositivityThreshold - maximum deviation from positivity (see DefaultAbsolutePositivityThreshold)
      Returns:

    • distance

      public double distance(double[] a, double[] b)
      Returns the Mahalanobis distance between the given points.
      Parameters:
      a - first point
      b - second point
      Returns:
      the Mahalanobis distance

    • distance2

      public double distance2(double[] a, double[] b)
      Returns the squared Mahalanobis distance between the given points a, b: d^2(a,b) = (a-b)^T . S^{-1} . (a-b)
      Parameters:
      a - first point
      b - second point
      Returns:
      the squared Mahalanobis distance