matplotlib artists

matplotlib.artist

class matplotlib.artist.Artist

Bases: object

Abstract base class for someone who renders into a FigureCanvas.

add_callback(func)
contains(mouseevent)

Test whether the artist contains the mouse event.

Returns the truth value and a dictionary of artist specific details of selection, such as which points are contained in the pick radius. See individual artists for details.

convert_xunits(x)
for artists in an axes, if the xaxis as units support, convert x using xaxis unit type
convert_yunits(y)
for artists in an axes, if the yaxis as units support, convert y using yaxis unit type
draw(renderer, *args, **kwargs)
Derived classes drawing method
findobj(match=None)
pyplot signature:
findobj(o=gcf(), match=None)

recursively find all :class:matplotlib.artist.Artist instances contained in self

match can be

  • None: return all objects contained in artist (including artist)
  • function with signature boolean = match(artist) used to filter matches
  • class instance: eg Line2D. Only return artists of class type

[source code, png, pdf]

../_images/findobj_demo.png
get_alpha()
Return the alpha value used for blending - not supported on all backends
get_animated()
return the artist’s animated state
get_axes()
return the axes instance the artist resides in, or None
get_clip_box()
Return artist clipbox
get_clip_on()
Return whether artist uses clipping
get_clip_path()
Return artist clip path
get_contains()
return the _contains test used by the artist, or None for default.
get_figure()
Return the Figure instance the artist belongs to.
get_label()
get_picker()
return the Pickeration instance used by this artist
get_transform()
Return the Transform instance used by this artist.
get_transformed_clip_path_and_affine()
Return the clip path with the non-affine part of its transformation applied, and the remaining affine part of its transformation.
get_visible()
return the artist’s visiblity
get_zorder()
have_units()
return True if units are set on the x or y axes
hitlist(event)
List the children of the artist which contain the mouse event
is_figure_set()
is_transform_set()
Artist has transform explicity let
pchanged()
fire event when property changed
pick(mouseevent)

call signature:

pick(mouseevent)

each child artist will fire a pick event if mouseevent is over the artist and the artist has picker set

pickable()
return True if self is pickable
remove()

Remove the artist from the figure if possible. The effect will not be visible until the figure is redrawn, e.g., with matplotlib.axes.Axes.draw_idle(). Call matplotlib.axes.Axes.relim() to update the axes limits if desired.

Note: relim() will not see collections even if the collection was added to axes with autolim = True.

Note: there is no support for removing the artist’s legend entry.

remove_callback(oid)
set(**kwargs)
A tkstyle set command, pass kwargs to set properties
set_alpha(alpha)

Set the alpha value used for blending - not supported on all backends

ACCEPTS: float

set_animated(b)

set the artist’s animation state

ACCEPTS: [True | False]

set_axes(axes)

set the axes instance in which the artist resides, if any

ACCEPTS: an axes instance

set_clip_box(clipbox)

Set the artist’s clip Bbox

ACCEPTS: a matplotlib.transform.Bbox instance

set_clip_on(b)

Set whether artist uses clipping

ACCEPTS: [True | False]

set_clip_path(path, transform=None)

Set the artist’s clip path, which may be:

  • a Patch (or subclass) instance

  • a Path instance, in which case

    an optional Transform instance may be provided, which will be applied to the path before using it for clipping.

  • None, to remove the clipping path

For efficiency, if the path happens to be an axis-aligned rectangle, this method will set the clipping box to the corresponding rectangle and set the clipping path to None.

ACCEPTS: a Path instance and a Transform instance, a Patch instance, or None.

set_contains(picker)

Replace the contains test used by this artist. The new picker should be a callable function which determines whether the artist is hit by the mouse event:

hit, props = picker(artist, mouseevent)

If the mouse event is over the artist, return hit=True and props is a dictionary of properties you want returned with the contains test.

set_figure(fig)

Set the Figure instance the artist belongs to.

ACCEPTS: a matplotlib.figure.Figure instance

set_label(s)

Set the line label to s for auto legend

ACCEPTS: any string

set_lod(on)

Set Level of Detail on or off. If on, the artists may examine things like the pixel width of the axes and draw a subset of their contents accordingly

ACCEPTS: [True | False]

set_picker(picker)

set the epsilon for picking used by this artist

picker can be one of the following:

  • None: picking is disabled for this artist (default)

  • A boolean: if True then picking will be enabled and the artist will fire a pick event if the mouse event is over the artist

  • A float: if picker is a number it is interpreted as an epsilon tolerance in points and the artist will fire off an event if it’s data is within epsilon of the mouse event. For some artists like lines and patch collections, the artist may provide additional data to the pick event that is generated, e.g. the indices of the data within epsilon of the pick event

  • A function: if picker is callable, it is a user supplied function which determines whether the artist is hit by the mouse event:

    hit, props = picker(artist, mouseevent)
    

    to determine the hit test. if the mouse event is over the artist, return hit=True and props is a dictionary of properties you want added to the PickEvent attributes.

ACCEPTS: [None|float|boolean|callable]

set_transform(t)
Set the Transform instance used by this artist.
set_visible(b)

set the artist’s visiblity

