BUG: Undocumented, Inconsistent matplotlib figure usage (Series.hist vs Series.plot.hist)

[EmperorArthur]

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• (optional) I have confirmed this bug exists on the master branch of pandas.

---

Note: Please read this guide detailing how to provide the necessary information for us to reproduce your bug.

Code Sample, a copy-pastable example

# Your code here
from pandas import DataFrame
import matplotlib.pyplot as plt

d = DataFrame({'y1':[0,1,2,3], 'y2':[3,4,5,6]}, index=[0,1,2,3])

# A new matplotlib figure is created
print(plt.gcf().number)
d.hist()
print(plt.gcf().number)  # new figure is created, current matplotlib figure is the new one

# Can NOT assign a figure to a dataframe plot
figure = plt.figure()
print(figure.number)
print(plt.gcf().number)
d.hist(figure=figure)  # Throws an exception
print(plt.gcf().number)  # new figure is still created! current matplotlib figure is the new one

# Can assign a figure to a Series histogram
figure1 = plt.figure()
figure2 = plt.figure()  # Current figure is always the last one created
print(figure1.number)
print(figure2.number)
print(plt.gcf().number)
d['y1'].hist(figure=figure1)
print(plt.gcf().number)  # Current figure stays the same
figure1.show() # This works

# Can NOT assign a figure to a Series histogram when using the .plot CachedAccessor
# However, it does not create a new figure
figure1 = plt.figure()
figure2 = plt.figure()  # Current figure is always the last one created
print(figure1.number)
print(figure2.number)
print(plt.gcf().number)
d['y1'].plot.hist(figure=figure1)  # Throws an exception!
print(plt.gcf().number)  # Current figure stays the same

Problem description

It is currently impossible to assign a plot of a DataFrame to an existing figure. The functionality is just broken.

The API to set a Series to an existing figure is almost completely broken (with the exception of the direct hist function).
There is a workaround in setting the global current figure plt.figure(old_figure.number), but that does not work if plt.Figure() is used.

Expected Output

All three examples accept the figure= argument, and use it.

Output of pd.show_versions()

INSTALLED VERSIONS

commit : db08276
python : 3.8.5.final.0
python-bits : 64
OS : Linux
OS-release : 5.4.0-51-generic
Version : #56-Ubuntu SMP Mon Oct 5 14:28:49 UTC 2020
machine : x86_64
processor : x86_64
byteorder : little
LC_ALL : None
LANG : en_US.UTF-8
LOCALE : en_US.UTF-8
pandas : 1.1.3
numpy : 1.19.2
pytz : 2020.1
dateutil : 2.8.1
pip : 20.0.2
setuptools : 44.0.0
Cython : None
pytest : None
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : None
lxml.etree : None
html5lib : 1.0.1
pymysql : None
psycopg2 : 2.8.6 (dt dec pq3 ext lo64)
jinja2 : 2.11.2
IPython : None
pandas_datareader: None
bs4 : None
bottleneck : None
fsspec : 0.8.4
fastparquet : None
gcsfs : None
matplotlib : 3.3.2
numexpr : None
odfpy : None
openpyxl : 3.0.5
pandas_gbq : None
pyarrow : None
pytables : None
pyxlsb : None
s3fs : None
scipy : 1.5.3
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlwt : None
numba : None

[EmperorArthur]

I have examined the issue further.

It looks like Series.hist is using hist_series directly, which bypasses all the logic which is causing the problem.

The issue with DataFrame vs Series is that series plots always set reuse_plot=True. I have confirmed that that option allows the work around to work for DataFrame plots as well. Though why Series plots get special treatment is a mystery. I suggest removing that special behavior, or at least documenting the default as different and allowing someone to manually set it to False.

The main problem is the matplotlib back-end plot function only handles "reuse_plot", and can't handle the "figure" argument.

[rhshadrach]

Thanks for raising this issue. Seems like there are some improvements to be made here, would you be interested in submitting a PR to fix?

[EmperorArthur]

I may be able to, but without approval, all code I write on company time belongs to the company...

So, I either have to get approval, or work on it in my extremely limited spare time.