The docstring of np.random.pareto (Version 1.8.0) contains multiple critical errors

[ckuehne]

The docstring of np.random.pareto (Version 1.8.0) contains multiple errors. In a nutshell np.random.pareto does not draw samples from the Pareto distribution shown under 'Notes' in the docstring. Instead it draws samples from a Lomax distribution (also stated in the docstring). However, the description in the docstring of how to convert those Lomax random variates to a Pareto distribution is wrong. Further, the examples are faulty.

More detailed:
The function np.random.pareto draws random variates from a Lomax distribution with shape a and location m'=1. To convert
those samples to a classical Pareto distribution with shape a and
location m you have to add 1 and multiply by m, instead of adding m as
stated in the docstring.

More specifically, the docstring says:
"The Lomax or Pareto II distribution is a shifted Pareto distribution. The
classical Pareto distribution can be obtained from the Lomax distribution
by adding the location parameter m, see below."

Instead, it should read "[..] by adding 1 and multiplying my m, see below."

The example at the bottom therefore should read:

a, m = 3., 1. # shape and mode
s = (np.random.pareto(a, 1000) + 1) * m

Maybe an example with m=10 makes it clearer

a, m = 3., 10. # shape and mode
s = (np.random.pareto(a, 1000) + 1) * m

Additionally, calling m the location parameter could be misleading.
For simple Pareto (Type I) distributions it is usually referred to as
the x_min or the scale parameter of the distribution. When discussing
generalized Pareto distributions m is also called the scale
parameter (a constant factor) while mu is the location (an additive
term) [1]. I assume the misleading naming could have caused some
confusion and lead to the errors described above.

Last but not least I think it might also cause confusion to call
a function 'random.pareto' while its meaning is 'shifted by -1 pareto'. :)

[1] http://en.wikipedia.org/wiki/Generalized_Pareto_distribution

[fplandes]

I stumbled on this same issue just now. It is a bit sad that it has not been fixed, since it is so simple to do, and can cause quite a large time loss.
It is enough to run the following code to realize that the current example is wrong:

import numpy as np
import matplotlib.pyplot as plt

a, m = 3., 10. # shape and mode
s = np.random.pareto(a, 1000) + m ## CURRENT, incorrect example

##a, m = 3,10 # shape and mode
##s = (np.random.pareto(a, 1000)+1.0)*m ## Correct example

count, bins, ignored = plt.hist(s, 100, normed=True)
fit = a * m * a/bins*(a+1)
plt.plot(bins, max(count) * fit/max(fit),linewidth=2, color='r')
plt.show()

The mathematics in teh example are correct, the only thing left to do is to change "s = np.random.pareto(a, 1000) + m" into "s = (np.random.pareto(a, 1000)+1)*m".

Also, one may remove the argument ",align='centered' ", which seems to have become incorrect.

[njsmith]

What needs to happen for it to be fixed, is for someone who understands the
details to write up a fix and submit it as a pull request :-)

On Tue, Jan 6, 2015 at 4:18 PM, F.P. Landes notifications@github.com
wrote:

I stumbled on this same issue just now. It is a bit sad that it has not
been fixed, since it is so simple to do, and can cause quite a large time
loss.
It is enough to run the following code to realize that the current example
is wrong:

import numpy as np
import matplotlib.pyplot as plt

a, m = 3., 10. # shape and mode
s = np.random.pareto(a, 1000) + m ## CURRENT, incorrect example

##a, m = 3,10 # shape and mode
##s = (np.random.pareto(a, 1000)+1.0)*m ## Correct example

count, bins, ignored = plt.hist(s, 100, normed=True)
fit = a * m * a/bins*(a+1)
plt.plot(bins, max(count) * fit/max(fit),linewidth=2, color='r')
plt.show()

The mathematics in teh example are correct, the only thing left to do is
to change "s = np.random.pareto(a, 1000) + m" into "s =
(np.random.pareto(a, 1000)+1)*m".

Also, one may remove the argument ",align='centered' ", which seems to
have become incorrect.

—
Reply to this email directly or view it on GitHub
#4181 (comment).

Nathaniel J. Smith
Postdoctoral researcher - Informatics - University of Edinburgh
http://vorpus.org

[fplandes]

are the webpages of the doc available ? Can I just edit the webpage and submit the new version ? If so, that's all that need to be done

[fplandes]

by available, I mean as part of the github project, so that I can make a pull (I am a noob to github but I know html)

[maniteja123]

Pareto distribution is here.
I think you can use edit option on the top to fork the repository, create a branch on your github profile, then submit pull request.

[fplandes]

thanks ! I just did it ! :)

[maniteja123]

I am not sure if it is relevant here, but if it is just documentation change, you can skip the Travis CI build. All you need to do is to add [ci skip] somewhere in the commit message.

Also the commit messages can be documented according to this.
In this case, it can be DOC: Update pareto documentation in np.random.mytrand.pyx

In case you want to close an issue, once the pull request is merged, you can add notes like closes #4181 in the commit message. Look at this.

[rgommers]

There are a few more issues pointed out than fixed in gh-5427 by @ckuehne.

• The name pareto for this function we can't change.
• The comment about calling m "scale" instead of "location" seems valid. (the +1 is loc, m in the example a scale parameter).
• The first paragraph needs an update to mention the + 1.