pyplot.hist: normalization fails

[khyox]

Matplotlib 1.5.1 under python 3.5.1.
The provided example for pyplot.hist is not working as expected for different mu and sigma values:

"""
Demo of the histogram (hist) function with a few features.

In addition to the basic histogram, this demo shows a few optional features:

    * Setting the number of data bins
    * The ``normed`` flag, which normalizes bin heights so that the integral of
      the histogram is 1. The resulting histogram is a probability density.
    * Setting the face color of the bars
    * Setting the opacity (alpha value).

"""
import numpy as np
import matplotlib.mlab as mlab
import matplotlib.pyplot as plt


# example data
mu = 0.5*5  # mean of distribution
sigma = 0.1*5  # standard deviation of distribution
x = mu + sigma * np.random.randn(10000)

num_bins = 50
# the histogram of the data
n, bins, patches = plt.hist(x, num_bins, normed=1, facecolor='green', alpha=0.5)
# add a 'best fit' line
y = mlab.normpdf(bins, mu, sigma)
plt.plot(bins, y, 'r--')
plt.xlabel('Smarts')
plt.ylabel('Probability')
plt.title(r'Normed histogram of IQ: $\mu=%f$, $\sigma=%f$' % (mu, sigma))

# Tweak spacing to prevent clipping of ylabel
plt.subplots_adjust(left=0.15)
plt.show()

If the parameters mu and sigma are reduced to:

mu = 0.5*2  # mean of distribution
sigma = 0.1*2  # standard deviation of distribution

the plot becomes even more clearly unnormalized:

This fail with normalization also happens for non-gaussian datasets.

[jenshnielsen]

Are you sure that you are interpreting the normalization correctly? It normalizes the area under the curve not the sum of the counts. See #6353 for a similar issue.
I haven't done an independent calculation of the normalization but the area under the curve in the last example is roughly (drawing a triangle around the data) 1*2*(0.5) = 1 so I don't see how this is clearly not normalized.

[khyox]

@jenshnielsen Thank you very much for your fast and useful reply. OMG, I was clearly misinterpreting the normalization despite all the comments. I took for granted the approach in which the normalized count is the count in a class divided by the total number of observations. Further away my slip, I suggest to improve the web documentation of pyplot.hist in two ways:

• An improved explanation for the normalization factor, so that it clearly shows that the normalized count is the count in the class divided by the number of observations times the class width. I think that (n/(len(x)dbin)` (literally) is not very clear in that sense.
• And, please, in the provided example in the doc replace:

plt.ylabel('Probability')

with:

plt.ylabel('Probability Density')

Thanks again!

[tacaswell]

@khyox Can you open up a pull request making those changes to the documentation?

[khyox]

@tacaswell Of course, Thomas, and very sorry for not having done it yet (about to travel to Japan for the 1st time and a bit bewildered... 👾).

[khyox]

PR ready! 📦