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 java.lang.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
  Version:
    $Id: Covariance.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private RealMatrix` | `covarianceMatrix` covariance matrix
    `private int` | `n` Number of observations (length of covariate vectors)

  - ### Constructor Summary

    Constructors
    Constructor and 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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `checkSufficientData(RealMatrix matrix)` Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows.
    `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`

- - ### Field Detail

    - #### covarianceMatrix

          private final RealMatrix covarianceMatrix

      covariance matrix

    - #### n

          private final int n

      Number of observations (length of covariate vectors)

  - ### Constructor Detail

    - #### Covariance

          public Covariance()

      Create a Covariance with no data

    - #### Covariance

          public Covariance(double[][] data,
                    boolean biasCorrected)
                     throws MathIllegalArgumentException

      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 two columns 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 two columns.

    - #### Covariance

          public Covariance(double[][] data)
                     throws MathIllegalArgumentException

      Create a Covariance matrix from a rectangular array whose columns represent covariates.

      The input array must be rectangular with at least two columns 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 two columns.

    - #### 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 two columns 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 two columns

    - #### Covariance

          public Covariance(RealMatrix matrix)
                     throws MathIllegalArgumentException

      Create a covariance matrix from a matrix whose columns represent covariates.

      The matrix must have at least two columns and two rows

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

  - ### Method Detail

    - #### 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 two columns 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 two columns and two rows)
      Returns:
        covariance matrix
      Throws:
        `MathIllegalArgumentException` - if matrix does not contain sufficient data
      See Also:
        `Covariance(org.apache.commons.math3.linear.RealMatrix)`

    - #### computeCovarianceMatrix

          protected RealMatrix computeCovarianceMatrix(double[][] data,
                                           boolean biasCorrected)
                                                throws MathIllegalArgumentException

      Compute a covariance matrix from a rectangular array whose columns represent covariates.
      Parameters:
        `data` - input array (must have at least two columns 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

    - #### computeCovarianceMatrix

          protected RealMatrix computeCovarianceMatrix(double[][] data)
                                                throws MathIllegalArgumentException

      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 two columns and two rows)
      Returns:
        covariance matrix
      Throws:
        `MathIllegalArgumentException` - if the data array does not contain sufficient data
      See Also:
        `Covariance(org.apache.commons.math3.linear.RealMatrix)`

    - #### 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

    - #### checkSufficientData

          private void checkSufficientData(RealMatrix matrix)
                                    throws MathIllegalArgumentException

      Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows.
      Parameters:
        `matrix` - matrix to check
      Throws:
        `MathIllegalArgumentException` - if the matrix does not contain sufficient data to compute covariance

Copyright (c) 2003-2013 Apache Software Foundation