[Numpy-svn] r4971 - in trunk/numpy: . core core/tests ma

numpy-svn@scip... numpy-svn@scip...
Sun Apr 6 21:59:38 CDT 2008


Author: peridot
Date: 2008-04-06 21:59:18 -0500 (Sun, 06 Apr 2008)
New Revision: 4971

Modified:
   trunk/numpy/add_newdocs.py
   trunk/numpy/core/defmatrix.py
   trunk/numpy/core/fromnumeric.py
   trunk/numpy/core/tests/test_numeric.py
   trunk/numpy/ma/core.py
Log:
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.


Modified: trunk/numpy/add_newdocs.py
===================================================================
--- trunk/numpy/add_newdocs.py	2008-04-07 02:07:04 UTC (rev 4970)
+++ trunk/numpy/add_newdocs.py	2008-04-07 02:59:18 UTC (rev 4971)
@@ -1024,7 +1024,7 @@
     ----------
     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', ('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 @@
         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 @@
     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', ('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 @@
         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 @@
 
     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.
 
     """))
 

Modified: trunk/numpy/core/defmatrix.py
===================================================================
--- trunk/numpy/core/defmatrix.py	2008-04-07 02:07:04 UTC (rev 4970)
+++ trunk/numpy/core/defmatrix.py	2008-04-07 02:59:18 UTC (rev 4971)
@@ -350,7 +350,7 @@
         """
         return N.ndarray.mean(self, axis, dtype, out)._align(axis)
 
-    def std(self, axis=None, dtype=None, out=None):
+    def std(self, axis=None, dtype=None, out=None, ddof=0):
         """Compute the standard deviation along the specified axis.
 
         Returns the standard deviation of the array elements, a measure of the
@@ -363,16 +363,17 @@
             Axis along which the standard deviation is computed. The
             default is to compute the standard deviation of the flattened
             array.
-
         dtype : type
             Type to use in computing the standard deviation. For arrays of
             integer type the default is float32, for arrays of float types
             it is the same as the array type.
-
         out : ndarray
             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
         -------
@@ -389,13 +390,17 @@
         -----
         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.
+        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.
+
         """
-        return N.ndarray.std(self, axis, dtype, out)._align(axis)
+        return N.ndarray.std(self, axis, dtype, out, ddof)._align(axis)
 
-    def var(self, axis=None, dtype=None, out=None):
+    def var(self, axis=None, dtype=None, out=None, ddof=0):
         """Compute the variance along the specified axis.
 
         Returns the variance of the array elements, a measure of the spread of
@@ -415,6 +420,9 @@
             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
         -------
@@ -431,9 +439,12 @@
         -----
 
         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.
+        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.
         """
         return N.ndarray.var(self, axis, dtype, out)._align(axis)
 

Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py	2008-04-07 02:07:04 UTC (rev 4970)
+++ trunk/numpy/core/fromnumeric.py	2008-04-07 02:59:18 UTC (rev 4971)
@@ -1671,9 +1671,11 @@
     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 computed by dividing by the number of 
-    elements, N-ddof.
+    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.
 
     Examples
     --------
@@ -1734,9 +1736,10 @@
     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.  var = mean(abs(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.
+    rather than by N-1. Note that for complex numbers the absolute value is
+    taken before squaring, so that the result is always real and nonnegative.
 
     Examples
     --------

Modified: trunk/numpy/core/tests/test_numeric.py
===================================================================
--- trunk/numpy/core/tests/test_numeric.py	2008-04-07 02:07:04 UTC (rev 4970)
+++ trunk/numpy/core/tests/test_numeric.py	2008-04-07 02:59:18 UTC (rev 4971)
@@ -739,6 +739,13 @@
         assert_almost_equal(var(self.A,ddof=2),self.real_var*len(self.A)/float(len(self.A)-2))
         assert_almost_equal(std(self.A,ddof=2)**2,self.real_var*len(self.A)/float(len(self.A)-2))
 
+class TestStdVarComplex(NumpyTestCase):
+    def test_basic(self):
+        A = array([1,1.j,-1,-1.j])
+        real_var = 1
+        assert_almost_equal(var(A),real_var)
+        assert_almost_equal(std(A)**2,real_var)
+
 import sys
 if sys.version_info[:2] >= (2, 5):
     set_local_path()

Modified: trunk/numpy/ma/core.py
===================================================================
--- trunk/numpy/ma/core.py	2008-04-07 02:07:04 UTC (rev 4970)
+++ trunk/numpy/ma/core.py	2008-04-07 02:59:18 UTC (rev 4971)
@@ -2153,7 +2153,7 @@
         """Return the variance, a measure of the spread of a distribution.
 
         The variance is the average of the squared deviations from the
-        mean, i.e. var = mean((x - x.mean())**2).
+        mean, i.e. var = mean(abs(x - x.mean())**2).
 
         Parameters
         ----------
@@ -2166,8 +2166,11 @@
 
         Notes
         -----
-        The value returned is a biased estimate of the true variance.
-        For the (more standard) unbiased estimate, use varu.
+        The value returned is by default a biased estimate of the 
+        true variance, since the mean is computed by dividing by N-ddof.
+        For the (more standard) unbiased estimate, use ddof=1 or call varu.
+        Note that for complex numbers the absolute value is taken before 
+        squaring, so that the result is always real and nonnegative.
 
         """
         if self._mask is nomask:
@@ -2191,7 +2194,7 @@
         The standard deviation is the square root of the average of
         the squared deviations from the mean, i.e.
 
-        std = sqrt(mean((x - x.mean())**2)).
+        std = sqrt(mean(abs(x - x.mean())**2)).
 
         Parameters
         ----------
@@ -2204,10 +2207,12 @@
 
         Notes
         -----
-        The value returned is a biased estimate of the true
-        standard deviation.  For the more standard unbiased
-        estimate, use stdu.
-
+        The value returned is by default a biased estimate of the 
+        true standard deviation, since the mean is computed by dividing 
+        by N-ddof.  For the more standard unbiased estimate, use ddof=1 
+        or call stdu. Note that for complex numbers the absolute value
+        is taken before squaring, so that the result is always real
+        and nonnegative.
         """
         dvar = self.var(axis,dtype,ddof=ddof)
         if axis is not None or dvar is not masked:



More information about the Numpy-svn mailing list