org.apache.commons.math4.stat.correlation

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

All Methods
Modifier and Type Method and 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 Detail

• #### 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 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 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
Covariance(org.apache.commons.math4.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.
Covariance(org.apache.commons.math4.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