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

[numpy-svn at scipy.org]

Author: rgommers
Date: 2010-08-14 08:45:09 -0500 (Sat, 14 Aug 2010)
New Revision: 8627

Modified:
   trunk/numpy/core/numeric.py
   trunk/numpy/core/tests/test_numeric.py
Log:
DEP: change default behavior of correlate(), old behavior was deprecated in
1.4.0.

The old behavior should be preserved and made available under the name xcorr or
similar. Should be done for 2.0, then the old_behavior keyword can be removed.

Modified: trunk/numpy/core/numeric.py
===================================================================
--- trunk/numpy/core/numeric.py	2010-08-14 13:44:49 UTC (rev 8626)
+++ trunk/numpy/core/numeric.py	2010-08-14 13:45:09 UTC (rev 8627)
@@ -640,16 +640,17 @@
         return _mode_from_name_dict[mode.lower()[0]]
     return mode
 
-def correlate(a,v,mode='valid',old_behavior=True):
+def correlate(a, v, mode='valid', old_behavior=False):
     """
-    Discrete, linear correlation of two 1-dimensional sequences.
+    Cross-correlation of two 1-dimensional sequences.
 
-    This function is equivalent to
+    This function computes the correlation as generally defined in signal
+    processing texts::
 
-    >>> np.convolve(a, v[::-1], mode=mode)
-    ... #doctest: +SKIP
+        z[k] = sum_n a[n] * conj(v[n+k])
 
-    where ``v[::-1]`` is the reverse of `v`.
+    with a and v sequences being zero-padded where necessary and conj being
+    the conjugate.
 
     Parameters
     ----------
@@ -659,28 +660,14 @@
         Refer to the `convolve` docstring.  Note that the default
         is `valid`, unlike `convolve`, which uses `full`.
     old_behavior : bool
-        If True, uses the old, numeric behavior (correlate(a,v) == correlate(v,
+        If True, uses the old behavior from Numeric, (correlate(a,v) == correlate(v,
         a), and the conjugate is not taken for complex arrays). If False, uses
         the conventional signal processing definition (see note).
 
     See Also
     --------
-    convolve : Discrete, linear convolution of two
-               one-dimensional sequences.
-    acorrelate : Discrete correlation following the usual signal processing
-               definition for complex arrays, and without assuming that
-               ``correlate(a, b) == correlate(b, a)``.
+    convolve : Discrete, linear convolution of two one-dimensional sequences.
 
-    Notes
-    -----
-    If `old_behavior` is False, this function computes the correlation as
-    generally defined in signal processing texts::
-
-        z[k] = sum_n a[n] * conj(v[n+k])
-
-    with a and v sequences being zero-padded where necessary and conj being
-    the conjugate.
-
     Examples
     --------
     >>> np.correlate([1, 2, 3], [0, 1, 0.5])
@@ -692,10 +679,12 @@
 
     """
     mode = _mode_from_name(mode)
+# the old behavior should be made available under a different name, see thread
+# http://thread.gmane.org/gmane.comp.python.numeric.general/12609/focus=12630
     if old_behavior:
         warnings.warn("""
-The current behavior of correlate is deprecated for 1.4.0, and will be removed
-for NumPy 1.5.0.
+The old behavior of correlate was deprecated for 1.4.0, and will be completely removed
+for NumPy 2.0.
 
 The new behavior fits the conventional definition of correlation: inputs are
 never swapped, and the second argument is conjugated for complex arrays.""",

Modified: trunk/numpy/core/tests/test_numeric.py
===================================================================
--- trunk/numpy/core/tests/test_numeric.py	2010-08-14 13:44:49 UTC (rev 8626)
+++ trunk/numpy/core/tests/test_numeric.py	2010-08-14 13:45:09 UTC (rev 8627)
@@ -938,7 +938,7 @@
         x = np.array([1, 2, 3, 4+1j], dtype=np.complex)
         y = np.array([-1, -2j, 3+1j], dtype=np.complex)
         r_z = np.array([3+1j, 6, 8-1j, 9+1j, -1-8j, -4-1j], dtype=np.complex)
-        z = np.correlate(x, y, 'full')
+        z = np.correlate(x, y, 'full', old_behavior=self.old_behavior)
         assert_array_almost_equal(z, r_z)
 
     @dec.deprecated()