@@ -6399,23 +6399,33 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
63996399 orientation = 'vertical' , rwidth = None , log = False ,
64006400 color = None , label = None , stacked = False , ** kwargs ):
64016401 """
6402- Plot a histogram.
6402+ Compute and plot a histogram.
64036403
6404- Compute and draw the histogram of *x*. The return value is a tuple
6405- (*n*, *bins*, *patches*) or ([*n0*, *n1*, ...], *bins*, [*patches0*,
6406- *patches1*, ...]) if the input contains multiple data. See the
6407- documentation of the *weights* parameter to draw a histogram of
6408- already-binned data.
6404+ This method uses `numpy.histogram` to bin the data in *x* and count the
6405+ number of values in each bin, then draws the distribution either as a
6406+ `.BarContainer` or `.Polygon`. The *bins*, *range*, *density*, and
6407+ *weights* parameters are forwarded to `numpy.histogram`.
64096408
6410- Multiple data can be provided via *x* as a list of datasets
6411- of potentially different length ([*x0*, *x1*, ...]), or as
6412- a 2D ndarray in which each column is a dataset. Note that
6413- the ndarray form is transposed relative to the list form.
6409+ If the data has already been binned and counted, use `~.bar` or
6410+ `~.stairs` to plot the distribution::
64146411
6415- Masked arrays are not supported.
6412+ counts, bins = np.histogram(x)
6413+ plt.stairs(bins, counts)
6414+
6415+ Alternatively, plot pre-computed bins and counts using ``hist()`` by
6416+ treating each bin as a single point with a weight equal to its count::
6417+
6418+ plt.hist(bins[:-1], bins, weights=counts)
64166419
6417- The *bins*, *range*, *weights*, and *density* parameters behave as in
6418- `numpy.histogram`.
6420+ The data input *x* can be a singular array, a list of datasets of
6421+ potentially different lengths ([*x0*, *x1*, ...]), or a 2D ndarray in
6422+ which each column is a dataset. Note that the ndarray form is
6423+ transposed relative to the list form. If the input is an array, then
6424+ the return value is a tuple (*n*, *bins*, *patches*); if the input is a
6425+ sequence of arrays, then the return value is a tuple
6426+ ([*n0*, *n1*, ...], *bins*, [*patches0*, *patches1*, ...]).
6427+
6428+ Masked arrays are not supported.
64196429
64206430 Parameters
64216431 ----------
@@ -6469,15 +6479,6 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
64696479 normalized, so that the integral of the density over the range
64706480 remains 1.
64716481
6472- This parameter can be used to draw a histogram of data that has
6473- already been binned, e.g. using `numpy.histogram` (by treating each
6474- bin as a single point with a weight equal to its count) ::
6475-
6476- counts, bins = np.histogram(data)
6477- plt.hist(bins[:-1], bins, weights=counts)
6478-
6479- (or you may alternatively use `~.bar()`).
6480-
64816482 cumulative : bool or -1, default: False
64826483 If ``True``, then a histogram is computed where each bin gives the
64836484 counts in that bin plus all bins for smaller values. The last bin
@@ -6578,9 +6579,9 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
65786579
65796580 Notes
65806581 -----
6581- For large numbers of bins (>1000), 'step' and 'stepfilled' can be
6582- significantly faster than 'bar' and 'barstacked'.
6583-
6582+ For large numbers of bins (>1000), plotting can be significantly faster
6583+ if *histtype* is set to 'step' or 'stepfilled' rather than 'bar' or
6584+ 'barstacked'.
65846585 """
65856586 # Avoid shadowing the builtin.
65866587 bin_range = range
0 commit comments