numpy · charris · Mar 21, 2015 · Mar 15, 2015 · Mar 15, 2015 · charris
diff --git a/doc/release/1.10.0-notes.rst b/doc/release/1.10.0-notes.rst
@@ -237,3 +237,18 @@ deprecated.
 pkgload, PackageLoader
 ~~~~~~~~~~~~~~~~~~~~~~
 These ways of loading packages are now deprecated.
+
+bias, ddof arguments to corrcoef
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The values for the ``bias`` and ``ddof`` arguments to the ``corrcoef``
+function canceled in the division implied by the correlation coefficient and
+so had no effect on the returned values.
+
+We now deprecate these arguments to ``corrcoef`` and the masked array version
+``ma.corrcoef``.
+
+Because we are deprecating the ``bias`` argument to ``ma.corrcoef``, we also
+deprecate the use of the ``allow_masked`` argument as a positional argument,
+as its position will change with the removal of ``bias``.  ``allow_masked``
+will in due course become a keyword-only argument.
diff --git a/numpy/__init__.py b/numpy/__init__.py
@@ -132,6 +132,16 @@ class VisibleDeprecationWarning(UserWarning):
     pass
 
 
+class _NoValue:
+    """Special keyword value.
+
+    This class may be used as the default value assigned to a
+    deprecated keyword in order to check if it has been given a user
+    defined value.
+    """
+    pass
+
+
 # oldnumeric and numarray were removed in 1.9. In case some packages import
 # but do not use them, we define them here for backward compatibility.
 oldnumeric = 'removed'

diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
@@ -1949,17 +1949,17 @@ def cov(m, y=None, rowvar=1, bias=0, ddof=None):
         return (dot(X, X.T.conj()) / fact).squeeze()
 
 
-def corrcoef(x, y=None, rowvar=1, bias=0, ddof=None):
+def corrcoef(x, y=None, rowvar=1, bias=np._NoValue, ddof=np._NoValue):
     """
-    Return correlation coefficients.
+    Return Pearson product-moment correlation coefficients.
 
     Please refer to the documentation for `cov` for more detail.  The
-    relationship between the correlation coefficient matrix, `P`, and the
+    relationship between the correlation coefficient matrix, `R`, and the
     covariance matrix, `C`, is
 
-    .. math:: P_{ij} = \\frac{ C_{ij} } { \\sqrt{ C_{ii} * C_{jj} } }
+    .. math:: R_{ij} = \\frac{ C_{ij} } { \\sqrt{ C_{ii} * C_{jj} } }
 
-    The values of `P` are between -1 and 1, inclusive.
+    The values of `R` are between -1 and 1, inclusive.
 
     Parameters
     ----------
@@ -1975,28 +1975,33 @@ def corrcoef(x, y=None, rowvar=1, bias=0, ddof=None):
         variable, with observations in the columns. Otherwise, the relationship
         is transposed: each column represents a variable, while the rows
         contain observations.
-    bias : int, optional
-        Default normalization is by ``(N - 1)``, where ``N`` is the number of
-        observations (unbiased estimate). If `bias` is 1, then
-        normalization is by ``N``. These values can be overridden by using
-        the keyword ``ddof`` in numpy versions >= 1.5.
-    ddof : int, optional
-        .. versionadded:: 1.5
-        If not ``None`` normalization is by ``(N - ddof)``, where ``N`` is
-        the number of observations; this overrides the value implied by
-        ``bias``. The default value is ``None``.
+    bias : _NoValue, optional
+        .. deprecated:: 1.10.0
+        Has no affect, do not use.
+    ddof : _NoValue, optional
+        .. deprecated:: 1.10.0
+        Has no affect, do not use.
 
     Returns
     -------
-    out : ndarray
+    R : ndarray
         The correlation coefficient matrix of the variables.
 
     See Also
     --------
     cov : Covariance matrix
 
+    Notes
+    -----
+    This function accepts but discards arguments `bias` and `ddof`.  This is
+    for backwards compatibility with previous versions of this function.  These
+    arguments had no effect on the return values of the function and can be
+    safely ignored in this and previous versions of numpy.
     """
