@@ -6415,23 +6415,33 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
64156415 orientation = 'vertical' , rwidth = None , log = False ,
64166416 color = None , label = None , stacked = False , ** kwargs ):
64176417 """
6418- Plot a histogram.
6418+ Compute and plot a histogram.
64196419
6420- Compute and draw the histogram of *x*. The return value is a tuple
6421- (*n*, *bins*, *patches*) or ([*n0*, *n1*, ...], *bins*, [*patches0*,
6422- *patches1*, ...]) if the input contains multiple data. See the
6423- documentation of the *weights* parameter to draw a histogram of
6424- already-binned data.
6420+ This method uses `numpy.histogram` to bin the data in *x* and count the
6421+ number of values in each bin, then draws the distribution either as a
6422+ `.BarContainer` or `.Polygon`. The *bins*, *range*, *density*, and
6423+ *weights* parameters are forwarded to `numpy.histogram`.
64256424
6426- Multiple data can be provided via *x* as a list of datasets
6427- of potentially different length ([*x0*, *x1*, ...]), or as
6428- a 2D ndarray in which each column is a dataset. Note that
6429- the ndarray form is transposed relative to the list form.
6425+ If the data has already been binned and counted, use `~.bar` or
6426+ `~.stairs` to plot the distribution::
64306427
6431- Masked arrays are not supported.
6428+ counts, bins = np.histogram(x)
6429+ plt.stairs(bins, counts)
6430+
6431+ Alternatively, plot pre-computed bins and counts using ``hist()`` by
6432+ treating each bin as a single point with a weight equal to its count::
6433+
6434+ plt.hist(bins[:-1], bins, weights=counts)
64326435
6433- The *bins*, *range*, *weights*, and *density* parameters behave as in
6434- `numpy.histogram`.
6436+ The data input *x* can be a singular array, a list of datasets of
6437+ potentially different lengths ([*x0*, *x1*, ...]), or a 2D ndarray in
6438+ which each column is a dataset. Note that the ndarray form is
6439+ transposed relative to the list form. If the input is an array, then
6440+ the return value is a tuple (*n*, *bins*, *patches*); if the input is a
6441+ sequence of arrays, then the return value is a tuple
6442+ ([*n0*, *n1*, ...], *bins*, [*patches0*, *patches1*, ...]).
6443+
6444+ Masked arrays are not supported.
64356445
64366446 Parameters
64376447 ----------
@@ -6485,15 +6495,6 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
64856495 normalized, so that the integral of the density over the range
64866496 remains 1.
64876497
6488- This parameter can be used to draw a histogram of data that has
6489- already been binned, e.g. using `numpy.histogram` (by treating each
6490- bin as a single point with a weight equal to its count) ::
6491-
6492- counts, bins = np.histogram(data)
6493- plt.hist(bins[:-1], bins, weights=counts)
6494-
6495- (or you may alternatively use `~.bar()`).
6496-
64976498 cumulative : bool or -1, default: False
64986499 If ``True``, then a histogram is computed where each bin gives the
64996500 counts in that bin plus all bins for smaller values. The last bin
@@ -6594,9 +6595,9 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
65946595
65956596 Notes
65966597 -----
6597- For large numbers of bins (>1000), 'step' and 'stepfilled' can be
6598- significantly faster than 'bar' and 'barstacked'.
6599-
6598+ For large numbers of bins (>1000), plotting can be significantly faster
6599+ if *histtype* is set to 'step' or 'stepfilled' rather than 'bar' or
6600+ 'barstacked'.
66006601 """
66016602 # Avoid shadowing the builtin.
66026603 bin_range = range
0 commit comments