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

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