From eae2b7fc51a1a06e49716f7749275572129b68c2 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Mon, 18 Feb 2019 11:38:58 +0100 Subject: [PATCH] Document histogramming pre-binned data. This simple solution is slightly modified from an original idea by @mhedges. --- lib/matplotlib/axes/_axes.py | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 4400e397743a..1a04b507bea4 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -6410,10 +6410,11 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, """ Plot a histogram. - Compute and draw the histogram of *x*. The return value is a - tuple (*n*, *bins*, *patches*) or ([*n0*, *n1*, ...], *bins*, - [*patches0*, *patches1*,...]) if the input contains multiple - data. + Compute and draw the histogram of *x*. The return value is a tuple + (*n*, *bins*, *patches*) or ([*n0*, *n1*, ...], *bins*, [*patches0*, + *patches1*,...]) if the input contains multiple data. See the + documentation of the *weights* parameter to draw a histogram of + already-binned data. Multiple data can be provided via *x* as a list of datasets of potentially different length ([*x0*, *x1*, ...]), or as @@ -6487,7 +6488,16 @@ def hist(self, x, bins=None, range=None, density=None, weights=None, the weights are normalized, so that the integral of the density over the range remains 1. - Default is ``None`` + Default is ``None``. + + This parameter can be used to draw a histogram of data that has + already been binned, e.g. using `np.histogram` (by treating each + bin as a single point with a weight equal to its count) :: + + counts, bins = np.histogram(data) + plt.hist(bins[:-1], bins, weights=counts) + + (or you may alternatively use `~.bar()`). cumulative : bool, optional If ``True``, then a histogram is computed where each bin gives the