From 53cafa064698dd877acb82aa1b6319510fe70ef5 Mon Sep 17 00:00:00 2001
From: Bernhard Spinnler <Bernhard.Spinnler@gmx.net>
Date: Sun, 13 Oct 2013 21:35:30 +0200
Subject: DOC: fixed correlate docstring.

Replaced correlation formula with corrected version that matches the
numpy implementation. Added comment on possible further different
definitions of correlation. Added examples.
---
 numpy/core/numeric.py | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

(limited to 'numpy/core/numeric.py')

diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 1aa59ce58..a5f6140f1 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -820,13 +820,8 @@ def correlate(a, v, mode='valid', old_behavior=False):
     """
     Cross-correlation of two 1-dimensional sequences.
 
-    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.
+    This function computes the cross-correlation of two sequences a and v
+    as generally defined in signal processing text.
 
     Parameters
     ----------
@@ -841,10 +836,30 @@ 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 discrete cross-correlation of two sequences a and v is defined as
+
+    .. math:: c_{av}[k] = \\sum_{n = -\\infty}^{\\infty} a[n+k] v^{*}[n]
+
+    where :math:`v^{*}[n]` is the complex conjugate of :math:`v[n]`.
+
+    Note that sometimes correlation may be defined differently.
+    Another common definition is
+
+    .. math:: c'_{av}[k] = \\sum_{n = -\\infty}^{\\infty} a[n] v^{*}[n+k]
+
+    which is related to :math:`c_{av}[k]` by :math:`c'_{av}[k] = c_{av}[-k]`.
+
     Examples
     --------
     >>> np.correlate([1, 2, 3], [0, 1, 0.5])
@@ -854,6 +869,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.,
+    :math:`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
-- 
cgit v1.2.1


From f6492d927206cf87006e005f0ab19d2db20bc889 Mon Sep 17 00:00:00 2001
From: Bernhard Spinnler <Bernhard.Spinnler@gmx.net>
Date: Tue, 15 Oct 2013 21:21:33 +0200
Subject: DOC: replaced typeset formulas by pure ASCII equivalents.

Replaced typeset formulas by pure ASCII equivalents. Should now be
easier to read in source files.
---
 numpy/core/numeric.py | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

(limited to 'numpy/core/numeric.py')

diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index a5f6140f1..fd6295a47 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -820,8 +820,13 @@ def correlate(a, v, mode='valid', old_behavior=False):
     """
     Cross-correlation of two 1-dimensional sequences.
 
-    This function computes the cross-correlation of two sequences a and v
-    as generally defined in signal processing text.
+    This function computes the correlation as generally defined in signal
+    processing texts::
+
+        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.
 
     Parameters
     ----------
@@ -847,18 +852,12 @@ def correlate(a, v, mode='valid', old_behavior=False):
 
     Notes
     -----
-    The discrete cross-correlation of two sequences a and v is defined as
-
-    .. math:: c_{av}[k] = \\sum_{n = -\\infty}^{\\infty} a[n+k] v^{*}[n]
-
-    where :math:`v^{*}[n]` is the complex conjugate of :math:`v[n]`.
-
-    Note that sometimes correlation may be defined differently.
-    Another common definition is
+    The definition of correlation above is not unique and sometimes correlation
+    may be defined differently. Another common definition is::
 
-    .. math:: c'_{av}[k] = \\sum_{n = -\\infty}^{\\infty} a[n] v^{*}[n+k]
+        c'_{av}[k] = sum_n a[n] conj(v[n+k])
 
-    which is related to :math:`c_{av}[k]` by :math:`c'_{av}[k] = c_{av}[-k]`.
+    which is related to ``c_{av}[k]`` by ``c'_{av}[k] = c_{av}[-k]``.
 
     Examples
     --------
@@ -876,7 +875,7 @@ def correlate(a, v, mode='valid', old_behavior=False):
 
     Note that you get the time reversed, complex conjugated result
     when the two input sequences change places, i.e.,
-    :math:`c_{va}[k] = c^{*}_{av}[-k]`:
+    ``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])
-- 
cgit v1.2.1