Module org.bzdev.math
Package org.bzdev.math.stats

Class CovarianceMatrix

java.lang.Object
org.bzdev.math.stats.CovarianceMatrix
Direct Known Subclasses:
CovarianceMatrix.Population, CovarianceMatrix.Sample
public abstract class CovarianceMatrix extends Object
Covariance matrix. This class provides the covariance matrix for a vector of measurements or random variables measured or evaluated multiple times. The inner classes are subclasses of this class:
  • Sample is used to compute the covariance matrix for the case in which the dataset whose covariance matrix is computed is a representative sample.
  • Population is used to compute the covariance matrix for the case where the dataset represents every case being computed.

For a row vector X of measurements or random values, the covariance matrix Σ is defined by

Σ = E[(X-E[X])(X - E[X])T]
where E[X] is the expectation value of X.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    CovarianceMatrix.Population
    Class to compute the covariance matrix for a total set of values, as opposed to a sample of values.
    static final class 
    CovarianceMatrix.Sample
    Class to compute a sample covariance matrix.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected long
    count
    The number of data vectors used.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    CovarianceMatrix(double[][] arrays, int n)
    Constructor given an array containing the initial data used to compute a covariance matrix.
    protected
    CovarianceMatrix(int n)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(double[] values)
    Add a new vector of values.
    void
    addsComplete()
    Assert that more values will not be added to the covariance-matrix computation.
    protected abstract double
    getCorrection()
    The elements of the variance array that is computed will be scaled by a correction factor.
    double[][]
    getCorrelationMatrix()
    Get the correlation matrix corresponding to this covariance matrix.
    void
    getCorrelationMatrix(double[][] result)
    Get the correlation matrix corresponding to this covariance matrix, storing the result in an array.
    int
    getDimension()
    Get the number of rows and colums for this covariance matrix.
    double[][]
    getMatrix()
    Get the covariance matrix.
    double[]
    getMeans()
    Get the mean values of the variables associated with this covariance matrix.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • count

      protected long count
      The number of data vectors used.

  • Constructor Details

    • CovarianceMatrix

      protected CovarianceMatrix(int n)
      Constructor. The method add(double[]) must be called repeatedly to provide the dataset used to compute the covariance matrix and mean array.
      Parameters:
      n - the number of variables

    • CovarianceMatrix

      protected CovarianceMatrix(double[][] arrays, int n) throws IllegalArgumentException
      Constructor given an array containing the initial data used to compute a covariance matrix. Note: the initial dataset will be used to estimate the mean for purposes of reducing floating-point errors. More dataset can be added using the add(double[]) method.
      Parameters:
      arrays - an array, each component of which is an array containing the values for n variables
      n - the number of variables
      Throws:
      IllegalArgumentException - the array length was incorrect

  • Method Details

    • getCorrection

      protected abstract double getCorrection()
      The elements of the variance array that is computed will be scaled by a correction factor. This factor should be 1.0 when the dataset represents a total population. For a sample of a population, the factor is m/(m-1) where m is the sample size.

      The subclasses CovarianceMatrix.Sample and CovarianceMatrix.Population provide suitable implementations of this method for those cases.

      Returns:
      the correction factor; Double.NaN if the factor cannot be computed due to too few entries

    • add

      public void add(double[] values) throws IllegalArgumentException, IllegalStateException
      Add a new vector of values. The vector's length must be at least n, where n is the number of variables.
      Parameters:
      values - a vector of values (the first n entries will be used)
      Throws:
      IllegalStateException - method may no longer be called
      IllegalArgumentException - the array length was incorrect

    • addsComplete

      public void addsComplete()
      Assert that more values will not be added to the covariance-matrix computation. Calling this method results in the method getMatrix() returning the same array repeatedly instead of a fresh copy.
      See Also:

    • getMatrix

      public double[][] getMatrix() throws IllegalArgumentException, IllegalStateException
      Get the covariance matrix. The value returned must not be modified when this method is called after addsComplete() has been called.
      Returns:
      the covariance matrix
      Throws:
      IllegalStateException - no data is yet available
      IllegalArgumentException - the array length was incorrect

    • getCorrelationMatrix

      public void getCorrelationMatrix(double[][] result)
      Get the correlation matrix corresponding to this covariance matrix, storing the result in an array.
      Parameters:
      result - an array to store the result.

    • getCorrelationMatrix

      public double[][] getCorrelationMatrix()
      Get the correlation matrix corresponding to this covariance matrix. Each call will produce a new matrix.
      Returns:
      the correlation matrix

    • getMeans

      public double[] getMeans() throws IllegalStateException
      Get the mean values of the variables associated with this covariance matrix. The value returned must not be modified when this method is called after addsComplete() has been called.
      Returns:
      the mean values
      Throws:
      IllegalStateException - no data is yet available

    • getDimension

      public int getDimension()
      Get the number of rows and colums for this covariance matrix. The covariance matrix is an N by N matrix, where N is the number of variables associated with the matrix. N is set when the constructor is called.
      Returns:
      the number of rows and columns