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

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 one column 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,
                  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

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

checkSufficientData

private void checkSufficientData(RealMatrix matrix)
                          throws MathIllegalArgumentException

Throws MathIllegalArgumentException if the matrix does not have at least one column and two rows.

Parameters:

matrix - matrix to check

Throws:

MathIllegalArgumentException - if the matrix does not contain sufficient data to compute covariance