Introduction to Artists#

Almost all objects you interact with on a Matplotlib plot are called "Artist" (and are subclasses of the Artist class). Figure and Axes are Artists, and generally contain Axis Artists and Artists that contain data or annotation information.

Creating Artists#

Usually we do not instantiate Artists directly, but rather use a plotting method on Axes. Some examples of plotting methods and the Artist object they create is given below:

Axes helper method


annotate - text annotations


bar - bar charts


errorbar - error bar plots

Line2D and Rectangle

fill - shared area


hist - histograms


imshow - image data


legend - Axes legend


plot - xy plots


scatter - scatter charts


text - text


As an example, we can save the Line2D Artist returned from axes.Axes.plot:

In [209]: import matplotlib.pyplot as plt
In [210]: import matplotlib.artist as martist
In [211]: import numpy as np

In [212]: fig, ax = plt.subplots()
In [213]: x, y = np.random.rand(2, 100)
In [214]: lines = ax.plot(x, y, '-', label='example')
In [215]: print(lines)
[<matplotlib.lines.Line2D at 0xd378b0c>]

Note that plot returns a _list_ of lines because you can pass in multiple x, y pairs to plot. The line has been added to the Axes, and we can retrieve the Artist via get_lines():

In [216]: print(ax.get_lines())
<a list of 1 Line2D objects>
In [217]: print(ax.get_lines()[0])

Changing Artist properties#

Getting the lines object gives us access to all the properties of the Line2D object. So if we want to change the linewidth after the fact, we can do so using Artist.set.

fig, ax = plt.subplots(figsize=(4, 2.5))
x = np.arange(0, 13, 0.2)
y = np.sin(x)
lines = ax.plot(x, y, '-', label='example', linewidth=0.2, color='blue')
lines[0].set(color='green', linewidth=2)

(Source code, 2x.png, png)

We can interrogate the full list of settable properties with matplotlib.artist.getp:

In [218]: martist.getp(lines[0])
agg_filter = None
alpha = None
animated = False
antialiased or aa = True
bbox = Bbox(x0=0.004013842290585101, y0=0.013914221641967...
children = []
clip_box = TransformedBbox(     Bbox(x0=0.0, y0=0.0, x1=1.0, ...
clip_on = True
clip_path = None
color or c = blue
dash_capstyle = butt
dash_joinstyle = round
data = (array([0.91377845, 0.58456834, 0.36492019, 0.0379...
drawstyle or ds = default
figure = Figure(550x450)
fillstyle = full
gapcolor = None
gid = None
in_layout = True
label = example
linestyle or ls = -
linewidth or lw = 2.0
marker = None
markeredgecolor or mec = blue
markeredgewidth or mew = 1.0
markerfacecolor or mfc = blue
markerfacecoloralt or mfcalt = none
markersize or ms = 6.0
markevery = None
mouseover = False
path = Path(array([[0.91377845, 0.51224793],        [0.58...
path_effects = []
picker = None
pickradius = 5
rasterized = False
sketch_params = None
snap = None
solid_capstyle = projecting
solid_joinstyle = round
tightbbox = Bbox(x0=70.4609002763619, y0=54.321277798941786, x...
transform = CompositeGenericTransform(     TransformWrapper(  ...
transformed_clip_path_and_affine = (None, None)
url = None
visible = True
window_extent = Bbox(x0=70.4609002763619, y0=54.321277798941786, x...
xdata = [0.91377845 0.58456834 0.36492019 0.03796664 0.884...
xydata = [[0.91377845 0.51224793]  [0.58456834 0.9820474 ] ...
ydata = [0.51224793 0.9820474  0.24469912 0.61647032 0.483...
zorder = 2

Note most Artists also have a distinct list of setters; e.g. Line2D.set_color or Line2D.set_linewidth.

Changing Artist data#

In addition to styling properties like color and linewidth, the Line2D object has a data property. You can set the data after the line has been created using Line2D.set_data. This is often used for Animations, where the same line is shown evolving over time (see Animations using Matplotlib)

fig, ax = plt.subplots(figsize=(4, 2.5))
x = np.arange(0, 13, 0.2)
y = np.sin(x)
lines = ax.plot(x, y, '-', label='example')
lines[0].set_data([x, np.cos(x)])

(Source code, 2x.png, png)

Manually adding Artists#

Not all Artists have helper methods, or you may want to use a low-level method for some reason. For example the patches.Circle Artist does not have a helper, but we can still create and add to an Axes using the axes.Axes.add_artist method:

import matplotlib.patches as mpatches

fig, ax = plt.subplots(figsize=(4, 2.5))
circle = mpatches.Circle((0.5, 0.5), 0.25, ec="none")
clipped_circle = mpatches.Circle((1, 0.5), 0.125, ec="none", facecolor='C1')

(Source code, 2x.png, png)

The Circle takes the center and radius of the Circle as arguments to its constructor; optional arguments are passed as keyword arguments.

Note that when we add an Artist manually like this, it doesn't necessarily adjust the axis limits like most of the helper methods do, so the Artists can be clipped, as is the case above for the clipped_circle patch.

See Reference for Matplotlib artists for other patches.

Removing Artists#

Sometimes we want to remove an Artist from a figure without re-specifying the whole figure from scratch. Most Artists have a usable remove method that will remove the Artist from its Axes list. For instance lines[0].remove() would remove the Line2D artist created in the example above.