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).