Top Description Fields Constructors Methods
org.apache.commons.math3.stat.correlation

public Class StorelessCovariance

extends Covariance
Class Inheritance
Imports
org.apache.commons.math3.exception.DimensionMismatchException, .MathUnsupportedOperationException, .NumberIsTooSmallException, org.apache.commons.math3.linear.MatrixUtils, .RealMatrix
Covariance implementation that does not require input data to be stored in memory. The size of the covariance matrix is specified in the constructor. Specific elements of the matrix are incrementally updated with calls to incrementRow() or increment Covariance().

This class is based on a paper written by Philippe Pébay: Formulas for Robust, One-Pass Parallel Computation of Covariances and Arbitrary-Order Statistical Moments, 2008, Technical Report SAND2008-6212, Sandia National Laboratories.

Note

the underlying covariance matrix is symmetric, thus only the upper triangular part of the matrix is stored and updated each increment.

Since
3.0

Field Summary

Modifier and TypeField and Description
private StorelessBivariateCovariance[]
covMatrix

the square covariance matrix (upper triangular part)

private int
dimension

dimension of the square covariance matrix

Constructor Summary

AccessConstructor and Description
public
StorelessCovariance(final int
the dimension of the square covariance matrix
dim)

Create a bias corrected covariance matrix with a given dimension.

public
StorelessCovariance(final int
the dimension of the covariance matrix
dim, final boolean
if true the covariance estimate is corrected for bias, i.e. n-1 in the denominator, otherwise there is no bias correction, i.e. n in the denominator.
biasCorrected)

Create a covariance matrix with a given number of rows and columns and the indicated bias correction.

Method Summary

Modifier and TypeMethod and Description
public void
append(StorelessCovariance
externally computed StorelessCovariance to add to this
sc)

Appends sc to this, effectively aggregating the computations in sc with this.

public double

Returns:

the covariance of the given element
getCovariance(final int
row index in the covariance matrix
xIndex, final int
column index in the covariance matrix
yIndex)

Get the covariance for an individual element of the covariance matrix.

public RealMatrix
getCovarianceMatrix()

Overrides org.apache.commons.math3.stat.correlation.Covariance.getCovarianceMatrix.

Returns the covariance matrix

public double[][]

Returns:

a two-dimensional double array of covariance values
getData()

Return the covariance matrix as two-dimensional array.

private StorelessBivariateCovariance

Returns:

the StorelessBivariateCovariance element at the given index
getElement(final int
the row index
i, final int
the column index
j)

Gets the element at index (i, j) from the covariance matrix

public int

Returns:

nothing as this implementation always throws a MathUnsupportedOperationException
getN()

Overrides org.apache.commons.math3.stat.correlation.Covariance.getN.

This Covariance method is not supported by a StorelessCovariance, since the number of bivariate observations does not have to be the same for different pairs of covariates - i.e., N as defined in Covariance#getN() is undefined.

public void
increment(final double[]
array representing one row of data.
data)

Increment the covariance matrix with one row of data.

private int

Returns:

the corresponding index in the matrix array
indexOf(final int
the row index
i, final int
the column index
j)

Returns the index (i, j) translated into the one-dimensional array used to store the upper triangular part of the symmetric covariance matrix.

private void
initializeMatrix(final boolean
if the covariance estimate shall be corrected for bias
biasCorrected)

Initialize the internal two-dimensional array of StorelessBivariateCovariance instances.

private void
setElement(final int
the row index
i, final int
the column index
j, final StorelessBivariateCovariance
the StorelessBivariateCovariance element to be set
cov)

Sets the covariance element at index (i, j) in the covariance matrix

Inherited from org.apache.commons.math3.stat.correlation.Covariance:
computeCovarianceMatrixcomputeCovarianceMatrixcomputeCovarianceMatrixcomputeCovarianceMatrixcovariancecovariance

Field Detail

covMatrixback to summary
private StorelessBivariateCovariance[] covMatrix

the square covariance matrix (upper triangular part)

dimensionback to summary
private int dimension

dimension of the square covariance matrix

Constructor Detail

