diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index da7c58428fb54..fa2766bb63d55 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -3049,21 +3049,47 @@ def box(self, by=None, **kwds): def hist(self, by=None, bins=10, **kwds): """ - Histogram + Draw one histogram of the DataFrame's columns. + + A histogram is a representation of the distribution of data. + This function groups the values of all given Series in the DataFrame + into bins, and draws all bins in only one :ref:`matplotlib.axes.Axes`. + This is useful when the DataFrame's Series are in a similar scale. Parameters ---------- - by : string or sequence + by : str or sequence, optional Column in the DataFrame to group by. - bins: integer, default 10 - Number of histogram bins to be used - `**kwds` : optional + bins : int, default 10 + Number of histogram bins to be used. + **kwds Additional keyword arguments are documented in :meth:`pandas.DataFrame.plot`. Returns ------- - axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them + axes : matplotlib.AxesSubplot histogram. + + See Also + -------- + DataFrame.hist : Draw histograms per DataFrame's Series. + Series.hist : Draw a histogram with Series' data. + + Examples + -------- + When we draw a dice 6000 times, we expect to get each value around 1000 + times. But when we draw two dices and sum the result, the distribution + is going to be quite different. A histogram illustrates those + distributions. + + .. plot:: + :context: close-figs + + >>> df = pd.DataFrame( + ... np.random.randint(1, 7, 6000), + ... columns = ['one']) + >>> df['two'] = df['one'] + np.random.randint(1, 7, 6000) + >>> ax = df.plot.hist(bins=12, alpha=0.5) """ return self(kind='hist', by=by, bins=bins, **kwds)