pandas.DataFrame: .hist() vs .plot.hist() methods

Question

On pandas.DataFrame in 0.19 there are two hist methods:

DataFrame.hist

DataFrame.plot.hist

At first I thought they were the same, but actually they take different arguments. Is one going to be deprecated in a future release, is there a different use case for each, or what's the story?

Answer 1

I don't have a definitive answer for you. One thing I noticed is that DataFrame.hist returns a list of axes objects and DataFrame.plot.hist returns only one. For example:

# Making up data
df = pd.DataFrame({'value1': np.random.normal(1, 1, 99),
                   'value2': [-1]*33 + [0]*33 + [1]*33})

df.hist()

df.plot.hist()

Answer 2

Looking at the docs, http://pandas.pydata.org/pandas-docs/version/0.17.0/generated/pandas.DataFrame.plot.hist.html and http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.hist.html, it looks like plot.hist is a function that takes a few histogram specific options but then passes on all other keyword args to plot(), while hist takes a large number of keyword args directly. I would guess that this is primarily to create a simpler, more consistent API, i.e. rather than having 15 different functions that each take a large number of kwargs, just focus on the specialized args while the rest are consistent with plot()

cf:

New in version 0.17.0: Each plot kind has a corresponding method on the DataFrame.plot accessor: df.plot(kind='line') is equivalent to df.plot.line()

In addition, the plot* functions return axes, which could be useful for chaining and other things.