StorelessCovarianceback to summary
public StorelessCovariance(final int dim)

Create a bias corrected covariance matrix with a given dimension.

Parameters
dim:int

the dimension of the square covariance matrix

StorelessCovarianceback to summary
public StorelessCovariance(final int dim, final boolean biasCorrected)

Create a covariance matrix with a given number of rows and columns and the indicated bias correction.

Parameters
dim:int

the dimension of the covariance matrix

biasCorrected:boolean

if true the covariance estimate is corrected for bias, i.e. n-1 in the denominator, otherwise there is no bias correction, i.e. n in the denominator.

Method Detail

appendback to summary
public void append(StorelessCovariance sc) throws DimensionMismatchException

Appends sc to this, effectively aggregating the computations in sc with this. After invoking this method, covariances returned should be close to what would have been obtained by performing all of the increment(double[]) operations in sc directly on this.

Parameters
sc:StorelessCovariance

externally computed StorelessCovariance to add to this

Exceptions
DimensionMismatchException:
if the dimension of sc does not match this
Since
3.3
getCovarianceback to summary
public double getCovariance(final int xIndex, final int yIndex) throws NumberIsTooSmallException

Get the covariance for an individual element of the covariance matrix.

Parameters
xIndex:int

row index in the covariance matrix

yIndex:int

column index in the covariance matrix

Returns:double

the covariance of the given element

Exceptions
NumberIsTooSmallException:
if the number of observations in the cell is < 2
getCovarianceMatrixback to summary
public RealMatrix getCovarianceMatrix() throws NumberIsTooSmallException

Overrides org.apache.commons.math3.stat.correlation.Covariance.getCovarianceMatrix.

Doc from org.apache.commons.math3.stat.correlation.Covariance.getCovarianceMatrix.

Returns the covariance matrix

Returns:RealMatrix

covariance matrix

Annotations
@Override
Exceptions
NumberIsTooSmallException:
if the number of observations in a cell is < 2
getDataback to summary
public double[][] getData() throws NumberIsTooSmallException

Return the covariance matrix as two-dimensional array.

Returns:double[][]

a two-dimensional double array of covariance values

Exceptions
NumberIsTooSmallException:
if the number of observations for a cell is < 2
getElementback to summary
private StorelessBivariateCovariance getElement(final int i, final int j)

Gets the element at index (i, j) from the covariance matrix

Parameters
i:int

the row index

j:int

the column index

Returns:StorelessBivariateCovariance

the StorelessBivariateCovariance element at the given index

getNback to summary
public int getN() throws MathUnsupportedOperationException

Overrides org.apache.commons.math3.stat.correlation.Covariance.getN.

This Covariance method is not supported by a StorelessCovariance, since the number of bivariate observations does not have to be the same for different pairs of covariates - i.e., N as defined in Covariance#getN() is undefined.

Returns:int

nothing as this implementation always throws a MathUnsupportedOperationException

Annotations
@Override
Exceptions
MathUnsupportedOperationException:
in all cases
incrementback to summary
public void increment(final double[] data) throws DimensionMismatchException

Increment the covariance matrix with one row of data.

Parameters
data:double[]

array representing one row of data.

Exceptions
DimensionMismatchException:
if the length of rowData does not match with the covariance matrix
indexOfback to summary
private int indexOf(final int i, final int j)

Returns the index (i, j) translated into the one-dimensional array used to store the upper triangular part of the symmetric covariance matrix.

Parameters
i:int

the row index

j:int

the column index

Returns:int

the corresponding index in the matrix array

initializeMatrixback to summary
private void initializeMatrix(final boolean biasCorrected)

Initialize the internal two-dimensional array of StorelessBivariateCovariance instances.

Parameters
biasCorrected:boolean

if the covariance estimate shall be corrected for bias

setElementback to summary
private void setElement(final int i, final int j, final StorelessBivariateCovariance cov)

Sets the covariance element at index (i, j) in the covariance matrix

Parameters
i:int

the row index

j:int

the column index

cov:StorelessBivariateCovariance

the StorelessBivariateCovariance element to be set