You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by tn...@apache.org on 2012/02/15 20:22:59 UTC
svn commit: r1244667 - in
/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation:
Covariance.java StorelessBivariateCovariance.java StorelessCovariance.java
Author: tn
Date: Wed Feb 15 19:22:59 2012
New Revision: 1244667
URL: http://svn.apache.org/viewvc?rev=1244667&view=rev
Log:
Added javadoc for StorelessCovariance, code cleanup.
JIRA: MATH-449 patch provided by Patrick Meyer
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/Covariance.java
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessBivariateCovariance.java
commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessCovariance.java
Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/Covariance.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/Covariance.java?rev=1244667&r1=1244666&r2=1244667&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/Covariance.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/Covariance.java Wed Feb 15 19:22:59 2012
@@ -145,7 +145,6 @@ public class Covariance {
*
* @return number of observations
*/
-
public int getN() {
return n;
}
Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessBivariateCovariance.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessBivariateCovariance.java?rev=1244667&r1=1244666&r2=1244667&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessBivariateCovariance.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessBivariateCovariance.java Wed Feb 15 19:22:59 2012
@@ -16,56 +16,97 @@
*/
package org.apache.commons.math3.stat.correlation;
-import org.apache.commons.math3.exception.MathIllegalArgumentException;
+import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.util.LocalizedFormats;
/**
* Bivariate Covariance implementation that does not require input data to be
* stored in memory.
*
+ * <p>This class is based on a paper written by Philippe Pébay:
+ * <a href="http://prod.sandia.gov/techlib/access-control.cgi/2008/086212.pdf">
+ * Formulas for Robust, One-Pass Parallel Computation of Covariances and
+ * Arbitrary-Order Statistical Moments</a>, 2008, Technical Report SAND2008-6212,
+ * Sandia National Laboratories. It computes the covariance for a pair of variables.
+ * Use {@link StorelessCovariance} to estimate an entire covariance matrix.</p>
+ *
* @version $Id$
* @since 3.0
*/
public class StorelessBivariateCovariance {
- private double deltaX = 0.0;
-
- private double deltaY = 0.0;
+ /** the mean of variable x */
+ private double meanX;
- private double meanX = 0.0;
+ /** the mean of variable y */
+ private double meanY;
- private double meanY = 0.0;
+ /** number of observations */
+ private double n;
- private double n = 0;
+ /** the running covariance estimate */
+ private double covarianceNumerator;
- private double covarianceNumerator = 0.0;
-
- private boolean biasCorrected = true;
+ /** flag for bias correction */
+ private boolean biasCorrected;
+ /**
+ * Create an empty {@link StorelessBivariateCovariance} instance with
+ * bias correction.
+ */
public StorelessBivariateCovariance() {
+ this(true);
}
- public StorelessBivariateCovariance(boolean biasCorrected) {
- this.biasCorrected = biasCorrected;
+ /**
+ * Create an empty {@link StorelessBivariateCovariance} instance.
+ *
+ * @param biasCorrection if <code>true</code> 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.
+ */
+ public StorelessBivariateCovariance(final boolean biasCorrection) {
+ meanX = meanY = 0.0;
+ n = 0;
+ covarianceNumerator = 0.0;
+ biasCorrected = biasCorrection;
}
- public void increment(double x, double y) {
+ /**
+ * Update the covariance estimation with a pair of variables (x, y).
+ *
+ * @param x the x value
+ * @param y the y value
+ */
+ public void increment(final double x, final double y) {
n++;
- deltaX = x - meanX;
- deltaY = y - meanY;
+ final double deltaX = x - meanX;
+ final double deltaY = y - meanY;
meanX += deltaX / n;
meanY += deltaY / n;
covarianceNumerator += ((n - 1.0) / n) * deltaX * deltaY;
}
+ /**
+ * Returns the number of observations.
+ *
+ * @return number of observations
+ */
public double getN() {
return n;
}
- public double getResult() throws IllegalArgumentException {
+ /**
+ * Return the current covariance estimate.
+ *
+ * @return the current covariance
+ * @throws NumberIsTooSmallException if the number of observations
+ * is < 2
+ */
+ public double getResult() throws NumberIsTooSmallException {
if (n < 2) {
- throw new MathIllegalArgumentException(LocalizedFormats.INSUFFICIENT_DIMENSION,
- n, 2);
+ throw new NumberIsTooSmallException(LocalizedFormats.INSUFFICIENT_DIMENSION,
+ n, 2, true);
}
if (biasCorrected) {
return covarianceNumerator / (n - 1d);
@@ -73,6 +114,5 @@ public class StorelessBivariateCovarianc
return covarianceNumerator / n;
}
}
-
}
Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessCovariance.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessCovariance.java?rev=1244667&r1=1244666&r2=1244667&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessCovariance.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation/StorelessCovariance.java Wed Feb 15 19:22:59 2012
@@ -16,42 +16,75 @@
*/
package org.apache.commons.math3.stat.correlation;
-import org.apache.commons.math3.exception.MathIllegalArgumentException;
+import org.apache.commons.math3.exception.DimensionMismatchException;
import org.apache.commons.math3.exception.MathUnsupportedOperationException;
-import org.apache.commons.math3.exception.util.LocalizedFormats;
-import org.apache.commons.math3.linear.Array2DRowRealMatrix;
+import org.apache.commons.math3.exception.NumberIsTooSmallException;
+import org.apache.commons.math3.linear.MatrixUtils;
import org.apache.commons.math3.linear.RealMatrix;
/**
* Covariance implementation that does not require input data to be
- * stored in memory.
+ * 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().
+ *
+ * <p>This class is based on a paper written by Philippe Pébay:
+ * <a href="http://prod.sandia.gov/techlib/access-control.cgi/2008/086212.pdf">
+ * Formulas for Robust, One-Pass Parallel Computation of Covariances and
+ * Arbitrary-Order Statistical Moments</a>, 2008, Technical Report SAND2008-6212,
+ * Sandia National Laboratories.</p>
*
* @version $Id$
* @since 3.0
*/
public class StorelessCovariance extends Covariance {
- private StorelessBivariateCovariance[][] covMatrix = null;
+ /** the two-dimensional covariance matrix */
+ private StorelessBivariateCovariance[][] covMatrix;
- private int rowDimension = 1;
+ /** row dimension of the covariance matrix */
+ private int rowDimension;
- private int colDimension = 1;
+ /** column dimension of the covariance matrix */
+ private int colDimension;
- private boolean biasCorrected = true;
+ /** flag for bias correction */
+ private boolean biasCorrected;
- public StorelessCovariance(int rowDimension, int colDimension){
- this(rowDimension, colDimension, true);
+ /**
+ * Create a bias corrected covariance matrix with a given number of rows and columns.
+ *
+ * @param rows number of rows
+ * @param cols number of columns
+ */
+ public StorelessCovariance(final int rows, final int cols) {
+ this(rows, cols, true);
}
- public StorelessCovariance(int rowDimension, int colDimension, boolean biasCorrected){
- this.rowDimension = rowDimension;
- this.colDimension = colDimension;
- this.biasCorrected = biasCorrected;
+ /**
+ * Create a covariance matrix with a given number of rows and columns and the
+ * indicated bias correction.
+ *
+ * @param rows number of variables in the rows
+ * @param cols number of variables in the columns
+ * @param biasCorrection if <code>true</code> 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.
+ */
+ public StorelessCovariance(final int rows, final int cols,
+ final boolean biasCorrection) {
+ rowDimension = rows;
+ colDimension = cols;
+ biasCorrected = biasCorrection;
covMatrix = new StorelessBivariateCovariance[rowDimension][colDimension];
initializeMatrix();
}
- private void initializeMatrix(){
+ /**
+ * Initialize the internal two-dimensional array of
+ * {@link StorelessBivariateCovariance} instances.
+ */
+ private void initializeMatrix() {
for(int i=0;i<rowDimension;i++){
for(int j=0;j<colDimension;j++){
covMatrix[i][j] = new StorelessBivariateCovariance(biasCorrected);
@@ -59,46 +92,88 @@ public class StorelessCovariance extends
}
}
- public StorelessBivariateCovariance getCovariance(int xIndex, int yIndex){
+ /**
+ * Get the covariance for an individual element of the covariance matrix.
+ *
+ * @param xIndex row index in the covariance matrix
+ * @param yIndex column index in the covariance matrix
+ * @return the covariance of the given element
+ */
+ public StorelessBivariateCovariance getCovariance(final int xIndex,
+ final int yIndex) {
return covMatrix[xIndex][yIndex];
}
- public void setCovariance(int xIndex, int yIndex, StorelessBivariateCovariance cov){
+ /**
+ * Set the covariance for an individual element of the covariance matrix.
+ *
+ * @param xIndex row index in the covariance matrix
+ * @param yIndex column index in the covariance matrix
+ * @param cov the covariance to be set
+ */
+ public void setCovariance(final int xIndex, final int yIndex,
+ final StorelessBivariateCovariance cov) {
covMatrix[xIndex][yIndex] = cov;
}
- public void incrementCovariance(int xIndex, int yIndex, double x, double y){
+ /**
+ * Increment one individual element of the covariance matrix.
+ *
+ * <p>The element is specified by the xIndex and yIndex and incremented with the
+ * corresponding values of x and y.</p>
+ *
+ * @param xIndex row index in the covariance matrix
+ * @param yIndex column index in the covariance matrix
+ * @param x value of x
+ * @param y value of y
+ */
+ public void incrementCovariance(final int xIndex, final int yIndex,
+ final double x, final double y) {
covMatrix[xIndex][yIndex].increment(x, y);
}
- public void incrementRow(double[] rowData)throws IllegalArgumentException{
+ /**
+ * Increment the covariance matrix with one row of data.
+ *
+ * @param rowData array representing one row of data.
+ * @throws DimensionMismatchException if the length of <code>rowData</code>
+ * does not match with the covariance matrix
+ */
+ public void incrementRow(final double[] rowData)
+ throws DimensionMismatchException {
+
int length = rowData.length;
if (length != colDimension) {
- throw new MathIllegalArgumentException(
- LocalizedFormats.DIMENSIONS_MISMATCH_SIMPLE, length, colDimension);
+ throw new DimensionMismatchException(length, colDimension);
}
- for(int i=0;i<length;i++){
- for(int j=0;j<length;j++){
+ for (int i = 0; i < length; i++){
+ for (int j = 0; j < length; j++){
covMatrix[i][j].increment(rowData[i], rowData[j]);
}
}
+
}
- @Override
- public RealMatrix getCovarianceMatrix() throws IllegalArgumentException {
- RealMatrix matrix = new Array2DRowRealMatrix(rowDimension, colDimension);
- for(int i=0;i<rowDimension;i++){
- for(int j=0;j<colDimension;j++){
- matrix.setEntry(i, j, covMatrix[i][j].getResult());
- }
- }
- return matrix;
+ /**
+ * {@inheritDoc}
+ * @throws NumberIsTooSmallException if the number of observations
+ * in a cell is < 2
+ */
+ public RealMatrix getCovarianceMatrix() throws NumberIsTooSmallException {
+ return MatrixUtils.createRealMatrix(getData());
}
- public double[][] getData() throws IllegalArgumentException {
- double[][] data = new double[rowDimension][rowDimension];
- for(int i=0;i<rowDimension;i++){
- for(int j=0;j<colDimension;j++){
+ /**
+ * Return the covariance matrix as two-dimensional array.
+ *
+ * @return a two-dimensional double array of covariance values
+ * @throws NumberIsTooSmallException if the number of observations
+ * for a cell is < 2
+ */
+ public double[][] getData() throws NumberIsTooSmallException {
+ final double[][] data = new double[rowDimension][rowDimension];
+ for (int i = 0; i < rowDimension; i++) {
+ for (int j = 0; j < colDimension; j++) {
data[i][j] = covMatrix[i][j].getResult();
}
}
@@ -106,16 +181,16 @@ public class StorelessCovariance extends
}
/**
- * This {@link Covariance} method is not supported by StorelessCovariance, since
- * the number of bivariate observations does not have to be the same for different
+ * This {@link Covariance} method is not supported by a {@link 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 {@link Covariance#getN()} is undefined.
- * @return nothing as this implementation always throws a {@link MathUnsupportedOperationException}
+ *
+ * @return nothing as this implementation always throws a
+ * {@link MathUnsupportedOperationException}
* @throws MathUnsupportedOperationException in all cases
*/
- @Override
public int getN()
throws MathUnsupportedOperationException {
throw new MathUnsupportedOperationException();
}
-
}