-    c = cov(x, y, rowvar, bias, ddof)
+    if bias is not np._NoValue or ddof is not np._NoValue:
+        warnings.warn('bias and ddof have no affect and are deprecated',
+                      DeprecationWarning)
+    c = cov(x, y, rowvar)
     try:
         d = diag(c)
     except ValueError:  # scalar covariance

diff --git a/numpy/lib/tests/test_function_base.py b/numpy/lib/tests/test_function_base.py
@@ -8,8 +8,9 @@
     run_module_suite, TestCase, assert_, assert_equal, assert_array_equal,
     assert_almost_equal, assert_array_almost_equal, assert_raises,
     assert_allclose, assert_array_max_ulp, assert_warns,
-    assert_raises_regex, dec
+    assert_raises_regex, dec, clear_and_catch_warnings
     )
+import numpy.lib.function_base as nfb
 from numpy.random import rand
 from numpy.lib import *
 from numpy.compat import long
@@ -1305,6 +1306,12 @@ def test_dtype_order(self):
         assert_(a.dtype == np.float64)
 
 
+class catch_warn_nfb(clear_and_catch_warnings):
+    """ Context manager to catch, reset warnings in function_base module
+    """
+    class_modules = (nfb,)
+
+
 class TestCorrCoef(TestCase):
     A = np.array(
         [[0.15391142, 0.18045767, 0.14197213],
@@ -1335,8 +1342,26 @@ def test_simple(self):
         assert_almost_equal(corrcoef(self.A, self.B), self.res2)
 
     def test_ddof(self):
-        assert_almost_equal(corrcoef(self.A, ddof=-1), self.res1)
-        assert_almost_equal(corrcoef(self.A, self.B, ddof=-1), self.res2)
+        # ddof raises DeprecationWarning
+        with catch_warn_nfb():
+            warnings.simplefilter("always")
+            assert_warns(DeprecationWarning, corrcoef, self.A, ddof=-1)
+            warnings.simplefilter("ignore")
+            # ddof has no or negligible effect on the function
+            assert_almost_equal(corrcoef(self.A, ddof=-1), self.res1)
+            assert_almost_equal(corrcoef(self.A, self.B, ddof=-1), self.res2)
+            assert_almost_equal(corrcoef(self.A, ddof=3), self.res1)
+            assert_almost_equal(corrcoef(self.A, self.B, ddof=3), self.res2)
+
+    def test_bias(self):
+        # bias raises DeprecationWarning
+        with catch_warn_nfb():
+            warnings.simplefilter("always")
+            assert_warns(DeprecationWarning, corrcoef, self.A, self.B, 1, 0)
+            assert_warns(DeprecationWarning, corrcoef, self.A, bias=0)
+            warnings.simplefilter("ignore")
+            # bias has no or negligible effect on the function
+            assert_almost_equal(corrcoef(self.A, bias=1), self.res1)
 
     def test_complex(self):
         x = np.array([[1, 2, 3], [1j, 2j, 3j]])
@@ -1356,13 +1381,6 @@ def test_empty(self):
             assert_array_equal(corrcoef(np.array([]).reshape(2, 0)),
                                np.array([[np.nan, np.nan], [np.nan, np.nan]]))
 
-    def test_wrong_ddof(self):
-        x = np.array([[0, 2], [1, 1], [2, 0]]).T
-        with warnings.catch_warnings(record=True):
-            warnings.simplefilter('always', RuntimeWarning)
-            assert_array_equal(corrcoef(x, ddof=5),
-                               np.array([[np.nan, np.nan], [np.nan, np.nan]]))
-
 
 class TestCov(TestCase):
     def test_basic(self):

diff --git a/numpy/ma/extras.py b/numpy/ma/extras.py
@@ -48,7 +48,6 @@
 from numpy import ndarray, array as nxarray
 import numpy.core.umath as umath
 from numpy.lib.index_tricks import AxisConcatenator
-from numpy.linalg import lstsq
 
 
 #...............................................................................
@@ -1377,9 +1376,10 @@ def cov(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None):
     return result
 
 
-def corrcoef(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None):
+def corrcoef(x, y=None, rowvar=True, bias=np._NoValue, allow_masked=True,
+             ddof=np._NoValue):
     """
-    Return correlation coefficients of the input array.
+    Return Pearson product-moment correlation coefficients.
 
     Except for the handling of missing data this function does the same as
     `numpy.corrcoef`. For more details and examples, see `numpy.corrcoef`.
@@ -1398,45 +1398,41 @@ def corrcoef(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None):
         variable, with observations in the columns. Otherwise, the relationship
         is transposed: each column represents a variable, while the rows
         contain observations.
-    bias : bool, optional
-        Default normalization (False) is by ``(N-1)``, where ``N`` is the
-        number of observations given (unbiased estimate). If `bias` is 1,
-        then normalization is by ``N``. This keyword can be overridden by
-        the keyword ``ddof`` in numpy versions >= 1.5.
+    bias : _NoValue, optional
+        .. deprecated:: 1.10.0
+        Has no affect, do not use.
     allow_masked : bool, optional
         If True, masked values are propagated pair-wise: if a value is masked
         in `x`, the corresponding value is masked in `y`.
-        If False, raises an exception.
-    ddof : {None, int}, optional
-        .. versionadded:: 1.5
-        If not ``None`` normalization is by ``(N - ddof)``, where ``N`` is
-        the number of observations; this overrides the value implied by
-        ``bias``. The default value is ``None``.
+        If False, raises an exception.  Because `bias` is deprecated, this
+        argument needs to be treated as keyword only to avoid a warning.
+    ddof : _NoValue, optional
+        .. deprecated:: 1.10.0
+        Has no affect, do not use.
 
     See Also
     --------
     numpy.corrcoef : Equivalent function in top-level NumPy module.
     cov : Estimate the covariance matrix.
 
-    """
-    # Check inputs
-    if ddof is not None and ddof != int(ddof):
-        raise ValueError("ddof must be an integer")
-    # Set up ddof
-    if ddof is None:
-        if bias:
-            ddof = 0
-        else:
-            ddof = 1
-
+    Notes
+    -----
+    This function accepts but discards arguments `bias` and `ddof`.  This is
+    for backwards compatibility with previous versions of this function.  These
+    arguments had no effect on the return values of the function and can be
+    safely ignored in this and previous versions of numpy.
+    """
+    msg = 'bias and ddof have no affect and are deprecated'
+    if bias is not np._NoValue or ddof is not np._NoValue:
+        warnings.warn(msg, DeprecationWarning)
     # Get the data
     (x, xnotmask, rowvar) = _covhelper(x, y, rowvar, allow_masked)
     # Compute the covariance matrix
     if not rowvar:
-        fact = np.dot(xnotmask.T, xnotmask) * 1. - ddof
+        fact = np.dot(xnotmask.T, xnotmask) * 1.
         c = (dot(x.T, x.conj(), strict=False) / fact).squeeze()
     else:
-        fact = np.dot(xnotmask, xnotmask.T) * 1. - ddof
+        fact = np.dot(xnotmask, xnotmask.T) * 1.
         c = (dot(x, x.T.conj(), strict=False) / fact).squeeze()
     # Check whether we have a scalar
     try:
@@ -1452,13 +1448,13 @@ def corrcoef(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None):
         if rowvar:
             for i in range(n - 1):
                 for j in range(i + 1, n):
-                    _x = mask_cols(vstack((x[i], x[j]))).var(axis=1, ddof=ddof)
+                    _x = mask_cols(vstack((x[i], x[j]))).var(axis=1)
                     _denom[i, j] = _denom[j, i] = ma.sqrt(ma.multiply.reduce(_x))
         else:
             for i in range(n - 1):
                 for j in range(i + 1, n):
                     _x = mask_cols(
-                            vstack((x[:, i], x[:, j]))).var(axis=1, ddof=ddof)
+                            vstack((x[:, i], x[:, j]))).var(axis=1)
                     _denom[i, j] = _denom[j, i] = ma.sqrt(ma.multiply.reduce(_x))
     return c / _denom