Package elki.math.linearalgebra

Class CovarianceMatrix

  • public class CovarianceMatrix
extends java.lang.Object
    Class for computing covariance matrixes using stable mean and variance computations.

    This class encapsulates the mathematical aspects of computing this matrix.

    See DatabaseUtil for easier to use APIs.

    For use in algorithms, it is more appropriate to use StandardCovarianceMatrixBuilder since this class can be overridden with a stabilized covariance matrix builder!

    Since:
    0.4.0
    Author:
    Erich Schubert

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) double[][] elements
      The covariance matrix.
      static java.lang.String ERR_TOO_LITTLE_WEIGHT
      Error message reported when too little data (weight <= 1) in matrix.
      (package private) double[] mean
      The means.
      (package private) double[] nmea
      Temporary storage, to avoid reallocations.
      protected double wsum
      The current weight.

    • Constructor Summary

      Constructors 
      Constructor Description
      CovarianceMatrix​(int dim)
      Constructor.

    • Field Detail

      • ERR_TOO_LITTLE_WEIGHT

        public static final java.lang.String ERR_TOO_LITTLE_WEIGHT
        Error message reported when too little data (weight <= 1) in matrix.
        See Also:
        Constant Field Values

      • mean

        double[] mean
        The means.

      • elements

        double[][] elements
        The covariance matrix.

      • nmea

        double[] nmea
        Temporary storage, to avoid reallocations.

      • wsum

        protected double wsum
        The current weight.

    • Constructor Detail

      • CovarianceMatrix

        public CovarianceMatrix​(int dim)
        Constructor.
        Parameters:
        dim - Dimensionality

    • Method Detail

      • getDimensionality

        public int getDimensionality()
        Get the matrix dimensionality.
        Returns:
        Mean length.

      • put

        public void put​(double[] val)
        Add a single value with weight 1.0.
        Parameters:
        val - Value

      • put

        public void put​(double[] val,
                double weight)
        Add data with a given weight.
        Parameters:
        val - data
        weight - weight

      • put

        public void put​(NumberVector val)
        Add a single value with weight 1.0.
        Parameters:
        val - Value

      • put

        public void put​(NumberVector val,
                double weight)
        Add data with a given weight.
        Parameters:
        val - data
        weight - weight

      • getWeight

        public double getWeight()
        Get the weight sum, to test whether the covariance matrix can be materialized.
        Returns:
        Weight sum.

      • getMeanVector

        public double[] getMeanVector()
        Get the mean as vector.
        Returns:
        Mean vector

      • getMeanVector

        public <F extends NumberVector> F getMeanVector​(Relation<? extends F> relation)
        Get the mean as vector.
        Type Parameters:
        F - vector type
        Parameters:
        relation - Data relation
        Returns:
        Mean vector

      • makeSampleMatrix

        public double[][] makeSampleMatrix()
        Obtain the covariance matrix according to the sample statistics: (n-1) degrees of freedom.

        This method duplicates the matrix contents, so it does allow further updates. Use destroyToSampleMatrix() if you do not need further updates.

        Returns:
        New matrix

      • makePopulationMatrix

        public double[][] makePopulationMatrix()
        Obtain the covariance matrix according to the population statistics: n degrees of freedom.

        This method duplicates the matrix contents, so it does allow further updates. Use destroyToPopulationMatrix() if you do not need further updates.

        Returns:
        New matrix

      • destroyToSampleMatrix

        public double[][] destroyToSampleMatrix()
        Obtain the covariance matrix according to the sample statistics: (n-1) degrees of freedom.

        This method doesn't require matrix duplication, but will not allow further updates, the object should be discarded. Use makeSampleMatrix() if you want to perform further updates.

        Returns:
        New matrix

      • destroyToPopulationMatrix

        public double[][] destroyToPopulationMatrix()
        Obtain the covariance matrix according to the population statistics: n degrees of freedom.

        This method doesn't require matrix duplication, but will not allow further updates, the object should be discarded. Use makePopulationMatrix() if you want to perform further updates.

        Returns:
        New matrix

      • reset

        public void reset()
        Reset the covariance matrix.

        This function may be called after a "destroy".

      • make

        public static CovarianceMatrix make​(Relation<? extends NumberVector> relation)
        Static Constructor from a full relation.
        Parameters:
        relation - Relation to use.
        Returns:
        Covariance matrix

      • make

        public static CovarianceMatrix make​(Relation<? extends NumberVector> relation,
                                    DBIDs ids)
        Static Constructor from a full relation.
        Parameters:
        relation - Relation to use.
        ids - IDs to add
        Returns:
        Covariance matrix