Class StorelessCovariance
java.lang.Object
org.apache.commons.math3.stat.correlation.Covariance
org.apache.commons.math3.stat.correlation.StorelessCovariance
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
FieldsModifier and TypeFieldDescriptionprivate StorelessBivariateCovariance[]
the square covariance matrix (upper triangular part)private int
dimension of the square covariance matrix -
Constructor Summary
ConstructorsConstructorDescriptionStorelessCovariance
(int dim) Create a bias corrected covariance matrix with a given dimension.StorelessCovariance
(int dim, boolean biasCorrected) Create a covariance matrix with a given number of rows and columns and the indicated bias correction. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Appendssc
to this, effectively aggregating the computations insc
with this.double
getCovariance
(int xIndex, int yIndex) Get the covariance for an individual element of the covariance matrix.Returns the covariance matrixdouble[][]
getData()
Return the covariance matrix as two-dimensional array.private StorelessBivariateCovariance
getElement
(int i, int j) Gets the element at index (i, j) from the covariance matrixint
getN()
ThisCovariance
method is not supported by aStorelessCovariance
, since the number of bivariate observations does not have to be the same for different pairs of covariates - i.e., N as defined inCovariance.getN()
is undefined.void
increment
(double[] data) Increment the covariance matrix with one row of data.private int
indexOf
(int i, 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.private void
initializeMatrix
(boolean biasCorrected) Initialize the internal two-dimensional array ofStorelessBivariateCovariance
instances.private void
setElement
(int i, int j, StorelessBivariateCovariance cov) Sets the covariance element at index (i, j) in the covariance matrixMethods inherited from class org.apache.commons.math3.stat.correlation.Covariance
computeCovarianceMatrix, computeCovarianceMatrix, computeCovarianceMatrix, computeCovarianceMatrix, covariance, covariance
-
Field Details
-
covMatrix
the square covariance matrix (upper triangular part) -
dimension
private int dimensiondimension of the square covariance matrix
-
-
Constructor Details
-
StorelessCovariance
public StorelessCovariance(int dim) Create a bias corrected covariance matrix with a given dimension.- Parameters:
dim
- the dimension of the square covariance matrix
-
StorelessCovariance
public StorelessCovariance(int dim, boolean biasCorrected) Create a covariance matrix with a given number of rows and columns and the indicated bias correction.- Parameters:
dim
- the dimension of the covariance matrixbiasCorrected
- iftrue
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 Details
-
initializeMatrix
private void initializeMatrix(boolean biasCorrected) Initialize the internal two-dimensional array ofStorelessBivariateCovariance
instances.- Parameters:
biasCorrected
- if the covariance estimate shall be corrected for bias
-
indexOf
private int indexOf(int i, 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
- the row indexj
- the column index- Returns:
- the corresponding index in the matrix array
-
getElement
Gets the element at index (i, j) from the covariance matrix- Parameters:
i
- the row indexj
- the column index- Returns:
- the
StorelessBivariateCovariance
element at the given index
-
setElement
Sets the covariance element at index (i, j) in the covariance matrix- Parameters:
i
- the row indexj
- the column indexcov
- theStorelessBivariateCovariance
element to be set
-
getCovariance
Get the covariance for an individual element of the covariance matrix.- Parameters:
xIndex
- row index in the covariance matrixyIndex
- column index in the covariance matrix- Returns:
- the covariance of the given element
- Throws:
NumberIsTooSmallException
- if the number of observations in the cell is < 2
-
increment
Increment the covariance matrix with one row of data.- Parameters:
data
- array representing one row of data.- Throws:
DimensionMismatchException
- if the length ofrowData
does not match with the covariance matrix
-
append
Appendssc
to this, effectively aggregating the computations insc
with this. After invoking this method, covariances returned should be close to what would have been obtained by performing all of theincrement(double[])
operations insc
directly on this.- Parameters:
sc
- externally computed StorelessCovariance to add to this- Throws:
DimensionMismatchException
- if the dimension of sc does not match this- Since:
- 3.3
-
getCovarianceMatrix
Returns the covariance matrix- Overrides:
getCovarianceMatrix
in classCovariance
- Returns:
- covariance matrix
- Throws:
NumberIsTooSmallException
- if the number of observations in a cell is < 2
-
getData
Return the covariance matrix as two-dimensional array.- Returns:
- a two-dimensional double array of covariance values
- Throws:
NumberIsTooSmallException
- if the number of observations for a cell is < 2
-
getN
ThisCovariance
method is not supported by aStorelessCovariance
, since the number of bivariate observations does not have to be the same for different pairs of covariates - i.e., N as defined inCovariance.getN()
is undefined.- Overrides:
getN
in classCovariance
- Returns:
- nothing as this implementation always throws a
MathUnsupportedOperationException
- Throws:
MathUnsupportedOperationException
- in all cases
-