Would like to patch docstring for numpy.random.normal
Dear numpy users, I would like to clarify the docstring for numpy.random.normal. I submitted a patch but it was rejected because it breaks the tests. Unfortunately, the development workflow page does not explain how to run the tests (in fact it doesn't mention them at all). I am therefore writing to discuss my proposed change and find out how to run the tests so that I can make it compatible with the existing code. The current form of the docstring for numpy.random.normal is as follows: """ normal(loc=0.0, scale=1.0, size=None) <snip> Parameters ---------- loc : float Mean ("centre") of the distribution. scale : float Standard deviation (spread or "width") of the distribution. size : tuple of ints Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. <snip> Notes ----- The probability density for the Gaussian distribution is .. math:: p(x) = \frac{1}{\sqrt{ 2 \pi \sigma^2 }} e^{ - \frac{ (x - \mu)^2 } {2 \sigma^2} }, where :math:`\mu` is the mean and :math:`\sigma` the standard deviation. The square of the standard deviation, :math:`\sigma^2`, is called the variance. """ It seems unnecessarily convoluted to name the input arguments "loc" and "scale", then immediately define them as the "mean" and "standard deviation" in the Parameters section, and then again rename them as "mu" and "sigma" in the written formula. I propose to simply change the argument names to "mean" and "sigma" to improve consistency. I tried fixing this via a pull request [1] but it was closed because my change broke the tests. Unfortunately, the development workflow section of the web page doesn't explain how to run the tests (in fact it doesn't even mention them). How can I make the proposed change without breaking the tests, or equivalently how do I find out how to run the tests myself so I can find an acceptable way of making the change on my own? [1] https://github.com/numpy/numpy/pull/5607#issuecomment-76114282 -- Daniel Sank
Daniel Sank <sank.daniel@gmail.com> wrote:
It seems unnecessarily convoluted to name the input arguments "loc" and "scale", then immediately define them as the "mean" and "standard deviation" in the Parameters section, and then again rename them as "mu" and "sigma" in the written formula. I propose to simply change the argument names to "mean" and "sigma" to improve consistency.
Change the name of keyword arguments? This would be evil.
I feel your pain. Making it worse, numpy.random.lognormal takes "mean" and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up. On Tue, Mar 3, 2015 at 9:59 PM, Daniel Sank <sank.daniel@gmail.com> wrote:
Sturia,
Change the name of keyword arguments? This would be evil.
Yes, I see this now. It is really a shame these were defined as keyword arguments. I've shown the docstring to a few people and so far they all agree that it is unnecessarily convoluted.
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Mon, Mar 9, 2015 at 2:34 PM, Paul Hobson <pmhobson@gmail.com> wrote:
I feel your pain. Making it worse, numpy.random.lognormal takes "mean" and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up.
There is a numpy 2.0 milestone ;) <snip> Chuck
On Mon, Mar 9, 2015 at 4:33 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Mon, Mar 9, 2015 at 2:34 PM, Paul Hobson <pmhobson@gmail.com> wrote:
I feel your pain. Making it worse, numpy.random.lognormal takes "mean" and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up.
There is a numpy 2.0 milestone ;)
Is it worth submitting PRs against the existing 2.X branch or is that so far away that the can should be kicked down the road? -Paul
On Mar 10, 2015 11:15 AM, "Paul Hobson" <pmhobson@gmail.com> wrote:
On Mon, Mar 9, 2015 at 4:33 PM, Charles R Harris <
charlesr.harris@gmail.com> wrote:
On Mon, Mar 9, 2015 at 2:34 PM, Paul Hobson <pmhobson@gmail.com> wrote:
I feel your pain. Making it worse, numpy.random.lognormal takes "mean"
and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up.
There is a numpy 2.0 milestone ;)
Is it worth submitting PRs against the existing 2.X branch or is that so far away that the can should be kicked down the road?
Not sure what you mean by "the existing 2.X branch" (does such a thing exist somewhere?), but yeah, don't submit PRs like that. Best case they'd bit rot before we ever get around to 2.0, worst case 2.0 may never happen. (What, you liked python 2 -> 3 so much you want to go through that again?)
On Di, 2015-03-10 at 11:22 -0700, Nathaniel Smith wrote:
On Mar 10, 2015 11:15 AM, "Paul Hobson" <pmhobson@gmail.com> wrote:
On Mon, Mar 9, 2015 at 4:33 PM, Charles R Harris
On Mon, Mar 9, 2015 at 2:34 PM, Paul Hobson <pmhobson@gmail.com>
wrote:
I feel your pain. Making it worse, numpy.random.lognormal takes
"mean" and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up.
There is a numpy 2.0 milestone ;)
Is it worth submitting PRs against the existing 2.X branch or is
<charlesr.harris@gmail.com> wrote: that so far away that the can should be kicked down the road?
Not sure what you mean by "the existing 2.X branch" (does such a thing exist somewhere?), but yeah, don't submit PRs like that. Best case they'd bit rot before we ever get around to 2.0, worst case 2.0 may never happen. (What, you liked python 2 -> 3 so much you want to go through that again?)
We could try to maintain a list of things like this for others like blaze to not fall into the same pits. But then I this is likely not quite of that caliber ;).
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
On Tue, Mar 10, 2015 at 11:22 AM, Nathaniel Smith <njs@pobox.com> wrote:
On Mar 10, 2015 11:15 AM, "Paul Hobson" <pmhobson@gmail.com> wrote:
On Mon, Mar 9, 2015 at 4:33 PM, Charles R Harris <
charlesr.harris@gmail.com> wrote:
On Mon, Mar 9, 2015 at 2:34 PM, Paul Hobson <pmhobson@gmail.com> wrote:
I feel your pain. Making it worse, numpy.random.lognormal takes "mean"
and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up.
There is a numpy 2.0 milestone ;)
Is it worth submitting PRs against the existing 2.X branch or is that so far away that the can should be kicked down the road?
Not sure what you mean by "the existing 2.X branch" (does such a thing exist somewhere?), but yeah, don't submit PRs like that. Best case they'd bit rot before we ever get around to 2.0, worst case 2.0 may never happen. (What, you liked python 2 -> 3 so much you want to go through that again?)
It's been a while, but last time I build numpy from the master on github, numpy.__version__ came back as 2.dev or something like that. So I always assumed there was a 2.X branch. It's been a while since I've built numpy, but clearly I'm mistaken. -p
On 09/03/15 21:34, Paul Hobson wrote:
I feel your pain. Making it worse, numpy.random.lognormal takes "mean" and "sigma" as input. If there's ever a backwards incompatible release, I hope these things will be cleared up.
The question is how... The fix is obvious, but the consequences are unacceptable. Sturla
participants (6)
-
Charles R Harris -
Daniel Sank -
Nathaniel Smith -
Paul Hobson -
Sebastian Berg -
Sturla Molden