DOC: normalizing histograms

jklymak · jklymak · commit aa52a1df86a9 · 2023-12-03T19:51:55.000-08:00
diff --git a/galleries/examples/statistics/histogram_normalization.py b/galleries/examples/statistics/histogram_normalization.py
@@ -98,12 +98,11 @@
 # and (``np.sum(density * np.diff(bins)) == 1``).
 #
 # This normalization is how `probability density functions
-# <https://en.wikipedia.org/wiki/Probability_density_function>`_ are
-# defined in statistics.  If :math:`X` is a random variable on :math:`x`, then
-# :math:`f_X` is is the probability density function if :math:`P[a<X<b] =
-# \int_a^b f_X dx`. Note that if the units of x are Volts (for instance), then
-# the units of :math:`f_X` are :math:`V^{-1}` or probability per change in
-# voltage.
+# <https://en.wikipedia.org/wiki/Probability_density_function>`_ are defined in
+# statistics.  If :math:`X` is a random variable on :math:`x`, then :math:`f_X`
+# is is the probability density function if :math:`P[a<X<b] = \int_a^b f_X dx`.
+# If the units of x are Volts, then the units of :math:`f_X` are :math:`V^{-1}`
+# or probability per change in voltage.
 #
 # The usefulness of this normalization is a little more clear when we draw from
 # a known distribution and try to compare with theory.  So, choose 1000 points
@@ -159,10 +158,11 @@
 ax['True'].legend(fontsize='small')
 
 # %%
+
 # Sometimes people want to normalize so that the sum of counts is one.  This is
-# _not_ done with the *density* kwarg, but instead we can set the *weights* to
-# 1/N.  Note, however, that the amplitude of the histogram still depends on
-# width of the bins
+# not done with the *density* kwarg, but rather we can get this effects if we
+# set the *weights* to 1/N.  Note, however, that the amplitude of the histogram
+# still depends on width of the bins:
 
 fig, ax = plt.subplots(layout='constrained', figsize=(3.5, 3))
 
@@ -176,7 +176,8 @@
 
 # %%
 # The true value of normalizing is if you do want to compare two distributions
-# that have different sized populations:
+# that have different sized populations.  Here we compare the distribution of
+# ``xdata`` with a population of 1000, and ``xdata2`` with 100 members.
 
 xdata2 = rng.normal(size=100)
 
