Merge pull request #3913 from bspinnler/fix_correlate_docstring

DOC: fixed correlate docstring.

1 files changed, 27 insertions, 1 deletions

diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 53254ec6a..f43f93d64 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -823,7 +823,7 @@ def correlate(a, v, mode='valid', old_behavior=False):
     This function computes the correlation as generally defined in signal
     processing texts::
 
-        z[k] = sum_n a[n] * conj(v[n+k])
+        c_{av}[k] = sum_n a[n+k] * conj(v[n])
 
     with a and v sequences being zero-padded where necessary and conj being
     the conjugate.
@@ -841,10 +841,24 @@ def correlate(a, v, mode='valid', old_behavior=False):
         for complex arrays). If False, uses the conventional signal
         processing definition.
 
+    Returns
+    -------
+    out : ndarray
+        Discrete cross-correlation of `a` and `v`.
+
     See Also
     --------
     convolve : Discrete, linear convolution of two one-dimensional sequences.
 
+    Notes
+    -----
+    The definition of correlation above is not unique and sometimes correlation
+    may be defined differently. Another common definition is::
+
+        c'_{av}[k] = sum_n a[n] conj(v[n+k])
+
+    which is related to ``c_{av}[k]`` by ``c'_{av}[k] = c_{av}[-k]``.
+
     Examples
     --------
     >>> np.correlate([1, 2, 3], [0, 1, 0.5])
@@ -854,6 +868,18 @@ def correlate(a, v, mode='valid', old_behavior=False):
     >>> np.correlate([1, 2, 3], [0, 1, 0.5], "full")
     array([ 0.5,  2. ,  3.5,  3. ,  0. ])
 
+    Using complex sequences:
+
+    >>> np.correlate([1+1j, 2, 3-1j], [0, 1, 0.5j], 'full')
+    array([ 0.5-0.5j,  1.0+0.j ,  1.5-1.5j,  3.0-1.j ,  0.0+0.j ])
+
+    Note that you get the time reversed, complex conjugated result
+    when the two input sequences change places, i.e.,
+    ``c_{va}[k] = c^{*}_{av}[-k]``:
+
+    >>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full')
+    array([ 0.0+0.j ,  3.0+1.j ,  1.5+1.5j,  1.0+0.j ,  0.5+0.5j])
+
     """
     mode = _mode_from_name(mode)
 # the old behavior should be made available under a different name, see thread