## org.apache.commons.math.stat.correlation
Class Covariance

    java.lang.Object
      org.apache.commons.math.stat.correlation.Covariance

    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:
  $Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $

Field Summary
`private RealMatrix` `covarianceMatrix` covariance matrix
`private int` `n` Number of observations (length of covariate vectors)

Constructor Summary
`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
`private void` `checkSufficientData(RealMatrix matrix)` Throws IllegalArgumentException of the matrix does not have at least two columns and two rows
`protected RealMatrix` `computeCovarianceMatrix(double[][] data)` Create a covariance matrix from a rectangual 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)

  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:
    `java.lang.IllegalArgumentException` - if the input data array is not rectangular with at least two rows and two columns.

### Covariance

    public Covariance(double[][] data)

  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:
    `java.lang.IllegalArgumentException` - if the input data array is not rectangular with at least two rows and two columns.

### Covariance

    public Covariance(RealMatrix matrix,
                      boolean biasCorrected)

  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:
    `java.lang.IllegalArgumentException` - if the input matrix does not have at least two rows and two columns

### Covariance

    public Covariance(RealMatrix matrix)

  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:
    `java.lang.IllegalArgumentException` - 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)

  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

### computeCovarianceMatrix

    protected RealMatrix computeCovarianceMatrix(RealMatrix matrix)

  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
  See Also:
    `Covariance(org.apache.commons.math.linear.RealMatrix)`

### computeCovarianceMatrix

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

  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

### computeCovarianceMatrix

    protected RealMatrix computeCovarianceMatrix(double[][] data)

  Create a covariance matrix from a rectangual 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
  See Also:
    `Covariance(org.apache.commons.math.linear.RealMatrix)`

### covariance

    public double covariance(double[] xArray,
                             double[] yArray,
                             boolean biasCorrected)
                      throws java.lang.IllegalArgumentException

  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:
    `java.lang.IllegalArgumentException` - if the arrays lengths do not match or there is insufficient data

### covariance

    public double covariance(double[] xArray,
                             double[] yArray)
                      throws java.lang.IllegalArgumentException

  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:
    `java.lang.IllegalArgumentException` - if the arrays lengths do not match or there is insufficient data

### checkSufficientData

    private void checkSufficientData(RealMatrix matrix)

  Throws IllegalArgumentException of the matrix does not have at least two columns and two rows

  Parameters:
    `matrix` - matrix to check

Copyright (c) 2003-2011 Apache Software Foundation