Documented and tested new behaviour of std and var on complex numbers. Added ddof argument and its documentation to the std and var methods of matrix. Documented ddof for std and var methods of ma. Note that stdu and varu in ma still have the old, peculiar, behaviour for complex values.

1 files changed, 20 insertions, 10 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index b1fb50900..be2b86f63 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -1024,7 +1024,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('mean',
     ----------
     axis : integer
         Axis along which the means are computed. The default is
-        to compute the standard deviation of the flattened array.
+        to compute the mean of the flattened array.
     dtype : type
         Type to use in computing the means. For arrays of
         integer type the default is float32, for arrays of float types it
@@ -1277,7 +1277,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('squeeze',
 
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
-    """a.std(axis=None, dtype=None, out=None) -> standard deviation.
+    """a.std(axis=None, dtype=None, out=None, ddof=0) -> standard deviation.
 
     Returns the standard deviation of the array elements, a measure of the
     spread of a distribution. The standard deviation is computed for the
@@ -1296,6 +1296,9 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
         Alternative output array in which to place the result. It must have
         the same shape as the expected output but the type will be cast if
         necessary.
+    ddof : {0, integer}
+        Means Delta Degrees of Freedom.  The divisor used in calculations
+        is N-ddof.
 
     Returns
     -------
@@ -1311,9 +1314,11 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
     Notes
     -----
     The standard deviation is the square root of the average of the squared
-    deviations from the mean, i.e. var = sqrt(mean((x - x.mean())**2)).  The
-    computed standard deviation is biased, i.e., the mean is computed by
-    dividing by the number of elements, N, rather than by N-1.
+    deviations from the mean, i.e. var = sqrt(mean(abs(x - x.mean())**2)).  
+    The computed standard deviation is computed by dividing by the number of 
+    elements, N-ddof. The option ddof defaults to zero, that is, a 
+    biased estimate. Note that for complex numbers std takes the absolute 
+    value before squaring, so that the result is always real and nonnegative.
 
     """))
 
@@ -1461,7 +1466,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose',
 
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
-    """a.var(axis=None, dtype=None, out=None) -> variance
+    """a.var(axis=None, dtype=None, out=None, ddof=0) -> variance
 
     Returns the variance of the array elements, a measure of the spread of a
     distribution.  The variance is computed for the flattened array by default,
@@ -1480,6 +1485,9 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
         Alternative output array in which to place the result. It must have
         the same shape as the expected output but the type will be cast if
         necessary.
+    ddof : {0, integer},
+        Means Delta Degrees of Freedom.  The divisor used in calculation is
+        N - ddof.
 
     Returns
     -------
@@ -1494,10 +1502,12 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
 
     Notes
     -----
-    The variance is the average of the squared deviations from the mean, i.e.
-    var = mean((x - x.mean())**2).  The computed variance is biased, i.e.,
-    the mean is computed by dividing by the number of elements, N, rather
-    than by N-1.
+    The variance is the average of the squared deviations from the mean,
+    i.e.  var = mean(abs(x - x.mean())**2).  The mean is computed by 
+    dividing by N-ddof, where N is the number of elements. The argument 
+    ddof defaults to zero; for an unbiased estimate supply ddof=1. Note 
+    that for complex numbers the absolute value is taken before squaring, 
+    so that the result is always real and nonnegative.
 
     """))