Package org.apache.commons.math3.stat.correlation

Class Covariance

java.lang.Object
org.apache.commons.math3.stat.correlation.Covariance
Direct Known Subclasses:
StorelessCovariance
public class Covariance extends Object
Computes covariances for pairs of arrays or columns of a matrix.

The constructors that take RealMatrix or double[][] arguments generate covariance matrices. The columns of the input matrices are assumed to represent variable values.

The constructor argument biasCorrected determines whether or not computed covariances are bias-corrected.

Unbiased covariances are given by the formula

cov(X, Y) = Σ[(xi - E(X))(yi - E(Y))] / (n - 1) where E(X) is the mean of X and E(Y) is the mean of the Y values.

Non-bias-corrected estimates use n in place of n - 1

Since:
2.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    Covariance()
    Create a Covariance with no data
    Covariance(double[][] data)
    Create a Covariance matrix from a rectangular array whose columns represent covariates.
    Covariance(double[][] data, boolean biasCorrected)
    Create a Covariance matrix from a rectangular array whose columns represent covariates.
    Covariance(RealMatrix matrix)
    Create a covariance matrix from a matrix whose columns represent covariates.
    Covariance(RealMatrix matrix, boolean biasCorrected)
    Create a covariance matrix from a matrix whose columns represent covariates.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected RealMatrix
    computeCovarianceMatrix(double[][] data)
    Create a covariance matrix from a rectangular array whose columns represent covariates.
    protected RealMatrix
    computeCovarianceMatrix(double[][] data, boolean biasCorrected)
    Compute a covariance matrix from a rectangular array whose columns represent covariates.
    protected RealMatrix
    computeCovarianceMatrix(RealMatrix matrix)
    Create a covariance matrix from a matrix whose columns represent covariates.
    protected RealMatrix
    computeCovarianceMatrix(RealMatrix matrix, boolean biasCorrected)
    Compute a covariance matrix from a matrix whose columns represent covariates.
    double
    covariance(double[] xArray, double[] yArray)
    Computes the covariance between the two arrays, using the bias-corrected formula.
    double
    covariance(double[] xArray, double[] yArray, boolean biasCorrected)
    Computes the covariance between the two arrays.
    RealMatrix
    getCovarianceMatrix()
    Returns the covariance matrix
    int
    getN()
    Returns the number of observations (length of covariate vectors)

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Covariance

      public Covariance()
      Create a Covariance with no data

    • Covariance

      public Covariance(double[][] data, boolean biasCorrected) throws MathIllegalArgumentException, NotStrictlyPositiveException
      Create a Covariance matrix from a rectangular array whose columns represent covariates.

      The biasCorrected parameter determines whether or not covariance estimates are bias-corrected.

      The input array must be rectangular with at least one column and two rows.

      Parameters:
      data - rectangular array with columns representing covariates
      biasCorrected - true means covariances are bias-corrected
      Throws:
      MathIllegalArgumentException - if the input data array is not rectangular with at least two rows and one column.
      NotStrictlyPositiveException - if the input data array is not rectangular with at least one row and one column.

    • Covariance

      public Covariance(double[][] data) throws MathIllegalArgumentException, NotStrictlyPositiveException
      Create a Covariance matrix from a rectangular array whose columns represent covariates.

      The input array must be rectangular with at least one column and two rows

      Parameters:
      data - rectangular array with columns representing covariates
      Throws:
      MathIllegalArgumentException - if the input data array is not rectangular with at least two rows and one column.
      NotStrictlyPositiveException - if the input data array is not rectangular with at least one row and one column.

    • Covariance

      public Covariance(RealMatrix matrix, boolean biasCorrected) throws MathIllegalArgumentException
      Create a covariance matrix from a matrix whose columns represent covariates.

      The biasCorrected parameter determines whether or not covariance estimates are bias-corrected.

      The matrix must have at least one column and two rows

      Parameters:
      matrix - matrix with columns representing covariates
      biasCorrected - true means covariances are bias-corrected
      Throws:
      MathIllegalArgumentException - if the input matrix does not have at least two rows and one column

    • Covariance

      public Covariance(RealMatrix matrix) throws MathIllegalArgumentException
      Create a covariance matrix from a matrix whose columns represent covariates.

      The matrix must have at least one column and two rows

      Parameters:
      matrix - matrix with columns representing covariates
      Throws:
      MathIllegalArgumentException - if the input matrix does not have at least two rows and one column

  • Method Details

    • getCovarianceMatrix

      public RealMatrix getCovarianceMatrix()
      Returns the covariance matrix
      Returns:
      covariance matrix

    • getN

      public int getN()
      Returns the number of observations (length of covariate vectors)
      Returns:
      number of observations

    • computeCovarianceMatrix

      protected RealMatrix computeCovarianceMatrix(RealMatrix matrix, boolean biasCorrected) throws MathIllegalArgumentException
      Compute a covariance matrix from a matrix whose columns represent covariates.
      Parameters:
      matrix - input matrix (must have at least one column and two rows)
      biasCorrected - determines whether or not covariance estimates are bias-corrected
      Returns:
      covariance matrix
      Throws:
      MathIllegalArgumentException - if the matrix does not contain sufficient data

    • computeCovarianceMatrix

      protected RealMatrix computeCovarianceMatrix(RealMatrix matrix) throws MathIllegalArgumentException
      Create a covariance matrix from a matrix whose columns represent covariates. Covariances are computed using the bias-corrected formula.
      Parameters:
      matrix - input matrix (must have at least one column and two rows)
      Returns:
      covariance matrix
      Throws:
      MathIllegalArgumentException - if matrix does not contain sufficient data
      See Also:

    • computeCovarianceMatrix

      protected RealMatrix computeCovarianceMatrix(double[][] data, boolean biasCorrected) throws MathIllegalArgumentException, NotStrictlyPositiveException
      Compute a covariance matrix from a rectangular array whose columns represent covariates.
      Parameters:
      data - input array (must have at least one column and two rows)
      biasCorrected - determines whether or not covariance estimates are bias-corrected
      Returns:
      covariance matrix
      Throws:
      MathIllegalArgumentException - if the data array does not contain sufficient data
      NotStrictlyPositiveException - if the input data array is not rectangular with at least one row and one column.

    • computeCovarianceMatrix

      protected RealMatrix computeCovarianceMatrix(double[][] data) throws MathIllegalArgumentException, NotStrictlyPositiveException
      Create a covariance matrix from a rectangular array whose columns represent covariates. Covariances are computed using the bias-corrected formula.
      Parameters:
      data - input array (must have at least one column and two rows)
      Returns:
      covariance matrix
      Throws:
      MathIllegalArgumentException - if the data array does not contain sufficient data
      NotStrictlyPositiveException - if the input data array is not rectangular with at least one row and one column.
      See Also:

    • covariance

      public double covariance(double[] xArray, double[] yArray, boolean biasCorrected) throws MathIllegalArgumentException
      Computes the covariance between the two arrays.

      Array lengths must match and the common length must be at least 2.

      Parameters:
      xArray - first data array
      yArray - second data array
      biasCorrected - if true, returned value will be bias-corrected
      Returns:
      returns the covariance for the two arrays
      Throws:
      MathIllegalArgumentException - if the arrays lengths do not match or there is insufficient data

    • covariance

      public double covariance(double[] xArray, double[] yArray) throws MathIllegalArgumentException
      Computes the covariance between the two arrays, using the bias-corrected formula.

      Array lengths must match and the common length must be at least 2.

      Parameters:
      xArray - first data array
      yArray - second data array
      Returns:
      returns the covariance for the two arrays
      Throws:
      MathIllegalArgumentException - if the arrays lengths do not match or there is insufficient data