[Numpy-discussion] Bug in numpy.correlate documentation

[David Goldsmith]

Date: Wed, 9 Oct 2013 21:54:07 +0100

> From: Nathaniel Smith <njs at pobox.com>
> Subject: Re: [Numpy-discussion] Bug in numpy.correlate documentation
> To: Discussion of Numerical Python <numpy-discussion at scipy.org>
> Message-ID:
>         <CAPJVwBmMZKN=
> z8V-aHUU+85LZ88xYWmAwxgzHk5GhtfuW8HN9A at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
>
> On Wed, Oct 9, 2013 at 7:48 PM, Bernhard Spinnler
> <Bernhard.Spinnler at gmx.net> wrote:
> > 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.
>
> Yeah, unless the current behaviour is actually broken or redundant in
> some way, we're not going to switch from one perfectly good convention
> to another perfectly good convention and break everyone's code in the
> process.
>
> The most helpful thing would be if you could file a pull request that
> just changes the docstring to what you think it should be. Extra bonus
> points if it points out that there is another definition some people
> might be expecting instead, and explains how those people can use the
> existing functions to get what they want. :-)
>
> -n
>

IMHO, "point[ing] out that there is another definition some people might be
expecting instead, and explain[ing] how those people can use the existing
functions to get what they want" should be a requirement for the docstring
("Notes" section), not merely worth "extra bonus points."  But then I'm
not, presently, in a position to edit the docstring myself, so that's just
MHO.

IAE, I found what appears to me to be another "vote" for the extant
docstring: Box & Jenkins, 1976, "Time Series Analysis: Forecasting and
Control," Holden-Day, Oakland, pg. 374.  Perhaps a "switch" (with a default
value that maintains current definition, so that extant uses would not
require a code change) c/should be added to the function signature so that
users can get easily get what they want?

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20131010/57f83d6c/attachment.html>