Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@commons.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: svn commit: r1244667 - in
 /commons/proper/math/trunk/src/main/java/org/apache/commons/math3/stat/correlation:
 Covariance.java StorelessBivariateCovariance.java StorelessCovariance.java
Date: Wed, 15 Feb 2012 19:22:59 -0000
To: commits@commons.apache.org
From: tn@apache.org
Message-Id: <20120215192300.1F17A238897D@eris.apache.org>

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 &lt; 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 &lt; 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 &lt; 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();
     }
-
 }