[Numpy-discussion] Bug in numpy.correlate documentation

[Bernhard Spinnler]

Hi Richard,

Ah, I searched the list but didn't find those posts before…

I can easily imagine that correlation is defined differently in different disciplines. Both ways are correct and it's just a convention or definition. In my field (Digital Communications, Digital Signal Processing) the vast majority uses the convention implemented by the code. Here are a few examples of prominent text books:

- Papoulis, "Probaility, Random Variables, and Stochastic Processes", McGraw-Hill, 2nd ed.
- Benvenuto, Cherubini, "Algorithms for Communications Systems and their Applications", Wiley.
- Carlson, "Communication Systems" 4th ed. 2002, McGraw-Hill.

Last not least, Matlab's xcorr() function behaves exactly like correlate() does right now, see
- http://www.mathworks.de/de/help/signal/ref/xcorr.html

But, as you say, the most important aspect might be, that most people will probably prefer changing the docs instead of changing the code.

Should I file a bug somewhere?

Cheers,
	Bernhard


On 08.10.2013, at 21:10, Richard Hattersley <rhattersley at gmail.com> wrote:

> Hi Bernard,
> 
> Looks like you're on to something - two other people have raised this discrepancy before: https://github.com/numpy/numpy/issues/2588. Unfortunately, when it comes to resolving the discrepancy one of the previous comments takes the opposite view. Namely, that the docstring is correct and the code is wrong.
> 
> Do different domains use different conventions here? Are there some references to back up one stance or another?
> 
> But all else being equal, I'm guessing there'll be far more appetite for updating the documentation than the code.
> 
> Regards,
> Richard Hattersley
> 
> 
> On 7 October 2013 22:09, Bernhard Spinnler <Bernhard.Spinnler at gmx.net> wrote:
> The numpy.correlate documentation says:
> 
>         correlate(a, v) = z[k] = sum_n a[n] * conj(v[n+k])
> 
> In [1]: a = [1, 2]
> 
> In [2]: v = [2, 1j]
> 
> In [3]: z = correlate(a, v, 'full')
> 
> In [4]: z
> Out[4]: array([ 0.-1.j,  2.-2.j,  4.+0.j])
> 
> However, according to the documentation, z should be
> 
>         z[-1] = a[1] * conj(v[0]) = 4.+0.j
>         z[0]  = a[0] * conj(v[0]) + a[1] * conj(v[1]) = 2.-2.j
>         z[1] = a[0] * conj(v[1]) = 0.-1.j
> 
> which is the time reversed version of what correlate() calculates.
> 
> IMHO, the correlate() code is correct. The correct formula in the docs (which is also the correlation formula in standard text books) should be
> 
>         z[k] = sum_n a[n+k] * conj(v[n])
> 
> Cheers,
>         Bernhard
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
> 
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20131009/38b19747/attachment.html>