1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
##################################
Introduction to Axes (or Subplots)
##################################
Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations.
Once an Axes is placed on a figure there are many methods that can be used to
add data to the Axes. An Axes typically has a pair of `~.axis.Axis`
Artists that define the data coordinate system, and include methods to add
annotations like x- and y-labels, titles, and legends.
.. _anatomy_local:
.. figure:: /_static/anatomy.png
:width: 80%
Anatomy of a Figure
In the picture above, the Axes object was created with ``ax = fig.subplots()``.
Everything else on the figure was created with methods on this ``ax`` object,
or can be accessed from it. If we want to change the label on the x-axis, we
call ``ax.set_xlabel('New Label')``, if we want to plot some data we call
``ax.plot(x, y)``. Indeed, in the figure above, the only Artist that is not
part of the Axes is the Figure itself, so the `.axes.Axes` class is really the
gateway to much of Matplotlib's functionality.
Note that Axes are so fundamental to the operation of Matplotlib that a lot of
material here is duplicate of that in :ref:`quick_start`.
Creating Axes
-------------
.. plot::
:include-source:
import matplotlib.pyplot as plt
import numpy as np
fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(3.5, 2.5),
layout="constrained")
# for each Axes, add an artist, in this case a nice label in the middle...
for row in range(2):
for col in range(2):
axs[row, col].annotate(f'axs[{row}, {col}]', (0.5, 0.5),
transform=axs[row, col].transAxes,
ha='center', va='center', fontsize=18,
color='darkgrey')
fig.suptitle('plt.subplots()')
Axes are added using methods on `~.Figure` objects, or via the `~.pyplot` interface. These methods are discussed in more detail in :ref:`creating_figures` and :doc:`arranging_axes`. However, for instance `~.Figure.add_axes` will manually position an Axes on the page. In the example above `~.pyplot.subplots` put a grid of subplots on the figure, and ``axs`` is a (2, 2) array of Axes, each of which can have data added to them.
There are a number of other methods for adding Axes to a Figure:
* `.Figure.add_axes`: manually position an Axes. ``fig.add_axes([0, 0, 1,
1])`` makes an Axes that fills the whole figure.
* `.pyplot.subplots` and `.Figure.subplots`: add a grid of Axes as in the example
above. The pyplot version returns both the Figure object and an array of
Axes. Note that ``fig, ax = plt.subplots()`` adds a single Axes to a Figure.
* `.pyplot.subplot_mosaic` and `.Figure.subplot_mosaic`: add a grid of named
Axes and return a dictionary of axes. For ``fig, axs =
plt.subplot_mosaic([['left', 'right'], ['bottom', 'bottom']])``,
``axs['left']`` is an Axes in the top row on the left, and ``axs['bottom']``
is an Axes that spans both columns on the bottom.
See :doc:`arranging_axes` for more detail on how to arrange grids of Axes on a
Figure.
Axes plotting methods
---------------------
Most of the high-level plotting methods are accessed from the `.axes.Axes`
class. See the API documentation for a full curated list, and
:ref:`plot_types` for examples. A basic example is `.axes.Axes.plot`:
.. plot::
:include-source:
fig, ax = plt.subplots(figsize=(4, 3))
np.random.seed(19680801)
t = np.arange(100)
x = np.cumsum(np.random.randn(100))
lines = ax.plot(t, x)
Note that ``plot`` returns a list of *lines* Artists which can subsequently be
manipulated, as discussed in :ref:`users_artists`.
A very incomplete list of plotting methods is below. Again, see :ref:`plot_types`
for more examples, and `.axes.Axes` for the full list of methods.
========================= ==================================================
:ref:`basic_plots` `~.axes.Axes.plot`, `~.axes.Axes.scatter`,
`~.axes.Axes.bar`, `~.axes.Axes.step`,
:ref:`arrays` `~.axes.Axes.pcolormesh`, `~.axes.Axes.contour`,
`~.axes.Axes.quiver`, `~.axes.Axes.streamplot`,
`~.axes.Axes.imshow`
:ref:`stats_plots` `~.axes.Axes.hist`, `~.axes.Axes.errorbar`,
`~.axes.Axes.hist2d`, `~.axes.Axes.pie`,
`~.axes.Axes.boxplot`, `~.axes.Axes.violinplot`
:ref:`unstructured_plots` `~.axes.Axes.tricontour`, `~.axes.Axes.tripcolor`
========================= ==================================================
Axes labelling and annotation
-----------------------------
Usually we want to label the Axes with an xlabel, ylabel, and title, and often we want to have a legend to differentiate plot elements. The `~.axes.Axes` class has a number of methods to create these annotations.
.. plot::
:include-source:
fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')
np.random.seed(19680801)
t = np.arange(200)
x = np.cumsum(np.random.randn(200))
y = np.cumsum(np.random.randn(200))
linesx = ax.plot(t, x, label='Random walk x')
linesy = ax.plot(t, y, label='Random walk y')
ax.set_xlabel('Time [s]')
ax.set_ylabel('Distance [km]')
ax.set_title('Random walk example')
ax.legend()
These methods are relatively straight-forward, though there are a number of :ref:`text_props` that can be set on the text objects, like *fontsize*, *fontname*, *horizontalalignment*. Legends can be much more complicated; see :ref:`legend_guide` for more details.
Note that text can also be added to axes using `~.axes.Axes.text`, and `~.axes.Axes.annotate`. This can be quite sophisticated: see :ref:`text_props` and :ref:`annotations` for more information.
Axes limits, scales, and ticking
--------------------------------
Each Axes has two (or more) `~.axis.Axis` objects, that can be accessed via :attr:`~matplotlib.axes.Axes.xaxis` and :attr:`~matplotlib.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read the API at `~.axis.Axis`. However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`.
Other important methods set the extent on the axes (`~.axes.Axes.set_xlim`, `~.axes.Axes.set_ylim`), or more fundamentally the scale of the axes. So for instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data:
.. plot::
:include-source:
fig, ax = plt.subplots(figsize=(4, 2.5), layout='constrained')
np.random.seed(19680801)
t = np.arange(200)
x = 2**np.cumsum(np.random.randn(200))
linesx = ax.plot(t, x)
ax.set_yscale('log')
ax.set_xlim([20, 180])
The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` which manually set the tick locations and optionally their labels. Minor ticks can be toggled with `~.axes.Axes.minorticks_on` or `~.axes.Axes.minorticks_off`.
Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green:
.. plot::
:include-source:
fig, ax = plt.subplots(figsize=(4, 2.5))
ax.plot(np.arange(10))
ax.tick_params(top=True, labeltop=True, color='red', axis='x',
labelcolor='green')
More fine-grained control on ticks, setting scales, and controlling the Axis can be highly customized beyond these Axes-level helpers.
Axes layout
-----------
Sometimes it is important to set the aspect ratio of a plot in data space, which we can do with `~.axes.Axes.set_aspect`:
.. plot::
:include-source:
fig, axs = plt.subplots(ncols=2, figsize=(7, 2.5), layout='constrained')
np.random.seed(19680801)
t = np.arange(200)
x = np.cumsum(np.random.randn(200))
axs[0].plot(t, x)
axs[0].set_title('aspect="auto"')
axs[1].plot(t, x)
axs[1].set_aspect(3)
axs[1].set_title('aspect=3')
|
