[Numpy-discussion] Would like to patch docstring for numpy.random.normal

Daniel Sank sank.daniel at gmail.com
Thu Feb 26 00:41:50 EST 2015


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20150225/ade4702e/attachment.html>


More information about the NumPy-Discussion mailing list