Allow covariance to be computed for one-dimensional variables.

JIRA: MATH-939

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1453271 13f79535-47bb-0310-9956-ffa450edef68

Author: Luc Maisonobe

src/changes/changes.xml

@@ -55,6 +55,9 @@ This is a minor release: It combines bug fixes and new features.
   Changes to existing features were made in a backwards-compatible
   way such as to allow drop-in replacement of the v3.1[.1] JAR file.
 ">
+      <action dev="luc" type="fix" issue="MATH-939" due-to="Piotr Wydrych" >
+        Allow covariance to be computed for one-dimensional variables.
+      </action>
       <action dev="luc" type="fix" issue="MATH-938" >
         Fixed accuracy of 3D Line.revert().
       </action>

src/main/java/org/apache/commons/math3/stat/correlation/Covariance.java

@@ -17,6 +17,7 @@
 package org.apache.commons.math3.stat.correlation;
 
 import org.apache.commons.math3.exception.MathIllegalArgumentException;
+import org.apache.commons.math3.exception.NotStrictlyPositiveException;
 import org.apache.commons.math3.exception.util.LocalizedFormats;
 import org.apache.commons.math3.linear.RealMatrix;
 import org.apache.commons.math3.linear.BlockRealMatrix;
@@ -70,31 +71,36 @@ public Covariance() {
      * <p>The <code>biasCorrected</code> parameter determines whether or not
      * covariance estimates are bias-corrected.</p>
      *
-     * <p>The input array must be rectangular with at least two columns
+     * <p>The input array must be rectangular with at least one column
      * and two rows.</p>
      *
      * @param data rectangular array with columns representing covariates
      * @param biasCorrected true means covariances are bias-corrected
      * @throws MathIllegalArgumentException if the input data array is not
-     * rectangular with at least two rows and two columns.
+     * rectangular with at least two rows and one column.
+     * @throws NotStrictlyPositiveException if the input data array is not
+     * rectangular with at least one row and one column.
      */
     public Covariance(double[][] data, boolean biasCorrected)
-    throws MathIllegalArgumentException {
+    throws MathIllegalArgumentException, NotStrictlyPositiveException {
         this(new BlockRealMatrix(data), biasCorrected);
     }
 
     /**
      * Create a Covariance matrix from a rectangular array
      * whose columns represent covariates.
      *
-     * <p>The input array must be rectangular with at least two columns
+     * <p>The input array must be rectangular with at least one column
      * and two rows</p>
      *
      * @param data rectangular array with columns representing covariates
      * @throws MathIllegalArgumentException if the input data array is not
-     * rectangular with at least two rows and two columns.
+     * rectangular with at least two rows and one column.
+     * @throws NotStrictlyPositiveException if the input data array is not
+     * rectangular with at least one row and one column.
      */
-    public Covariance(double[][] data) throws MathIllegalArgumentException {
+    public Covariance(double[][] data)
+    throws MathIllegalArgumentException, NotStrictlyPositiveException {
         this(data, true);
     }
 
@@ -105,12 +111,12 @@ public Covariance(double[][] data) throws MathIllegalArgumentException {
      * <p>The <code>biasCorrected</code> parameter determines whether or not
      * covariance estimates are bias-corrected.</p>
      *
-     * <p>The matrix must have at least two columns and two rows</p>
+     * <p>The matrix must have at least one column and two rows</p>
      *
      * @param matrix matrix with columns representing covariates
      * @param biasCorrected true means covariances are bias-corrected
      * @throws MathIllegalArgumentException if the input matrix does not have
-     * at least two rows and two columns
+     * at least two rows and one column
      */
     public Covariance(RealMatrix matrix, boolean biasCorrected)
     throws MathIllegalArgumentException {
@@ -123,11 +129,11 @@ public Covariance(RealMatrix matrix, boolean biasCorrected)
      * Create a covariance matrix from a matrix whose columns
      * represent covariates.
      *
-     * <p>The matrix must have at least two columns and two rows</p>
+     * <p>The matrix must have at least one column and two rows</p>
      *
      * @param matrix matrix with columns representing covariates
      * @throws MathIllegalArgumentException if the input matrix does not have
-     * at least two rows and two columns
+     * at least two rows and one column
      */
     public Covariance(RealMatrix matrix) throws MathIllegalArgumentException {
         this(matrix, true);
@@ -154,7 +160,7 @@ public int getN() {
     /**
      * Compute a covariance matrix from a matrix whose columns represent
      * covariates.
-     * @param matrix input matrix (must have at least two columns and two rows)
+     * @param matrix input matrix (must have at least one column and two rows)
      * @param biasCorrected determines whether or not covariance estimates are bias-corrected
      * @return covariance matrix
      * @throws MathIllegalArgumentException if the matrix does not contain sufficient data
@@ -178,7 +184,7 @@ protected RealMatrix computeCovarianceMatrix(RealMatrix matrix, boolean biasCorr
     /**
      * Create a covariance matrix from a matrix whose columns represent
      * covariates. Covariances are computed using the bias-corrected formula.
-     * @param matrix input matrix (must have at least two columns and two rows)
+     * @param matrix input matrix (must have at least one column and two rows)
      * @return covariance matrix
      * @throws MathIllegalArgumentException if matrix does not contain sufficient data
      * @see #Covariance
@@ -191,26 +197,31 @@ protected RealMatrix computeCovarianceMatrix(RealMatrix matrix)
     /**
      * Compute a covariance matrix from a rectangular array whose columns represent
      * covariates.
-     * @param data input array (must have at least two columns and two rows)
+     * @param data input array (must have at least one column and two rows)
      * @param biasCorrected determines whether or not covariance estimates are bias-corrected
      * @return covariance matrix
      * @throws MathIllegalArgumentException if the data array does not contain sufficient
      * data
+     * @throws NotStrictlyPositiveException if the input data array is not
+     * rectangular with at least one row and one column.
      */
     protected RealMatrix computeCovarianceMatrix(double[][] data, boolean biasCorrected)
-    throws MathIllegalArgumentException {
+    throws MathIllegalArgumentException, NotStrictlyPositiveException {
         return computeCovarianceMatrix(new BlockRealMatrix(data), biasCorrected);
     }
 
     /**
      * Create a covariance matrix from a rectangular array whose columns represent
      * covariates. Covariances are computed using the bias-corrected formula.
-     * @param data input array (must have at least two columns and two rows)
+     * @param data input array (must have at least one column and two rows)
      * @return covariance matrix
      * @throws MathIllegalArgumentException if the data array does not contain sufficient data
+     * @throws NotStrictlyPositiveException if the input data array is not
+     * rectangular with at least one row and one column.
      * @see #Covariance
      */
-    protected RealMatrix computeCovarianceMatrix(double[][] data) throws MathIllegalArgumentException {
+    protected RealMatrix computeCovarianceMatrix(double[][] data)
+    throws MathIllegalArgumentException, NotStrictlyPositiveException {
         return computeCovarianceMatrix(data, true);
     }
 
@@ -268,15 +279,15 @@ public double covariance(final double[] xArray, final double[] yArray)
 
     /**
      * Throws MathIllegalArgumentException if the matrix does not have at least
-     * two columns and two rows.
+     * one column and two rows.
      * @param matrix matrix to check
      * @throws MathIllegalArgumentException if the matrix does not contain sufficient data
      * to compute covariance
      */
     private void checkSufficientData(final RealMatrix matrix) throws MathIllegalArgumentException {
         int nRows = matrix.getRowDimension();
         int nCols = matrix.getColumnDimension();
-        if (nRows < 2 || nCols < 2) {
+        if (nRows < 2 || nCols < 1) {
             throw new MathIllegalArgumentException(
                     LocalizedFormats.INSUFFICIENT_ROWS_AND_COLUMNS,
                     nRows, nCols);

src/test/java/org/apache/commons/math3/stat/correlation/CovarianceTest.java

@@ -17,6 +17,7 @@
 package org.apache.commons.math3.stat.correlation;
 
 import org.apache.commons.math3.TestUtils;
+import org.apache.commons.math3.exception.NotStrictlyPositiveException;
 import org.apache.commons.math3.linear.RealMatrix;
 import org.apache.commons.math3.linear.Array2DRowRealMatrix;
 import org.apache.commons.math3.stat.descriptive.moment.Variance;
@@ -161,6 +162,16 @@ public void testConstant() {
         Assert.assertEquals(0d, new Covariance().covariance(noVariance, noVariance, true), Double.MIN_VALUE);
     }
 
+    /**
+     * One column
+     */
+    @Test
+    public void testOneColumn() {
+        RealMatrix cov = new Covariance(new double[][] {{1}, {2}}, false).getCovarianceMatrix();
+        Assert.assertEquals(1, cov.getRowDimension());
+        Assert.assertEquals(1, cov.getColumnDimension());
+        Assert.assertEquals(0.25, cov.getEntry(0, 0), 1.0e-15);
+    }
 
     /**
      * Insufficient data
@@ -175,11 +186,10 @@ public void testInsufficientData() {
         } catch (IllegalArgumentException ex) {
             // Expected
         }
-        RealMatrix matrix = new Array2DRowRealMatrix(new double[][] {{0},{1}});
         try {
-            new Covariance(matrix);
-            Assert.fail("Expecting IllegalArgumentException");
-        } catch (IllegalArgumentException ex) {
+            new Covariance(new double[][] {{},{}});
+            Assert.fail("Expecting NotStrictlyPositiveException");
+        } catch (NotStrictlyPositiveException ex) {
             // Expected
         }
     }