On 11.10.2013, at 01:19, Julian Taylor jtaylor.deb...@googlemail.com wrote:
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?
As pointed out in another post in this thread, there are now at least
three different definitions of correlation which are in use in different
disciplines of science and engineering:
Numpy code:
z_numpyCode[k] = sum_n a[n+k] * conj(v[n])
Numpy docs:
z_numpyDoc[k] = sum_n a[n] * conj(v[n+k])
= sum_n a[n-k] * conj(v[n])
= z_numpyCode[-k]
Wolfram Mathworld:
z_mmca[k] = sum_n conj(a[n]) * v[n+k]
= conj( sum_n a[n] * conj(v[n+k]) )
= conj( z_numpyDoc[k] )
= conj( z_numpyCode[-k] )
I'm sure there are even more if you search long enough. But shouldn't
the primary objective be to bring the docs in line with the code (which
is definitely not broken)? It took me 2 days of debugging my
code recently only to discover that numpy correlate() was calculating a
different correlation than the docs said.
I can try to come up with a proposal for the docs. Could anyone point me
to where I can find the docs? I can clone the numpy repo, however, I'm
not a numpy developer.
yes we should only change the documentation to match the (hopefully
correct) code.
the documentation is in the docstring of the correlate function in
numpy/core/numeric.py line 819
___
Ok, corrected the docstring, mentioning one alternative definition of
correlation. Pull request filed: https://github.com/numpy/numpy/pull/3913.
Bernhard
___
NumPy-Discussion mailing list
NumPy-Discussion@scipy.org
http://mail.scipy.org/mailman/listinfo/numpy-discussion
