DOC: Updated documentation wording and examples for np.percentile.

[madphysicist]

Examples had some factual errors. Fixed up 80-char columns. Wording updated in a couple of places.

[shoyer]

should be the return value or the result rather than the return

[madphysicist]

@shoyer I have accepted all of your comments. While we are on the subject, please let me know if the following appears to be a bug or if it is just me:

>>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])
>>> np.percentile(x, (25, 75), interpolation='linear')
array([ 1.,  3.])
>>> np.percentile(x, (25, 75), interpolation='higher')
array([1, 3])
>>> np.percentile(x, (25, 75), interpolation='lower')
array([1, 3])
>>> np.percentile(x, (25, 75), interpolation='nearest')
array([1, 3])
>>> np.percentile(x, (25, 75), interpolation='midpoint')
array([ 1.5,  3.5])

Specifically, how is 'linear' ending up on an integer boundary when there are five elements in the array? How is 'midpoint' giving fractional values when 'higher' and 'lower' coincide?

[shoyer]

@madawilliams I think linear is right here -- these percentiles are exact (to within floating point precision).

I don't know what's going on with midpoint. I would look at the relevant code and check for unit tests and/or discussion when it was last changed (use git blame to figure that out).

[shoyer]

This LGTM. I'll give other folks a day or two to comment and then merge.

[madphysicist]

I did not think this was major enough to post on the mailing list. If you disagree, I will post it.

I did some research and all of the interpolation methods look correct except midpoint. Midpoint is definitely messed up in the example I gave and I have added a patch (#7129). Is there any point to opening an issue now that I have the PR?

[shoyer]

Agreed, no need to ping the mailing list for this issue or open a separate issue for midpoint now that you have a PR.

[shoyer]

Thanks!

@charris we should consider backporting this doc fix to 1.11.