@@ -36,47 +36,51 @@ methods on them to plot data, add axis labels and a figure title.
3636Usage patterns
3737--------------
3838
39- Below we describe several common approaches to plotting with Matplotlib. See
40- :ref: `api_interfaces ` for an explanation of the trade-offs between the supported user
41- APIs.
39+ Matplotlib provides two different interfaces:
4240
41+ - Within the *Axes interface * you create a Figure and one or more Axes objects
42+ (typically using `.pyplot.subplots `). Then, you use methods on these objects to add
43+ data, configure limits, set labels etc.
44+ - The *pyplot interface * consists of functions. Figure and Axes are manipulated through
45+ these functions and are only implicitly present in the background.
4346
44- The explicit API
45- ^^^^^^^^^^^^^^^^
47+ See :ref: ` api_interfaces ` for a more detailed description of both and their recommended
48+ use cases.
4649
47- At its core, Matplotlib is an object-oriented library. We recommend directly
48- working with the objects if you need more control and customization of your
49- plots.
50+ .. grid :: 1 1 2 2
51+ :padding: 0 0 1 1
5052
51- In many cases you will create a `.Figure ` and one or more
52- `~matplotlib.axes.Axes ` using `.pyplot.subplots ` and from then on only work
53- on these objects. However, it's also possible to create `.Figure `\ s
54- explicitly (e.g. when including them in GUI applications).
53+ .. grid-item-card ::
5554
56- Further reading:
55+ **Axes interface ** (object-based, explicit)
56+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5757
58- - `matplotlib.axes.Axes ` and `matplotlib.figure.Figure ` for an overview of
59- plotting functions.
60- - Most of the :ref: `examples <examples-index >` use the object-oriented approach
61- (except for the pyplot section)
58+ API:
6259
60+ - `~.pyplot.subplots `: create Figure and Axes
61+ - :doc: `Axes </api/axes_api >` add data, limits, labels etc.
62+ - :doc: `Figure <figure_api >` for figure-level methods
6363
64- The implicit API
65- ^^^^^^^^^^^^^^^^
64+ Examples:
6665
67- `matplotlib.pyplot ` is a collection of functions that make
68- Matplotlib work like MATLAB. Each pyplot function makes some change to a
69- figure: e.g., creates a figure, creates a plotting area in a figure, plots
70- some lines in a plotting area, decorates the plot with labels, etc.
66+ - Most :ref: `examples <examples-index >` use this
7167
72- `.pyplot ` is mainly intended for interactive plots and simple cases of
73- programmatic plot generation.
68+ (except for the pyplot section)
7469
75- Further reading:
70+ .. grid-item-card ::
71+
72+ **pyplot interface ** (function-based, implicit)
73+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
74+
75+ API:
76+
77+ - `matplotlib.pyplot `
78+
79+ Examples:
80+
81+ - :ref: `pyplot_tutorial `
82+ - :ref: `Pyplot examples <pyplots_examples >`
7683
77- - The `matplotlib.pyplot ` function reference
78- - :ref: `pyplot_tutorial `
79- - :ref: `Pyplot examples <pyplots_examples >`
8084
8185.. _api-index :
8286
0 commit comments