ACCEPTS: [True | False]

set_zorder(level)

Set the zorder for the artist

ACCEPTS: any number

update(props)
update_from(other)
Copy properties from other to self.
class matplotlib.artist.ArtistInspector(o)

A helper class to inspect an Artist and return information about it’s settable properties and their current values.

Initialize the artist inspector with an Artist or sequence of Artists. If a sequence is used, we assume it is a homogeneous sequence (all Artists are of the same type) and it is your responsibility to make sure this is so.

aliased_name(s)

return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME.

E.g. for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’ and for the transform property, which does not, return ‘transform’

findobj(match=None)

recursively find all :class:matplotlib.artist.Artist instances contained in self

if match is not None, it can be

  • function with signature boolean = match(artist)
  • class instance: eg Line2D

used to filter matches

get_aliases()

Get a dict mapping fullname -> alias for each alias in the ArtistInspector.

Eg., for lines:

{'markerfacecolor': 'mfc',
 'linewidth'      : 'lw',
}
get_setters()
Get the attribute strings with setters for object. Eg., for a line, return ['markerfacecolor', 'linewidth', ....].
get_valid_values(attr)

Get the legal arguments for the setter associated with attr.

This is done by querying the docstring of the function set_attr for a line that begins with ACCEPTS:

Eg., for a line linestyle, return [ ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘steps’ | ‘None’ ]

is_alias(o)
Return True if method object o is an alias for another function.
pprint_getters()
Return the getters and actual values as list of strings.
pprint_setters(prop=None, leadingspace=2)

If prop is None, return a list of strings of all settable properies and their valid values.

If prop is not None, it is a valid property name and that property will be returned as a string of property : valid values.

matplotlib.artist.get(o, *args, **kwargs)

Return the value of handle property. property is an optional string for the property you want to return

Example usage:

getp(o)  # get all the object properties
getp(o, 'linestyle')  # get the linestyle property

o is a Artist instance, eg Line2D or an instance of a Axes or matplotlib.text.Text. If the property is ‘somename’, this function returns

o.get_somename()

getp can be used to query all the gettable properties with getp(o) Many properties have aliases for shorter typing, eg ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names will be listed as:

property or  alias = value

e.g.:

linewidth or lw = 2
matplotlib.artist.getp(o, property=None)

Return the value of handle property. property is an optional string for the property you want to return

Example usage:

getp(o)  # get all the object properties
getp(o, 'linestyle')  # get the linestyle property

o is a Artist instance, eg Line2D or an instance of a Axes or matplotlib.text.Text. If the property is ‘somename’, this function returns

o.get_somename()

getp can be used to query all the gettable properties with getp(o) Many properties have aliases for shorter typing, eg ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names will be listed as:

property or  alias = value

e.g.:

linewidth or lw = 2
matplotlib.artist.kwdoc(a)
matplotlib.artist.setp(h, *args, **kwargs)

matplotlib supports the use of setp() (“set property”) and getp() to set and get object properties, as well as to do introspection on the object. For example, to set the linestyle of a line to be dashed, you can do:

>>> line, = plot([1,2,3])
>>> setp(line, linestyle='--')

If you want to know the valid types of arguments, you can provide the name of the property you want to set without a value:

>>> setp(line, 'linestyle')
    linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]

If you want to see all the properties that can be set, and their possible values, you can do:

>>> setp(line)
    ... long output listing omitted

setp() operates on a single instance or a list of instances. If you are in query mode introspecting the possible values, only the first instance in the sequence is used. When actually setting values, all the instances will be set. E.g., suppose you have a list of two lines, the following will make both lines thicker and red:

>>> x = arange(0,1.0,0.01)
>>> y1 = sin(2*pi*x)
>>> y2 = sin(4*pi*x)
>>> lines = plot(x, y1, x, y2)
>>> setp(lines, linewidth=2, color='r')

setp() works with the matlab(TM) style string/value pairs or with python kwargs. For example, the following are equivalent

