|
1 | 1 | API Reference |
2 | 2 | ============= |
3 | 3 |
|
4 | | -When using the library you will typically create |
5 | | -:doc:`Figure <figure_api>` and :doc:`Axes <axes_api>` objects and |
6 | | -call their methods to add content and modify the appearance. |
| 4 | +Matplotlib interfaces |
| 5 | +--------------------- |
7 | 6 |
|
8 | | -- :mod:`matplotlib.figure`: axes creation, figure-level content |
9 | | -- :mod:`matplotlib.axes`: most plotting methods, Axes labels, access to axis |
10 | | - styling, etc. |
| 7 | +Matplotlib provides two different interfaces: |
11 | 8 |
|
12 | | -Example: We create a Figure ``fig`` and Axes ``ax``. Then we call |
13 | | -methods on them to plot data, add axis labels and a figure title. |
| 9 | +- **Axes interface**: create a `.Figure` and one or more `~.axes.Axes` objects |
| 10 | + (typically using `.pyplot.subplots`), then *explicitly* use methods on these objects |
| 11 | + to add data, configure limits, set labels etc. |
| 12 | +- **pyplot interface**: consists of functions in the `.pyplot` module. Figure and Axes |
| 13 | + are manipulated through these functions and are only *implicitly* present in the |
| 14 | + background. |
14 | 15 |
|
15 | | -.. plot:: |
16 | | - :include-source: |
17 | | - :align: center |
| 16 | +See :ref:`api_interfaces` for a more detailed description of both and their recommended |
| 17 | +use cases. |
18 | 18 |
|
19 | | - import matplotlib.pyplot as plt |
20 | | - import numpy as np |
| 19 | +.. grid:: 1 1 2 2 |
| 20 | + :padding: 0 0 1 1 |
21 | 21 |
|
22 | | - x = np.arange(0, 4, 0.05) |
23 | | - y = np.sin(x*np.pi) |
| 22 | + .. grid-item-card:: |
24 | 23 |
|
25 | | - fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True) |
26 | | - ax.plot(x, y) |
27 | | - ax.set_xlabel('t [s]') |
28 | | - ax.set_ylabel('S [V]') |
29 | | - ax.set_title('Sine wave') |
30 | | - fig.set_facecolor('lightsteelblue') |
| 24 | + **Axes interface** (object-based, explicit) |
| 25 | + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
31 | 26 |
|
| 27 | + API: |
32 | 28 |
|
| 29 | + - `~.pyplot.subplots`: create Figure and Axes |
| 30 | + - :mod:`~matplotlib.axes`: add data, limits, labels etc. |
| 31 | + - `.Figure`: for figure-level methods |
33 | 32 |
|
34 | | -.. _usage_patterns: |
| 33 | + .. grid-item-card:: |
35 | 34 |
|
36 | | -Usage patterns |
37 | | --------------- |
| 35 | + **pyplot interface** (function-based, implicit) |
| 36 | + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
38 | 37 |
|
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. |
| 38 | + API: |
42 | 39 |
|
| 40 | + - `matplotlib.pyplot` |
43 | 41 |
|
44 | | -The explicit API |
45 | | -^^^^^^^^^^^^^^^^ |
46 | | - |
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 | | - |
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). |
55 | | - |
56 | | -Further reading: |
57 | | - |
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) |
62 | | - |
63 | | - |
64 | | -The implicit API |
65 | | -^^^^^^^^^^^^^^^^ |
66 | | - |
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. |
71 | | - |
72 | | -`.pyplot` is mainly intended for interactive plots and simple cases of |
73 | | -programmatic plot generation. |
74 | | - |
75 | | -Further reading: |
76 | | - |
77 | | -- The `matplotlib.pyplot` function reference |
78 | | -- :ref:`pyplot_tutorial` |
79 | | -- :ref:`Pyplot examples <pyplots_examples>` |
80 | 42 |
|
81 | 43 | .. _api-index: |
82 | 44 |
|
|
0 commit comments