Skip to content

Commit 9ec6407

Browse files
jklymakrcomer
jklymak
and
rcomer
committed
DOC: fix levels in user/explain/figure
Co-authored-by: Ruth Comer <[email protected]>
1 parent f588d2b commit 9ec6407

File tree

6 files changed

+664
-599
lines changed

6 files changed

+664
-599
lines changed

‎galleries/users_explain/artists/artist_intro.rst‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
.. _users_artists:
2+
3+
Introduction to Artists
4+
-----------------------
5+
6+
Almost all objects you interact with on a Matplotlib plot are called "Artist"
7+
(and are subclasses of the `.Artist` class). :doc:`Figure <../figure/index>`
8+
and :doc:`Axes <../axes/index>` are Artists, and generally contain :doc:`Axis
9+
<../axis/index>` Artists and Artists that contain data or annotation
10+
information.
11+
12+
13+
Creating Artists
14+
~~~~~~~~~~~~~~~~
15+
16+
Usually we do not instantiate Artists directly, but rather use a plotting
17+
method on `~.axes.Axes`. Some examples of plotting methods and the Artist
18+
object they create is given below:
19+
20+
========================================= =================
21+
Axes helper method Artist
22+
========================================= =================
23+
`~.axes.Axes.annotate` - text annotations `.Annotation`
24+
`~.axes.Axes.bar` - bar charts `.Rectangle`
25+
`~.axes.Axes.errorbar` - error bar plots `.Line2D` and
26+
`.Rectangle`
27+
`~.axes.Axes.fill` - shared area `.Polygon`
28+
`~.axes.Axes.hist` - histograms `.Rectangle`
29+
`~.axes.Axes.imshow` - image data `.AxesImage`
30+
`~.axes.Axes.legend` - Axes legend `.Legend`
31+
`~.axes.Axes.plot` - xy plots `.Line2D`
32+
`~.axes.Axes.scatter` - scatter charts `.PolyCollection`
33+
`~.axes.Axes.text` - text `.Text`
34+
========================================= =================
35+
36+
As an example, we can save the Line2D Artist returned from `.axes.Axes.plot`:
37+
38+
.. sourcecode:: ipython
39+
40+
In [209]: import matplotlib.pyplot as plt
41+
In [210]: import matplotlib.artist as martist
42+
In [211]: import numpy as np
43+
44+
In [212]: fig, ax = plt.subplots()
45+
In [213]: x, y = np.random.rand(2, 100)
46+
In [214]: lines = ax.plot(x, y, '-', label='example')
47+
In [215]: print(lines)
48+
[<matplotlib.lines.Line2D at 0xd378b0c>]
49+
50+
Note that ``plot`` returns a _list_ of lines because you can pass in multiple x,
51+
y pairs to plot. The line has been added to the Axes, and we can retrieve the
52+
Artist via `~.Axes.get_lines()`:
53+
54+
.. sourcecode:: ipython
55+
56+
In [216]: print(ax.get_lines())
57+
<a list of 1 Line2D objects>
58+
In [217]: print(ax.get_lines()[0])
59+
Line2D(example)
60+
61+
Changing Artist properties
62+
~~~~~~~~~~~~~~~~~~~~~~~~~~
63+
64+
Getting the ``lines`` object gives us access to all the properties of the
65+
Line2D object. So if we want to change the *linewidth* after the fact, we can do so using `.Artist.set`.
66+
67+
.. plot::
68+
:include-source:
69+
70+
fig, ax = plt.subplots(figsize=(4, 2.5))
71+
x = np.arange(0, 13, 0.2)
72+
y = np.sin(x)
73+
lines = ax.plot(x, y, '-', label='example', linewidth=0.2, color='blue')
74+
lines[0].set(color='green', linewidth=2)
75+
76+
We can interrogate the full list of settable properties with
77+
`matplotlib.artist.getp`:
78+
79+
.. sourcecode:: ipython
80+
81+
In [218]: martist.getp(lines[0])
82+
agg_filter = None
83+
alpha = None
84+
animated = False
85+
antialiased or aa = True
86+
bbox = Bbox(x0=0.004013842290585101, y0=0.013914221641967...
87+
children = []
88+
clip_box = TransformedBbox( Bbox(x0=0.0, y0=0.0, x1=1.0, ...
89+
clip_on = True
90+
clip_path = None
91+
color or c = blue
92+
dash_capstyle = butt
93+
dash_joinstyle = round
94+
data = (array([0.91377845, 0.58456834, 0.36492019, 0.0379...
95+
drawstyle or ds = default
96+
figure = Figure(550x450)
97+
fillstyle = full
98+
gapcolor = None
99+
gid = None
100+
in_layout = True
101+
label = example
102+
linestyle or ls = -
103+
linewidth or lw = 2.0
104+
marker = None
105+
markeredgecolor or mec = blue
106+
markeredgewidth or mew = 1.0
107+
markerfacecolor or mfc = blue
108+
markerfacecoloralt or mfcalt = none
109+
markersize or ms = 6.0
110+
markevery = None
111+
mouseover = False
112+
path = Path(array([[0.91377845, 0.51224793], [0.58...
113+
path_effects = []
114+
picker = None
115+
pickradius = 5
116+
rasterized = False
117+
sketch_params = None
118+
snap = None
119+
solid_capstyle = projecting
120+
solid_joinstyle = round
121+
tightbbox = Bbox(x0=70.4609002763619, y0=54.321277798941786, x...
122+
transform = CompositeGenericTransform( TransformWrapper( ...
123+
transformed_clip_path_and_affine = (None, None)
124+
url = None
125+
visible = True
126+
window_extent = Bbox(x0=70.4609002763619, y0=54.321277798941786, x...
127+
xdata = [0.91377845 0.58456834 0.36492019 0.03796664 0.884...
128+
xydata = [[0.91377845 0.51224793] [0.58456834 0.9820474 ] ...
129+
ydata = [0.51224793 0.9820474 0.24469912 0.61647032 0.483...
130+
zorder = 2
131+
132+
Note most Artists also have a distinct list of setters; e.g.
133+
`.Line2D.set_color` or `.Line2D.set_linewidth`.
134+
135+
Changing Artist data
136+
~~~~~~~~~~~~~~~~~~~~
137+
138+
In addition to styling properties like *color* and *linewidth*, the Line2D
139+
object has a *data* property. You can set the data after the line has been
140+
created using `.Line2D.set_data`. This is often used for Animations, where the
141+
same line is shown evolving over time (see :doc:`../animations/index`)
142+
143+
.. plot::
144+
:include-source:
145+
146+
fig, ax = plt.subplots(figsize=(4, 2.5))
147+
x = np.arange(0, 13, 0.2)
148+
y = np.sin(x)
149+
lines = ax.plot(x, y, '-', label='example')
150+
lines[0].set_data([x, np.cos(x)])
151+
152+
Manually adding Artists
153+
~~~~~~~~~~~~~~~~~~~~~~~
154+
155+
Not all Artists have helper methods, or you may want to use a low-level method
156+
for some reason. For example the `.patches.Circle` Artist does not have a
157+
helper, but we can still create and add to an Axes using the
158+
`.axes.Axes.add_artist` method:
159+
160+
.. plot::
161+
:include-source:
162+
163+
import matplotlib.patches as mpatches
164+
165+
fig, ax = plt.subplots(figsize=(4, 2.5))
166+
circle = mpatches.Circle((0.5, 0.5), 0.25, ec="none")
167+
ax.add_artist(circle)
168+
clipped_circle = mpatches.Circle((1, 0.5), 0.125, ec="none", facecolor='C1')
169+
ax.add_artist(clipped_circle)
170+
ax.set_aspect(1)
171+
172+
The Circle takes the center and radius of the Circle as arguments to its
173+
constructor; optional arguments are passed as keyword arguments.
174+
175+
Note that when we add an Artist manually like this, it doesn't necessarily
176+
adjust the axis limits like most of the helper methods do, so the Artists can
177+
be clipped, as is the case above for the ``clipped_circle`` patch.
178+
179+
See :ref:`artist_reference` for other patches.
180+
181+
Removing Artists
182+
~~~~~~~~~~~~~~~~
183+
184+
Sometimes we want to remove an Artist from a figure without re-specifying the
185+
whole figure from scratch. Most Artists have a usable *remove* method that
186+
will remove the Artist from its Axes list. For instance ``lines[0].remove()``
187+
would remove the *Line2D* artist created in the example above.

‎galleries/users_explain/artists/index.rst‎

Lines changed: 11 additions & 187 deletions
Original file line numberDiff line numberDiff line change
@@ -1,200 +1,24 @@
1-
.. _users_artists:
2-
3-
Using Artists
4-
-------------
1+
+++++++
2+
Artists
3+
+++++++
54

65
Almost all objects you interact with on a Matplotlib plot are called "Artist"
76
(and are subclasses of the `.Artist` class). :doc:`Figure <../figure/index>`
87
and :doc:`Axes <../axes/index>` are Artists, and generally contain :doc:`Axis
98
<../axis/index>` Artists and Artists that contain data or annotation
109
information.
1110

11+
.. toctree::
12+
:maxdepth: 2
1213

13-
Creating Artists
14-
~~~~~~~~~~~~~~~~
15-
16-
Usually we do not instantiate Artists directly, but rather use a plotting
17-
method on `~.axes.Axes`. Some examples of plotting methods and the Artist
18-
object they create is given below:
19-
20-
========================================= =================
21-
Axes helper method Artist
22-
========================================= =================
23-
`~.axes.Axes.annotate` - text annotations `.Annotation`
24-
`~.axes.Axes.bar` - bar charts `.Rectangle`
25-
`~.axes.Axes.errorbar` - error bar plots `.Line2D` and
26-
`.Rectangle`
27-
`~.axes.Axes.fill` - shared area `.Polygon`
28-
`~.axes.Axes.hist` - histograms `.Rectangle`
29-
`~.axes.Axes.imshow` - image data `.AxesImage`
30-
`~.axes.Axes.legend` - Axes legend `.Legend`
31-
`~.axes.Axes.plot` - xy plots `.Line2D`
32-
`~.axes.Axes.scatter` - scatter charts `.PolyCollection`
33-
`~.axes.Axes.text` - text `.Text`
34-
========================================= =================
35-
36-
As an example, we can save the Line2D Artist returned from `.axes.Axes.plot`:
37-
38-
.. sourcecode:: ipython
39-
40-
In [209]: import matplotlib.pyplot as plt
41-
In [210]: import matplotlib.artist as martist
42-
In [211]: import numpy as np
43-
44-
In [212]: fig, ax = plt.subplots()
45-
In [213]: x, y = np.random.rand(2, 100)
46-
In [214]: lines = ax.plot(x, y, '-', label='example')
47-
In [215]: print(lines)
48-
[<matplotlib.lines.Line2D at 0xd378b0c>]
49-
50-
Note that ``plot`` returns a _list_ of lines because you can pass in multiple x,
51-
y pairs to plot. The line has been added to the Axes, and we can retrieve the
52-
Artist via `~.Axes.get_lines()`:
53-
54-
.. sourcecode:: ipython
55-
56-
In [216]: print(ax.get_lines())
57-
<a list of 1 Line2D objects>
58-
In [217]: print(ax.get_lines()[0])
59-
Line2D(example)
60-
61-
Changing Artist properties
62-
~~~~~~~~~~~~~~~~~~~~~~~~~~
63-
64-
Getting the ``lines`` object gives us access to all the properties of the
65-
Line2D object. So if we want to change the *linewidth* after the fact, we can do so using `.Artist.set`.
66-
67-
.. plot::
68-
:include-source:
69-
70-
fig, ax = plt.subplots(figsize=(4, 2.5))
71-
x = np.arange(0, 13, 0.2)
72-
y = np.sin(x)
73-
lines = ax.plot(x, y, '-', label='example', linewidth=0.2, color='blue')
74-
lines[0].set(color='green', linewidth=2)
75-
76-
We can interrogate the full list of settable properties with
77-
`matplotlib.artist.getp`:
78-
79-
.. sourcecode:: ipython
80-
81-
In [218]: martist.getp(lines[0])
82-
agg_filter = None
83-
alpha = None
84-
animated = False
85-
antialiased or aa = True
86-
bbox = Bbox(x0=0.004013842290585101, y0=0.013914221641967...
87-
children = []
88-
clip_box = TransformedBbox( Bbox(x0=0.0, y0=0.0, x1=1.0, ...
89-
clip_on = True
90-
clip_path = None
91-
color or c = blue
92-
dash_capstyle = butt
93-
dash_joinstyle = round
94-
data = (array([0.91377845, 0.58456834, 0.36492019, 0.0379...
95-
drawstyle or ds = default
96-
figure = Figure(550x450)
97-
fillstyle = full
98-
gapcolor = None
99-
gid = None
100-
in_layout = True
101-
label = example
102-
linestyle or ls = -
103-
linewidth or lw = 2.0
104-
marker = None
105-
markeredgecolor or mec = blue
106-
markeredgewidth or mew = 1.0
107-
markerfacecolor or mfc = blue
108-
markerfacecoloralt or mfcalt = none
109-
markersize or ms = 6.0
110-
markevery = None
111-
mouseover = False
112-
path = Path(array([[0.91377845, 0.51224793], [0.58...
113-
path_effects = []
114-
picker = None
115-
pickradius = 5
116-
rasterized = False
117-
sketch_params = None
118-
snap = None
119-
solid_capstyle = projecting
120-
solid_joinstyle = round
121-
tightbbox = Bbox(x0=70.4609002763619, y0=54.321277798941786, x...
122-
transform = CompositeGenericTransform( TransformWrapper( ...
123-
transformed_clip_path_and_affine = (None, None)
124-
url = None
125-
visible = True
126-
window_extent = Bbox(x0=70.4609002763619, y0=54.321277798941786, x...
127-
xdata = [0.91377845 0.58456834 0.36492019 0.03796664 0.884...
128-
xydata = [[0.91377845 0.51224793] [0.58456834 0.9820474 ] ...
129-
ydata = [0.51224793 0.9820474 0.24469912 0.61647032 0.483...
130-
zorder = 2
131-
132-
Note most Artists also have a distinct list of setters; e.g.
133-
`.Line2D.set_color` or `.Line2D.set_linewidth`.
134-
135-
Changing Artist data
136-
~~~~~~~~~~~~~~~~~~~~
137-
138-
In addition to styling properties like *color* and *linewidth*, the Line2D
139-
object has a *data* property. You can set the data after the line has been
140-
created using `.Line2D.set_data`. This is often used for Animations, where the
141-
same line is shown evolving over time (see :doc:`../animations/index`)
142-
143-
.. plot::
144-
:include-source:
145-
146-
fig, ax = plt.subplots(figsize=(4, 2.5))
147-
x = np.arange(0, 13, 0.2)
148-
y = np.sin(x)
149-
lines = ax.plot(x, y, '-', label='example')
150-
lines[0].set_data([x, np.cos(x)])
151-
152-
Manually adding Artists
153-
~~~~~~~~~~~~~~~~~~~~~~~
154-
155-
Not all Artists have helper methods, or you may want to use a low-level method
156-
for some reason. For example the `.patches.Circle` Artist does not have a
157-
helper, but we can still create and add to an Axes using the
158-
`.axes.Axes.add_artist` method:
159-
160-
.. plot::
161-
:include-source:
162-
163-
import matplotlib.patches as mpatches
164-
165-
fig, ax = plt.subplots(figsize=(4, 2.5))
166-
circle = mpatches.Circle((0.5, 0.5), 0.25, ec="none")
167-
ax.add_artist(circle)
168-
clipped_circle = mpatches.Circle((1, 0.5), 0.125, ec="none", facecolor='C1')
169-
ax.add_artist(clipped_circle)
170-
ax.set_aspect(1)
171-
172-
The Circle takes the center and radius of the Circle as arguments to its
173-
constructor; optional arguments are passed as keyword arguments.
174-
175-
Note that when we add an Artist manually like this, it doesn't necessarily
176-
adjust the axis limits like most of the helper methods do, so the Artists can
177-
be clipped, as is the case above for the ``clipped_circle`` patch.
178-
179-
See :ref:`artist_reference` for other patches.
180-
181-
Removing Artists
182-
~~~~~~~~~~~~~~~~
183-
184-
Sometimes we want to remove an Artist from a figure without re-specifying the
185-
whole figure from scratch. Most Artists have a usable *remove* method that
186-
will remove the Artist from its Axes list. For instance ``lines[0].remove()``
187-
would remove the *Line2D* artist created in the example above.
188-
189-
More details
190-
~~~~~~~~~~~~
14+
artist_intro
19115

19216
.. toctree::
19317
:maxdepth: 1
19418

195-
Concept: Automated color cycle <color_cycle>
196-
Concept: optimizing Artists for performance <performance>
197-
Concept: Paths <paths>
198-
Concept: Path effects guide <patheffects_guide>
199-
In Depth: understanding the extent keyword argument of imshow <imshow_extent>
19+
Automated color cycle <color_cycle>
20+
Optimizing Artists for performance <performance>
21+
Paths <paths>
22+
Path effects guide <patheffects_guide>
23+
Understanding the extent keyword argument of imshow <imshow_extent>
20024
transforms_tutorial

0 commit comments

Comments
 (0)