Repository navigation
Recommendation for using pyplot vs OOP API #15355
Description
I would like to know if it is recommended to always use the OOP API if
matplotlib plots need to be created in a library.
The reason why I'm asking is the following: We have lots of libraries that
create matplotlib plots non-interactively if the code is run as part of a
(multi-threaded) service on a head-less system or interactively if a
console-script is started manually. For these libraries we run unit tests on
a CI server. Since we don't explicilty specify a backend (via
matplotlib.use), we either have to mock the pylot API a bit or run a fake
xserver (Xvfb) in the background to fix issues due to missing DISPLAY env
var. (On our headless systems we neither use a custom matplotlibrc nor do we
set the MATPLOTLIB_BACKEND env var. pyqt/pyside is installed on these
systems because the console scripts depend on qt libs)
The matplotlib documentation of the mpl API
(https://matplotlib.org/3.1.1/api/index.html) contains the following two
sentences:
At its core, Matplotlib is object-oriented. We recommend directly working
with the objects, if you need more control and customization of your plots.
pyplot is mainly intended for interactive plots and simple cases of
programmatic plot generation.
Do you recommend to use pyplot in our case or rather recommend us to use the OOP API
directly? Independent of the recommendation I think it makes sense to extend the docs a bit and mention
this use-case, since our use-case is probably very common.
BTW There are unfortunately very few (currently only 1:
https://matplotlib.org/gallery/api/agg_oo_sgskip.html) examples that show
how the OOP API is supposed to be used. What is missing IMO is an example
that shows how to use plotting functions both interactively and
non-interactively.
Activity
jklymak commented on Oct 1, 2019
Maybe this would be a good subject for discourse.matplotlib.org rather than the issue tracker?
ImportanceOfBeingErnest commented on Oct 1, 2019
I think this hits two important points of missing/unclear documentation and maybe even an action point for the general API:
What is meant by OOP API? I think the sentence from the documentation aims at the difference between storing objects in variables and using their methods vs. acting on the current pyplot state. E.g.
vs.
But this is probably not very clear from the documentation. Or is it?
Both use pyplot though.
The /api/agg_oo_sgskip.html example is quite useful, but maybe a bit hidden. No link to it from any of the tutorials, it seems. I'm not sure what other example there needs to be; there is also CanvasAgg demo in the user_interfaces section.
Interactive usage is underdocumented. This might be solved by DOC: Start to document interactive figures #4779. So @Thisch you might want to read through that proposed addition and give feedback if this is helpful for you.
As action item I could imagine that there should be one single example/tutorial that compares the three cases
Finally, the underlying question might be this: What do you do if you have a Figure (possibly with a FigureCanvas) and want to show it? Should it be possible to hook that figure into pyplot a posteriori? This might be part of #14024 actually(?).
jklymak commented on Oct 1, 2019
I don't think anyone meant to say that pyplot was a discouraged way to start up the backend. yes there are other ways to do it, but its by far the preferred way.
story645 commented on Dec 31, 2020
I think/hope this is addressed by #19183
story645 commented on Jun 26, 2023
@jklymak is this more or less covered in the user guide?
jklymak commented on Jun 26, 2023
I think so. Improvements can always be made, but I think we have done a fair bit of this in the intervening years.