>>> setp(lines, 'linewidth', 2, 'color', r')  # matlab style
>>> setp(lines, linewidth=2, color='r')       # python style

matplotlib.lines

This module contains all the 2D line class which can draw with a variety of line styles, markers and colors

class matplotlib.lines.Line2D(xdata, ydata, linewidth=None, linestyle=None, color=None, marker=None, markersize=None, markeredgewidth=None, markeredgecolor=None, markerfacecolor=None, antialiased=None, dash_capstyle=None, solid_capstyle=None, dash_joinstyle=None, solid_joinstyle=None, pickradius=5, **kwargs)

Bases: matplotlib.artist.Artist

Create a Line2D instance with x and y data in sequences xdata, ydata.

The kwargs are Line2D properties:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
axes unknown
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
clip_path a Path instance and a
color or c any matplotlib color
contains unknown
dash_capstyle [‘butt’ | ‘round’ | ‘projecting’]
dash_joinstyle [‘miter’ | ‘round’ | ‘bevel’]
dashes sequence of on/off ink in points
data (np.array xdata, np.array ydata)
figure a matplotlib.figure.Figure instance
label any string
linestyle or ls [ ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ | ‘None’ | ‘ ‘ | ‘’ ]
linewidth or lw float value in points
lod [True | False]
marker [ ‘+’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’
markeredgecolor or mec any matplotlib color
markeredgewidth or mew float value in points
markerfacecolor or mfc any matplotlib color
markersize or ms float
picker unknown
pickradius unknown
solid_capstyle [‘butt’ | ‘round’ | ‘projecting’]
solid_joinstyle [‘miter’ | ‘round’ | ‘bevel’]
transform a matplotlib.transforms.Transform instance
visible [True | False]
xdata np.array
ydata np.array
zorder any number
contains(mouseevent)

Test whether the mouse event occurred on the line. The pick radius determines the precision of the location test (usually within five points of the value). Use get_pickradius()/set_pickradius() to view or modify it.

Returns True if any values are within the radius along with {'ind': pointlist}, where pointlist is the set of points within the radius.

TODO: sort returned indices by distance

draw(renderer)
get_aa()
alias for get_antialiased
get_antialiased()
get_c()
alias for get_color
get_color()
get_dash_capstyle()
Get the cap style for dashed linestyles
get_dash_joinstyle()
Get the join style for dashed linestyles
get_data(orig=True)

Return the xdata, ydata.

If orig is True, return the original data

get_linestyle()
get_linewidth()
get_ls()
alias for get_linestyle
get_lw()
alias for get_linewidth
get_marker()
get_markeredgecolor()
get_markeredgewidth()
get_markerfacecolor()
get_markersize()
get_mec()
alias for get_markeredgecolor
get_mew()
alias for get_markeredgewidth
get_mfc()
alias for get_markerfacecolor
get_ms()
alias for get_markersize
get_path()
Return the Path object associated with this line.
get_pickradius()
return the pick radius used for containment tests
get_solid_capstyle()
Get the cap style for solid linestyles
get_solid_joinstyle()
Get the join style for solid linestyles
get_window_extent(renderer)
get_xdata(orig=True)

Return the xdata.

If orig is True, return the original data, else the processed data.

get_xydata()
Return the xy data as a Nx2 numpy array.
get_ydata(orig=True)

Return the ydata.

If orig is True, return the original data, else the processed data.

is_dashed()
return True if line is dashstyle
recache()
set_aa(val)
alias for set_antialiased
set_antialiased(b)

True if line should be drawin with antialiased rendering

ACCEPTS: [True | False]

set_axes(ax)
set_c(val)
alias for set_color
set_color(color)

Set the color of the line

ACCEPTS: any matplotlib color

set_dash_capstyle(s)

Set the cap style for dashed linestyles

ACCEPTS: [‘butt’ | ‘round’ | ‘projecting’]

set_dash_joinstyle(s)
Set the join style for dashed linestyles ACCEPTS: [‘miter’ | ‘round’ | ‘bevel’]
set_dashes(seq)

Set the dash sequence, sequence of dashes with on off ink in points. If seq is empty or if seq = (None, None), the linestyle will be set to solid.

ACCEPTS: sequence of on/off ink in points

set_data(*args)

Set the x and y data

ACCEPTS: (np.array xdata, np.array ydata)

set_linestyle(linestyle)

Set the linestyle of the line

‘steps’ is equivalent to ‘steps-pre’ and is maintained for backward-compatibility.

ACCEPTS: [ ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ | ‘None’ | ‘ ‘ | ‘’ ]

set_linewidth(w)

Set the line width in points

ACCEPTS: float value in points

set_ls(val)
alias for set_linestyle
set_lw(val)
alias for set_linewidth
set_marker(marker)

Set the line marker

ACCEPTS: [ ‘+’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’
‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’
‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v’ | ‘x’ | ‘|’
TICKUP | TICKDOWN | TICKLEFT | TICKRIGHT
‘None’ | ‘ ‘ | ‘’ ]
set_markeredgecolor(ec)

Set the marker edge color

ACCEPTS: any matplotlib color

set_markeredgewidth(ew)

Set the marker edge width in points

ACCEPTS: float value in points

set_markerfacecolor(fc)

Set the marker face color

ACCEPTS: any matplotlib color

set_markersize(sz)

Set the marker size in points

ACCEPTS: float

set_mec(val)
alias for set_markeredgecolor
set_mew(val)
alias for set_markeredgewidth
set_mfc(val)
alias for set_markerfacecolor
set_ms(val)
alias for set_markersize
set_picker(p)

Sets the event picker details for the line.

Accepts: float distance in points or callable pick function fn(artist,event)

set_pickradius(d)

Sets the pick radius used for containment tests

Accepts: float distance in points.

set_solid_capstyle(s)

Set the cap style for solid linestyles

ACCEPTS: [‘butt’ | ‘round’ | ‘projecting’]

set_solid_joinstyle(s)
Set the join style for solid linestyles ACCEPTS: [‘miter’ | ‘round’ | ‘bevel’]
set_transform(t)

set the Transformation instance used by this artist

ACCEPTS: a matplotlib.transforms.Transform instance

set_xdata(x)

Set the data np.array for x

ACCEPTS: np.array

set_ydata(y)

Set the data np.array for y

ACCEPTS: np.array

update_from(other)
copy properties from other to self
class matplotlib.lines.VertexSelector(line)

Manage the callbacks to maintain a list of selected vertices for matplotlib.lines.Line2D. Derived classes should override process_selected() to do something with the picks.

Here is an example which highlights the selected verts with red circles:

import numpy as np
import matplotlib.pyplot as plt
import matplotlib.lines as lines

class HighlightSelected(lines.VertexSelector):
    def __init__(self, line, fmt='ro', **kwargs):
        lines.VertexSelector.__init__(self, line)
        self.markers, = self.axes.plot([], [], fmt, **kwargs)

    def process_selected(self, ind, xs, ys):
        self.markers.set_data(xs, ys)
        self.canvas.draw()

fig = plt.figure()
ax = fig.add_subplot(111)
x, y = np.random.rand(2, 30)
line, = ax.plot(x, y, 'bs-', picker=5)

selector = HighlightSelected(line)
plt.show()

Initialize the class with a matplotlib.lines.Line2D instance. The line should already be added to some matplotlib.axes.Axes instance and should have the picker property set.

onpick(event)
When the line is picked, update the set of selected indicies.
process_selected(ind, xs, ys)

Default “do nothing” implementation of the process_selected() method.

ind are the indices of the selected vertices. xs and ys are the coordinates of the selected vertices.

matplotlib.lines.segment_hits(cx, cy, x, y, radius)
Determine if any line segments are within radius of a point. Returns the list of line segments that are within that radius.
matplotlib.lines.unmasked_index_ranges(mask, compressed=True)

matplotlib.patches

class matplotlib.patches.Arc(xy, width, height, angle=0.0, theta1=0.0, theta2=360.0, **kwargs)

Bases: matplotlib.patches.Ellipse

An elliptical arc. Because it performs various optimizations, it can not be filled.

The arc must be used in an Axes instance—it cannot be added directly to a Figure—because it is optimized to only render the segments that are inside the axes bounding box with high resolution.

The following args are supported:

xy
center of ellipse
width
length of horizontal axis
height
length of vertical axis
angle
rotation in degrees (anti-clockwise)
theta1
starting angle of the arc in degrees
theta2
ending angle of the arc in degrees

If theta1 and theta2 are not provided, the arc will form a complete ellipse.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
draw(renderer)

Ellipses are normally drawn using an approximation that uses eight cubic bezier splines. The error of this approximation is 1.89818e-6, according to this unverified source:

Lancaster, Don. Approximating a Circle or an Ellipse Using Four Bezier Cubic Splines.

http://www.tinaja.com/glib/ellipse4.pdf

There is a use case where very large ellipses must be drawn with very high accuracy, and it is too expensive to render the entire ellipse with enough segments (either splines or line segments). Therefore, in the case where either radius of the ellipse is large enough that the error of the spline approximation will be visible (greater than one pixel offset from the ideal), a different technique is used.

In that case, only the visible parts of the ellipse are drawn, with each visible arc using a fixed number of spline segments (8). The algorithm proceeds as follows:

  1. The points where the ellipse intersects the axes bounding box are located. (This is done be performing an inverse transformation on the axes bbox such that it is relative to the unit circle – this makes the intersection calculation much easier than doing rotated ellipse intersection directly).

    This uses the “line intersecting a circle” algorithm from:

    Vince, John. Geometry for Computer Graphics: Formulae, Examples & Proofs. London: Springer-Verlag, 2005.

  2. The angles of each of the intersection points are calculated.

  3. Proceeding counterclockwise starting in the positive x-direction, each of the visible arc-segments between the pairs of vertices are drawn using the bezier arc approximation technique implemented in matplotlib.path.Path.arc().

class matplotlib.patches.Arrow(x, y, dx, dy, width=1.0, **kwargs)

Bases: matplotlib.patches.Patch

An arrow patch.

Draws an arrow, starting at (x, y), direction and length given by (dx, dy) the width of the arrow is scaled by width.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
get_patch_transform()
get_path()
class matplotlib.patches.Circle(xy, radius=5, **kwargs)

Bases: matplotlib.patches.Ellipse

A circle patch.

Create true circle at center xy = (x, y) with given radius. Unlike CirclePolygon which is a polygonal approximation, this uses Bézier splines and is much closer to a scale-free circle.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
class matplotlib.patches.CirclePolygon(xy, radius=5, resolution=20, **kwargs)

Bases: matplotlib.patches.RegularPolygon

A polygon-approximation of a circle patch.

Create a circle at xy = (x, y) with given radius. This circle is approximated by a regular polygon with resolution sides. For a smoother circle drawn with splines, see Circle.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
class matplotlib.patches.Ellipse(xy, width, height, angle=0.0, **kwargs)

Bases: matplotlib.patches.Patch

A scale-free ellipse.

xy
center of ellipse
width
length of horizontal axis
height
length of vertical axis
angle
rotation in degrees (anti-clockwise)

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
contains(ev)
get_patch_transform()
get_path()
Return the vertices of the rectangle
class matplotlib.patches.FancyArrow(x, y, dx, dy, width=0.001, length_includes_head=False, head_width=None, head_length=None, shape='full', overhang=0, head_starts_at_zero=False, **kwargs)

Bases: matplotlib.patches.Polygon

Like Arrow, but lets you set head width and head height independently.

Constructor arguments

length_includes_head:
True if head is counted in calculating the length.

shape: [‘full’, ‘left’, ‘right’]

overhang:
distance that the arrow is swept back (0 overhang means triangular shape).
head_starts_at_zero:
If True, the head starts being drawn at coordinate 0 instead of ending at coordinate 0.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
class matplotlib.patches.Patch(edgecolor=None, facecolor=None, linewidth=None, linestyle=None, antialiased=None, hatch=None, fill=True, **kwargs)

Bases: matplotlib.artist.Artist

A patch is a 2D thingy with a face color and an edge color.

If any of edgecolor, facecolor, linewidth, or antialiased are None, they default to their rc params setting.

The following kwarg properties are supported

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
contains(mouseevent)

Test whether the mouse event occurred in the patch.

Returns T/F, {}

draw(renderer)
get_aa()
get_antialiased()
get_data_transform()
get_ec()
get_edgecolor()
get_extents()
get_facecolor()
get_fc()
get_fill()
return whether fill is set
get_hatch()
return the current hatching pattern
get_linestyle()
get_linewidth()
get_ls()
get_lw()
get_patch_transform()
get_path()
Return the path of this patch
get_transform()
get_verts()

Return a copy of the vertices used in this patch

If the patch contains Bézier curves, the curves will be interpolated by line segments. To access the curves as curves, use get_path().

get_window_extent(renderer=None)
set_aa(aa)

Set whether to use antialiased rendering

ACCEPTS: [True | False] or None for default

set_antialiased(aa)

Set whether to use antialiased rendering

ACCEPTS: [True | False] or None for default

set_ec(color)

Set the patch edge color

ACCEPTS: mpl color spec, or None for default, or ‘none’ for no color

set_edgecolor(color)

Set the patch edge color

ACCEPTS: mpl color spec, or None for default, or ‘none’ for no color

set_facecolor(color)

Set the patch face color

ACCEPTS: mpl color spec, or None for default, or ‘none’ for no color

set_fc(color)

Set the patch face color

ACCEPTS: mpl color spec, or None for default, or ‘none’ for no color

set_fill(b)

Set whether to fill the patch

ACCEPTS: [True | False]

set_hatch(h)

Set the hatching pattern

hatch can be one of:

/   - diagonal hatching
\   - back diagonal
|   - vertical
-   - horizontal
#   - crossed
x   - crossed diagonal

Letters can be combined, in which case all the specified hatchings are done. If same letter repeats, it increases the density of hatching in that direction.

CURRENT LIMITATIONS:

  1. Hatching is supported in the PostScript backend only.
  2. Hatching is done with solid black lines of width 0.
set_linestyle(ls)

Set the patch linestyle

ACCEPTS: [‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’]

set_linewidth(w)

Set the patch linewidth in points

ACCEPTS: float or None for default

set_ls(ls)

Set the patch linestyle

ACCEPTS: [‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’]

set_lw(w)

Set the patch linewidth in points

ACCEPTS: float or None for default

update_from(other)
class matplotlib.patches.PathPatch(path, **kwargs)

Bases: matplotlib.patches.Patch

A general polycurve path patch.

path is a matplotlib.path.Path object.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number

See Patch documentation for additional kwargs

get_path()
class matplotlib.patches.Polygon(xy, closed=True, **kwargs)

Bases: matplotlib.patches.Patch

A general polygon patch.

xy is a numpy array with shape Nx2.

If closed is True, the polygon will be closed so the starting and ending points are the same.

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number

See Patch documentation for additional kwargs

get_closed()
get_path()
get_xy()
set_closed(closed)
set_xy(vertices)
xy
Set/get the vertices of the polygon. This property is provided for backward compatibility with matplotlib 0.91.x only. New code should use get_xy() and set_xy() instead.
class matplotlib.patches.Rectangle(xy, width, height, **kwargs)

Bases: matplotlib.patches.Patch

Draw a rectangle with lower left at xy*=(*x, y) with specified width and height

fill is a boolean indicating whether to fill the rectangle

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
contains(mouseevent)
get_bbox()
get_height()
Return the height of the rectangle
get_patch_transform()
get_path()
Return the vertices of the rectangle
get_width()
Return the width of the rectangle
get_x()
Return the left coord of the rectangle
get_y()
Return the bottom coord of the rectangle
set_bounds(*args)

Set the bounds of the rectangle: l,b,w,h

ACCEPTS: (left, bottom, width, height)

set_height(h)

Set the width rectangle

ACCEPTS: float

set_width(w)

Set the width rectangle

ACCEPTS: float

set_x(x)

Set the left coord of the rectangle

ACCEPTS: float

set_y(y)

Set the bottom coord of the rectangle

ACCEPTS: float

class matplotlib.patches.RegularPolygon(xy, numVertices, radius=5, orientation=0, **kwargs)

Bases: matplotlib.patches.Patch

A regular polygon patch.

Constructor arguments:

xy
A length 2 tuple (x, y) of the center.
numVertices
the number of vertices.
radius
The distance from the center to each of the vertices.
orientation
rotates the polygon (in radians).

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
get_patch_transform()
get_path()
numvertices
orientation
radius
xy
class matplotlib.patches.Shadow(patch, ox, oy, props=None, **kwargs)

Bases: matplotlib.patches.Patch

Create a shadow of the given patch offset by ox, oy. props, if not None, is a patch property update dictionary. If None, the shadow will have have the same color as the face, but darkened.

kwargs are

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
get_patch_transform()
get_path()
class matplotlib.patches.Wedge(center, r, theta1, theta2, **kwargs)

Bases: matplotlib.patches.Patch

Draw a wedge centered at x, y center with radius r that sweeps theta1 to theta2 (in degrees).

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
get_patch_transform()
get_path()
class matplotlib.patches.YAArrow(figure, xytip, xybase, width=4, frac=0.10000000000000001, headwidth=12, **kwargs)

Bases: matplotlib.patches.Patch

Yet another arrow class.

This is an arrow that is defined in display space and has a tip at x1, y1 and a base at x2, y2.

Constructor arguments:

xytip
(x, y) location of arrow tip
xybase
(x, y) location the arrow base mid point
figure
The Figure instance (fig.dpi)
width
The width of the arrow in points
frac
The fraction of the arrow length occupied by the head
headwidth
The width of the base of the arrow head in points

Valid kwargs are:

Property Description
alpha float
animated [True | False]
antialiased or aa [True | False]
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
edgecolor or ec any matplotlib color
facecolor or fc any matplotlib color
figure a matplotlib.figure.Figure instance
fill [True | False]
hatch unknown
label any string
linewidth or lw float
lod [True | False]
transform a matplotlib.transform transformation instance
visible [True | False]
zorder any number
get_patch_transform()
get_path()
getpoints(x1, y1, x2, y2, k)
For line segment defined by (x1, y1) and (x2, y2) return the points on the line that is perpendicular to the line and intersects (x2, y2) and the distance from (x2, y2) of the returned points is k.
matplotlib.patches.bbox_artist(artist, renderer, props=None, fill=True)

This is a debug function to draw a rectangle around the bounding box returned by get_window_extent() of an artist, to test whether the artist is returning the correct bbox.

props is a dict of rectangle props with the additional property ‘pad’ that sets the padding around the bbox in points.

matplotlib.patches.draw_bbox(bbox, renderer, color='k', trans=None)
This is a debug function to draw a rectangle around the bounding box returned by get_window_extent() of an artist, to test whether the artist is returning the correct bbox.

matplotlib.text

Figure and Axes text

class matplotlib.text.Annotation(s, xy, xytext=None, xycoords='data', textcoords=None, arrowprops=None, **kwargs)

Bases: matplotlib.text.Text

A Text class to make annotating things in the figure, such as Figure, Axes, Rectangle, etc., easier.

Annotate the x, y point xy with text s at x, y location xytext. (If xytext = None, defaults to xy, and if textcoords = None, defaults to xycoords).

arrowprops, if not None, is a dictionary of line properties (see matplotlib.lines.Line2D) for the arrow that connects annotation to the point. Valid keys are

Key Description
width the width of the arrow in points
frac the fraction of the arrow length occupied by the head
headwidth the width of the base of the arrow head in points
shrink oftentimes it is convenient to have the arrowtip and base a bit away from the text and point being annotated. If d is the distance between the text and annotated point, shrink will shorten the arrow so the tip and base are shink percent of the distance d away from the endpoints. ie, shrink=0.05 is 5%
? any key for matplotlib.patches.polygon

xycoords and textcoords are strings that indicate the coordinates of xy and xytext.

Property Description
‘figure points’ points from the lower left corner of the figure
‘figure pixels’ pixels from the lower left corner of the figure
‘figure fraction’ 0,0 is lower left of figure and 1,1 is upper, right
‘axes points’ points from lower left corner of axes
‘axes pixels’ pixels from lower left corner of axes
‘axes fraction’ 0,1 is lower left of axes and 1,1 is upper right
‘data’ use the coordinate system of the object being annotated (default)
‘offset points’ Specify an offset (in points) from the xy value
‘polar’ you can specify theta, r for the annotation, even in cartesian plots. Note that if you are using a polar axes, you do not need to specify polar for the coordinate system since that is the native “data” coordinate system.

If a ‘points’ or ‘pixels’ option is specified, values will be added to the bottom-left and if negative, values will be subtracted from the top-right. Eg:

# 10 points to the right of the left border of the axes and
# 5 points below the top border
xy=(10,-5), xycoords='axes points'

Additional kwargs are Text properties:

Property Description
alpha float
animated [True | False]
axes an axes instance
backgroundcolor any matplotlib color
bbox rectangle prop dict plus key ‘pad’ which is a pad in points
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
clip_path a Path instance and a
color any matplotlib color
contains unknown
family [ ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ]
figure a matplotlib.figure.Figure instance
fontproperties a matplotlib.font_manager.FontProperties instance
horizontalalignment or ha [ ‘center’ | ‘right’ | ‘left’ ]
label any string
linespacing float
lod [True | False]
multialignment [‘left’ | ‘right’ | ‘center’ ]
name or fontname string eg, [‘Sans’ | ‘Courier’ | ‘Helvetica’ ...]
picker [None|float|boolean|callable]
position (x,y)
rotation [ angle in degrees ‘vertical’ | ‘horizontal’
size or fontsize [ size in points | relative size eg ‘smaller’, ‘x-large’ ]
style or fontstyle [ ‘normal’ | ‘italic’ | ‘oblique’]
text string or anything printable with ‘%s’ conversion
transform unknown
variant [ ‘normal’ | ‘small-caps’ ]
verticalalignment or va [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ]
visible [True | False]
weight or fontweight [ ‘normal’ | ‘bold’ | ‘heavy’ | ‘light’ | ‘ultrabold’ | ‘ultralight’]
x float
y float
zorder any number
contains(event)
draw(renderer)
set_clip_box(clipbox)

Set the artist’s clip Bbox

ACCEPTS: a matplotlib.transform.Bbox instance

set_figure(fig)
update_positions(renderer)
class matplotlib.text.Text(x=0, y=0, text='', color=None, verticalalignment='bottom', horizontalalignment='left', multialignment=None, fontproperties=None, rotation=None, linespacing=None, **kwargs)

Bases: matplotlib.artist.Artist

Handle storing and drawing of text in window or data coordinates

Create a Text instance at x, y with string text.

Valid kwargs are
alpha float
animated [True | False]
backgroundcolor any matplotlib color
bbox rectangle prop dict plus key ‘pad’ which is a pad in points
clip_box a matplotlib.transform.Bbox instance
clip_on [True | False]
color any matplotlib color
family [ ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ]
figure a matplotlib.figure.Figure instance
fontproperties a matplotlib.font_manager.FontProperties instance
horizontalalignment or ha [ ‘center’ | ‘right’ | ‘left’ ]
label any string
linespacing float
lod [True | False]
multialignment [‘left’ | ‘right’ | ‘center’ ]
name or fontname string eg, [‘Sans’ | ‘Courier’ | ‘Helvetica’ ...]
position (x,y)
rotation [ angle in degrees ‘vertical’ | ‘horizontal’
size or fontsize [ size in points | relative size eg ‘smaller’, ‘x-large’ ]
style or fontstyle [ ‘normal’ | ‘italic’ | ‘oblique’]
text string
transform a matplotlib.transform transformation instance
variant [ ‘normal’ | ‘small-caps’ ]
verticalalignment or va [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ]
visible [True | False]
weight or fontweight [ ‘normal’ | ‘bold’ | ‘heavy’ | ‘light’ | ‘ultrabold’ | ‘ultralight’]
x float
y float
zorder any number
contains(mouseevent)

Test whether the mouse event occurred in the patch.

Returns T/F, {}

draw(renderer)
get_color()
Return the color of the text
get_font_properties()
Return the font object
get_fontname()
alias for get_name
get_fontsize()
alias for get_size
get_fontstyle()
alias for get_style
get_fontweight()
alias for get_weight
get_ha()
alias for get_horizontalalignment
get_horizontalalignment()
Return the horizontal alignment as string
get_name()
Return the font name as string
get_position()
Return x, y as tuple
get_prop_tup()

Return a hashable tuple of properties

Not intended to be human readable, but useful for backends who want to cache derived information about text (eg layouts) and need to know if the text has changed

get_rotation()
return the text angle as float
get_size()
Return the font size as integer
get_style()
Return the font style as string
get_text()
Get the text as string
get_va()
alias for getverticalalignment
get_verticalalignment()
Return the vertical alignment as string
get_weight()
Get the font weight as string
get_window_extent(renderer=None)
is_math_text(s)
set_backgroundcolor(color)

Set the background color of the text by updating the bbox (see set_bbox for more info)

ACCEPTS: any matplotlib color

set_bbox(rectprops)

Draw a bounding box around self. rect props are any settable properties for a rectangle, eg facecolor=’red’, alpha=0.5.

t.set_bbox(dict(facecolor=’red’, alpha=0.5))

ACCEPTS: rectangle prop dict plus key ‘pad’ which is a pad in points

set_color(color)

Set the foreground color of the text

ACCEPTS: any matplotlib color

set_family(fontname)

Set the font family

ACCEPTS: [ ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ]

set_fontname(fontname)
alias for set_name
set_fontproperties(fp)

Set the font properties that control the text

ACCEPTS: a matplotlib.font_manager.FontProperties instance

set_fontsize(fontsize)
alias for set_size
set_fontstyle(fontstyle)
alias for set_style
set_fontweight(weight)
alias for set_weight
set_ha(align)
alias for set_horizontalalignment
set_horizontalalignment(align)

Set the horizontal alignment to one of

ACCEPTS: [ ‘center’ | ‘right’ | ‘left’ ]

set_linespacing(spacing)

Set the line spacing as a multiple of the font size. Default is 1.2.

ACCEPTS: float

set_ma(align)
alias for set_verticalalignment
set_multialignment(align)

Set the alignment for multiple lines layout. The layout of the bounding box of all the lines is determined bu the horizontalalignment and verticalalignment properties, but the multiline text within that box can be

ACCEPTS: [‘left’ | ‘right’ | ‘center’ ]

set_name(fontname)

Set the font name,

ACCEPTS: string eg, [‘Sans’ | ‘Courier’ | ‘Helvetica’ ...]

set_position(xy)

Set the xy position of the text

ACCEPTS: (x,y)

set_rotation(s)

Set the rotation of the text

ACCEPTS: [ angle in degrees ‘vertical’ | ‘horizontal’

set_size(fontsize)

Set the font size, eg, 8, 10, 12, 14...

ACCEPTS: [ size in points | relative size eg ‘smaller’, ‘x-large’ ]

set_style(fontstyle)

Set the font style

ACCEPTS: [ ‘normal’ | ‘italic’ | ‘oblique’]

set_text(s)

Set the text string s

ACCEPTS: string or anything printable with ‘%s’ conversion

set_va(align)
alias for set_verticalalignment
set_variant(variant)

Set the font variant, eg,

ACCEPTS: [ ‘normal’ | ‘small-caps’ ]

set_verticalalignment(align)

Set the vertical alignment

ACCEPTS: [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ]

set_weight(weight)

Set the font weight

ACCEPTS: [ ‘normal’ | ‘bold’ | ‘heavy’ | ‘light’ | ‘ultrabold’ | ‘ultralight’]

set_x(x)

Set the x position of the text

ACCEPTS: float

set_y(y)

Set the y position of the text

ACCEPTS: float

update_from(other)
Copy properties from other to self
class matplotlib.text.TextWithDash(x=0, y=0, text='', color=None, verticalalignment='center', horizontalalignment='center', multialignment=None, fontproperties=None, rotation=None, linespacing=None, dashlength=0.0, dashdirection=0, dashrotation=None, dashpad=3, dashpush=0, xaxis=True)

Bases: matplotlib.text.Text

This is basically a Text with a dash (drawn with a Line2D) before/after it. It is intended to be a drop-in replacement for Text, and should behave identically to it when dashlength = 0.0.

The dash always comes between the point specified by set_position() and the text. When a dash exists, the text alignment arguments (horizontalalignment, verticalalignment) are ignored.

dashlength is the length of the dash in canvas units. (default = 0.0).

dashdirection is one of 0 or 1, where 0 draws the dash after the text and 1 before. (default = 0).

dashrotation specifies the rotation of the dash, and should generally stay None. In this case get_dashrotation() returns get_rotation(). (I.e., the dash takes its rotation from the text’s rotation). Because the text center is projected onto the dash, major deviations in the rotation cause what may be considered visually unappealing results. (default = None)

dashpad is a padding length to add (or subtract) space between the text and the dash, in canvas units. (default = 3)

dashpush “pushes” the dash and text away from the point specified by set_position() by the amount in canvas units. (default = 0)

NOTE: The alignment of the two objects is based on the bounding box of the Text, as obtained by get_window_extent(). This, in turn, appears to depend on the font metrics as given by the rendering backend. Hence the quality of the “centering” of the label text with respect to the dash varies depending on the backend used.

NOTE 2: I’m not sure that I got the get_window_extent() right, or whether that’s sufficient for providing the object bounding box.

draw(renderer)
get_dashdirection()
get_dashlength()
get_dashpad()
get_dashpush()
get_dashrotation()
get_figure()
return the figure instance
get_position()
Return x, y as tuple
get_prop_tup()

Return a hashable tuple of properties.

Not intended to be human readable, but useful for backends who want to cache derived information about text (eg layouts) and need to know if the text has changed.

get_window_extent(renderer=None)
set_dashdirection(dd)

Set the direction of the dash following the text. 1 is before the text and 0 is after. The default is 0, which is what you’d want for the typical case of ticks below and on the left of the figure.

ACCEPTS: int

set_dashlength(dl)

Set the length of the dash.

ACCEPTS: float

set_dashpad(dp)

Set the “pad” of the TextWithDash, which is the extra spacing between the dash and the text, in canvas units.

ACCEPTS: float

set_dashpush(dp)

Set the “push” of the TextWithDash, which is the extra spacing between the beginning of the dash and the specified position.

ACCEPTS: float

set_dashrotation(dr)

Set the rotation of the dash.

ACCEPTS: float

set_figure(fig)

Set the figure instance the artist belong to.

ACCEPTS: a matplotlib.figure.Figure instance

set_position(xy)

Set the xy position of the TextWithDash.

ACCEPTS: (x,y)

set_transform(t)

Set the Transformation instance used by this artist.

ACCEPTS: a matplotlib.transform transformation instance

set_x(x)

Set the x position of the TextWithDash.

ACCEPTS: float

set_y(y)

Set the y position of the TextWithDash.

ACCEPTS: float

update_coords(renderer)
Computes the actual x,y coordinates for text based on the input x,y and the dashlength. Since the rotation is with respect to the actual canvas’s coordinates we need to map back and forth.
matplotlib.text.get_rotation(rotation)
return the text angle as float