You are reading an old version of the documentation (v1.3.0). For the latest version see https://matplotlib.org/stable/api/collections_api.html
matplotlib

Table Of Contents

Previous topic

cm (colormap)

Next topic

colorbar

This Page

collections

Inheritance diagram of matplotlib.collections

matplotlib.collections

Classes for the efficient drawing of large collections of objects that share most properties, e.g., a large number of line segments or polygons.

The classes are not meant to be as flexible as their single element counterparts (e.g., you may not be able to select all line styles) but they are meant to be fast for common use cases (e.g., a large set of solid line segemnts)

class matplotlib.collections.AsteriskPolygonCollection(numsides, rotation=0, sizes=(1, ), **kwargs)

Bases: matplotlib.collections.RegularPolyCollection

Draw a collection of regular asterisks with numsides points.

numsides
the number of sides of the polygon
rotation
the rotation of the polygon in radians
sizes

gives the area of the circle circumscribing the regular polygon in points^2

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

Example: see examples/dynamic_collection.py for complete example:

offsets = np.random.rand(20,2)
facecolors = [cm.jet(x) for x in np.random.rand(20)]
black = (0,0,0,1)

collection = RegularPolyCollection(
    numsides=5, # a pentagon
    rotation=0, sizes=(50,),
    facecolors = facecolors,
    edgecolors = (black,),
    linewidths = (1,),
    offsets = offsets,
    transOffset = ax.transData,
    )
class matplotlib.collections.BrokenBarHCollection(xranges, yrange, **kwargs)

Bases: matplotlib.collections.PolyCollection

A collection of horizontal bars spanning yrange with a sequence of xranges.

xranges
sequence of (xmin, xwidth)
yrange

ymin, ywidth

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

static span_where(x, ymin, ymax, where, **kwargs)

Create a BrokenBarHCollection to plot horizontal bars from over the regions in x where where is True. The bars range on the y-axis from ymin to ymax

A BrokenBarHCollection is returned. kwargs are passed on to the collection.

class matplotlib.collections.CircleCollection(sizes, **kwargs)

Bases: matplotlib.collections.Collection

A collection of circles, drawn using splines.

sizes Gives the area of the circle in points^2

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

draw(artist, renderer, *args, **kwargs)
get_sizes()

return sizes of circles

class matplotlib.collections.Collection(edgecolors=None, facecolors=None, linewidths=None, linestyles='solid', antialiaseds=None, offsets=None, transOffset=None, norm=None, cmap=None, pickradius=5.0, hatch=None, urls=None, offset_position='screen', zorder=1, **kwargs)

Bases: matplotlib.artist.Artist, matplotlib.cm.ScalarMappable

Base class for Collections. Must be subclassed to be usable.

All properties in a collection must be sequences or scalars; if scalars, they will be converted to sequences. The property of the ith element of the collection is:

prop[i % len(props)]

Keyword arguments and default values:

  • edgecolors: None
  • facecolors: None
  • linewidths: None
  • antialiaseds: None
  • offsets: None
  • transOffset: transforms.IdentityTransform()
  • offset_position: ‘screen’ (default) or ‘data’
  • norm: None (optional for matplotlib.cm.ScalarMappable)
  • cmap: None (optional for matplotlib.cm.ScalarMappable)
  • hatch: None
  • zorder: 1

offsets and transOffset are used to translate the patch after rendering (default no offsets). If offset_position is ‘screen’ (default) the offset is applied after the master transform has been applied, that is, the offsets are in screen coordinates. If offset_position is ‘data’, the offset is applied before the master transform, i.e., the offsets are in data coordinates.

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

The use of ScalarMappable is optional. If the ScalarMappable matrix _A is not None (ie a call to set_array has been made), at draw time a call to scalar mappable will be made to set the face colors.

Create a Collection

%(Collection)s

contains(mouseevent)

Test whether the mouse event occurred in the collection.

Returns True | False, dict(ind=itemlist), where every item in itemlist contains the event.

draw(artist, renderer, *args, **kwargs)
get_dashes()
get_datalim(transData)
get_edgecolor()
get_edgecolors()
get_facecolor()
get_facecolors()
get_hatch()

Return the current hatching pattern

get_linestyle()
get_linestyles()
get_linewidth()
get_linewidths()
get_offset_position()

Returns how offsets are applied for the collection. If offset_position is ‘screen’, the offset is applied after the master transform has been applied, that is, the offsets are in screen coordinates. If offset_position is ‘data’, the offset is applied before the master transform, i.e., the offsets are in data coordinates.

get_offset_transform()
get_offsets()

Return the offsets for the collection.

get_paths()
get_pickradius()
get_transforms()
get_urls()
get_window_extent(renderer)
set_alpha(alpha)

Set the alpha tranparencies of the collection. alpha must be a float or None.

ACCEPTS: float or None

set_antialiased(aa)

Set the antialiasing state for rendering.

ACCEPTS: Boolean or sequence of booleans

set_antialiaseds(aa)

alias for set_antialiased

set_color(c)

Set both the edgecolor and the facecolor.

ACCEPTS: matplotlib color arg or sequence of rgba tuples

See also

set_facecolor(), set_edgecolor()
For setting the edge or face color individually.
set_dashes(ls)

alias for set_linestyle

set_edgecolor(c)

Set the edgecolor(s) of the collection. c can be a matplotlib color arg (all patches have same color), or a sequence of rgba tuples; if it is a sequence the patches will cycle through the sequence.

If c is ‘face’, the edge color will always be the same as the face color. If it is ‘none’, the patch boundary will not be drawn.

ACCEPTS: matplotlib color arg or sequence of rgba tuples

set_edgecolors(c)

alias for set_edgecolor

set_facecolor(c)

Set the facecolor(s) of the collection. c can be a matplotlib color arg (all patches have same color), or a sequence of rgba tuples; if it is a sequence the patches will cycle through the sequence.

If c is ‘none’, the patch will not be filled.

ACCEPTS: matplotlib color arg or sequence of rgba tuples

set_facecolors(c)

alias for set_facecolor

set_hatch(hatch)

Set the hatching pattern

hatch can be one of:

/   - diagonal hatching
\   - back diagonal
|   - vertical
-   - horizontal
+   - crossed
x   - crossed diagonal
o   - small circle
O   - large circle
.   - dots
*   - stars

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

Hatching is supported in the PostScript, PDF, SVG and Agg backends only.

Unlike other properties such as linewidth and colors, hatching can only be specified for the collection as a whole, not separately for each member.

ACCEPTS: [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ]

set_linestyle(ls)

Set the linestyle(s) for the collection.

ACCEPTS: [‘solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (offset, on-off-dash-seq) ]

set_linestyles(ls)

alias for set_linestyle

set_linewidth(lw)

Set the linewidth(s) for the collection. lw can be a scalar or a sequence; if it is a sequence the patches will cycle through the sequence

ACCEPTS: float or sequence of floats

set_linewidths(lw)

alias for set_linewidth

set_lw(lw)

alias for set_linewidth

set_offset_position(offset_position)

Set how offsets are applied. If offset_position is ‘screen’ (default) the offset is applied after the master transform has been applied, that is, the offsets are in screen coordinates. If offset_position is ‘data’, the offset is applied before the master transform, i.e., the offsets are in data coordinates.

set_offsets(offsets)

Set the offsets for the collection. offsets can be a scalar or a sequence.

ACCEPTS: float or sequence of floats

set_paths()
set_pickradius(pr)
set_urls(urls)
update_from(other)

copy properties from other to self

update_scalarmappable()

If the scalar mappable array is not none, update colors from scalar data

class matplotlib.collections.EllipseCollection(widths, heights, angles, units='points', **kwargs)

Bases: matplotlib.collections.Collection

A collection of ellipses, drawn using splines.

widths: sequence
lengths of first axes (e.g., major axis lengths)
heights: sequence
lengths of second axes
angles: sequence
angles of first axes, degrees CCW from the X-axis

units: [‘points’ | ‘inches’ | ‘dots’ | ‘width’ | ‘height’ | ‘x’ | ‘y’ | ‘xy’]

units in which majors and minors are given; ‘width’ and ‘height’ refer to the dimensions of the axes, while ‘x’ and ‘y’ refer to the offsets data units. ‘xy’ differs from all others in that the angle as plotted varies with the aspect ratio, and equals the specified angle only when the aspect ratio is unity. Hence it behaves the same as the Ellipse with axes.transData as its transform.

Additional kwargs inherited from the base Collection:

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

draw(artist, renderer, *args, **kwargs)
class matplotlib.collections.EventCollection(positions, orientation=None, lineoffset=0, linelength=1, linewidth=None, color=None, linestyle='solid', antialiased=None, **kwargs)

Bases: matplotlib.collections.LineCollection

A collection of discrete events.

An event is a 1-dimensional value, usually the position of something along an axis, such as time or length. Events do not have an amplitude. They are displayed as v

positions
a sequence of numerical values or a 1D numpy array. Can be None
orientation [ ‘horizontal’ | ‘vertical’ | None ]
defaults to ‘horizontal’ if not specified or None
lineoffset
a single numerical value, corresponding to the offset of the center of the markers from the origin
linelength
a single numerical value, corresponding to the total height of the marker (i.e. the marker stretches from lineoffset+linelength/2 to lineoffset-linelength/2). Defaults to 1
linewidth
a single numerical value
color
must be a sequence of RGBA tuples (eg arbitrary color strings, etc, not allowed).

linestyle [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ]

antialiased
1 or 2

If linewidth, color, or antialiased is None, they default to their rcParams setting, in sequence form.

norm
None (optional for matplotlib.cm.ScalarMappable)
cmap
None (optional for matplotlib.cm.ScalarMappable)

pickradius is the tolerance for mouse clicks picking a line. The default is 5 pt.

The use of ScalarMappable is optional. If the ScalarMappable array _A is not None (ie a call to set_array() has been made), at draw time a call to scalar mappable will be made to set the colors.

Example:

(Source code, png, hires.png, pdf)

../_images/eventcollection_demo.png
add_positions(position)

add one or more events at the specified positions

append_positions(position)

add one or more events at the specified positions

extend_positions(position)

add one or more events at the specified positions

get_color()

get the color of the lines used to mark each event

get_linelength()

get the length of the lines used to mark each event

get_lineoffset()

get the offset of the lines used to mark each event

get_linestyle()

get the style of the lines used to mark each event [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ]

get_linewidth()

get the width of the lines used to mark each event

get_orientation()

get the orientation of the event line, may be: [ ‘horizontal’ | ‘vertical’ ]

get_positions()

return an array containing the floating-point values of the positions

is_horizontal()

True if the eventcollection is horizontal, False if vertical

set_linelength(linelength)

set the length of the lines used to mark each event

set_lineoffset(lineoffset)

set the offset of the lines used to mark each event

set_orientation(orientation=None)

set the orientation of the event line [ ‘horizontal’ | ‘vertical’ | None ] defaults to ‘horizontal’ if not specified or None

set_positions(positions)

set the positions of the events to the specified value

switch_orientation()

switch the orientation of the event line, either from vertical to horizontal or vice versus

class matplotlib.collections.LineCollection(segments, linewidths=None, colors=None, antialiaseds=None, linestyles='solid', offsets=None, transOffset=None, norm=None, cmap=None, pickradius=5, zorder=2, **kwargs)

Bases: matplotlib.collections.Collection

All parameters must be sequences or scalars; if scalars, they will be converted to sequences. The property of the ith line segment is:

prop[i % len(props)]

i.e., the properties cycle if the len of props is less than the number of segments.

segments

a sequence of (line0, line1, line2), where:

linen = (x0, y0), (x1, y1), ... (xm, ym)

or the equivalent numpy array with two columns. Each line can be a different length.

colors
must be a sequence of RGBA tuples (eg arbitrary color strings, etc, not allowed).
antialiaseds
must be a sequence of ones or zeros
linestyles [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ]

a string or dash tuple. The dash tuple is:

(offset, onoffseq),

where onoffseq is an even length tuple of on and off ink in points.

If linewidths, colors, or antialiaseds is None, they default to their rcParams setting, in sequence form.

If offsets and transOffset are not None, then offsets are transformed by transOffset and applied after the segments have been transformed to display coordinates.

If offsets is not None but transOffset is None, then the offsets are added to the segments before any transformation. In this case, a single offset can be specified as:

offsets=(xo,yo)

and this value will be added cumulatively to each successive segment, so as to produce a set of successively offset curves.

norm
None (optional for matplotlib.cm.ScalarMappable)
cmap
None (optional for matplotlib.cm.ScalarMappable)

pickradius is the tolerance for mouse clicks picking a line. The default is 5 pt.

zorder
The zorder of the LineCollection. Default is 2

The use of ScalarMappable is optional. If the ScalarMappable array _A is not None (ie a call to set_array() has been made), at draw time a call to scalar mappable will be made to set the colors.

color(c)

Set the color(s) of the line collection. c can be a matplotlib color arg (all patches have same color), or a sequence or rgba tuples; if it is a sequence the patches will cycle through the sequence

ACCEPTS: matplotlib color arg or sequence of rgba tuples

get_color()
get_colors()
get_segments()
set_color(c)

Set the color(s) of the line collection. c can be a matplotlib color arg (all patches have same color), or a sequence or rgba tuples; if it is a sequence the patches will cycle through the sequence.

ACCEPTS: matplotlib color arg or sequence of rgba tuples

set_paths(segments)
set_segments(segments)
set_verts(segments)
class matplotlib.collections.PatchCollection(patches, match_original=False, **kwargs)

Bases: matplotlib.collections.Collection

A generic collection of patches.

This makes it easier to assign a color map to a heterogeneous collection of patches.

This also may improve plotting speed, since PatchCollection will draw faster than a large number of patches.

patches
a sequence of Patch objects. This list may include a heterogeneous assortment of different patch types.
match_original
If True, use the colors and linewidths of the original patches. If False, new colors may be assigned by providing the standard collection arguments, facecolor, edgecolor, linewidths, norm or cmap.

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

The use of ScalarMappable is optional. If the ScalarMappable matrix _A is not None (ie a call to set_array has been made), at draw time a call to scalar mappable will be made to set the face colors.

set_paths(patches)
class matplotlib.collections.PathCollection(paths, sizes=None, **kwargs)

Bases: matplotlib.collections.Collection

This is the most basic Collection subclass.

paths is a sequence of matplotlib.path.Path instances.

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

draw(artist, renderer, *args, **kwargs)
get_paths()
get_sizes()
set_paths(paths)
class matplotlib.collections.PolyCollection(verts, sizes=None, closed=True, **kwargs)

Bases: matplotlib.collections.Collection

verts is a sequence of ( verts0, verts1, ...) where verts_i is a sequence of xy tuples of vertices, or an equivalent numpy array of shape (nv, 2).

sizes is None (default) or a sequence of floats that scale the corresponding verts_i. The scaling is applied before the Artist master transform; if the latter is an identity transform, then the overall scaling is such that if verts_i specify a unit square, then sizes_i is the area of that square in points^2. If len(sizes) < nv, the additional values will be taken cyclically from the array.

closed, when True, will explicitly close the polygon.

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

draw(artist, renderer, *args, **kwargs)
set_paths(verts, closed=True)

This allows one to delay initialization of the vertices.

set_verts(verts, closed=True)

This allows one to delay initialization of the vertices.

class matplotlib.collections.QuadMesh(meshWidth, meshHeight, coordinates, antialiased=True, shading='flat', **kwargs)

Bases: matplotlib.collections.Collection

Class for the efficient drawing of a quadrilateral mesh.

A quadrilateral mesh consists of a grid of vertices. The dimensions of this array are (meshWidth + 1, meshHeight + 1). Each vertex in the mesh has a different set of “mesh coordinates” representing its position in the topology of the mesh. For any values (m, n) such that 0 <= m <= meshWidth and 0 <= n <= meshHeight, the vertices at mesh coordinates (m, n), (m, n + 1), (m + 1, n + 1), and (m + 1, n) form one of the quadrilaterals in the mesh. There are thus (meshWidth * meshHeight) quadrilaterals in the mesh. The mesh need not be regular and the polygons need not be convex.

A quadrilateral mesh is represented by a (2 x ((meshWidth + 1) * (meshHeight + 1))) numpy array coordinates, where each row is the x and y coordinates of one of the vertices. To define the function that maps from a data point to its corresponding color, use the set_cmap() method. Each of these arrays is indexed in row-major order by the mesh coordinates of the vertex (or the mesh coordinates of the lower left vertex, in the case of the colors).

For example, the first entry in coordinates is the coordinates of the vertex at mesh coordinates (0, 0), then the one at (0, 1), then at (0, 2) .. (0, meshWidth), (1, 0), (1, 1), and so on.

shading may be ‘flat’, or ‘gouraud’

static convert_mesh_to_paths(meshWidth, meshHeight, coordinates)

Converts a given mesh into a sequence of matplotlib.path.Path objects for easier rendering by backends that do not directly support quadmeshes.

This function is primarily of use to backend implementers.

convert_mesh_to_triangles(meshWidth, meshHeight, coordinates)

Converts a given mesh into a sequence of triangles, each point with its own color. This is useful for experiments using draw_qouraud_triangle.

draw(artist, renderer, *args, **kwargs)
get_datalim(transData)
get_paths()
set_paths()
class matplotlib.collections.RegularPolyCollection(numsides, rotation=0, sizes=(1, ), **kwargs)

Bases: matplotlib.collections.Collection

Draw a collection of regular polygons with numsides.

numsides
the number of sides of the polygon
rotation
the rotation of the polygon in radians
sizes

gives the area of the circle circumscribing the regular polygon in points^2

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

Example: see examples/dynamic_collection.py for complete example:

offsets = np.random.rand(20,2)
facecolors = [cm.jet(x) for x in np.random.rand(20)]
black = (0,0,0,1)

collection = RegularPolyCollection(
    numsides=5, # a pentagon
    rotation=0, sizes=(50,),
    facecolors = facecolors,
    edgecolors = (black,),
    linewidths = (1,),
    offsets = offsets,
    transOffset = ax.transData,
    )
draw(artist, renderer, *args, **kwargs)
get_numsides()
get_rotation()
get_sizes()
class matplotlib.collections.StarPolygonCollection(numsides, rotation=0, sizes=(1, ), **kwargs)

Bases: matplotlib.collections.RegularPolyCollection

Draw a collection of regular stars with numsides points.

numsides
the number of sides of the polygon
rotation
the rotation of the polygon in radians
sizes

gives the area of the circle circumscribing the regular polygon in points^2

Valid Collection keyword arguments:

offsets and transOffset are used to translate the patch after rendering (default no offsets)

If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form.

Example: see examples/dynamic_collection.py for complete example:

offsets = np.random.rand(20,2)
facecolors = [cm.jet(x) for x in np.random.rand(20)]
black = (0,0,0,1)

collection = RegularPolyCollection(
    numsides=5, # a pentagon
    rotation=0, sizes=(50,),
    facecolors = facecolors,
    edgecolors = (black,),
    linewidths = (1,),
    offsets = offsets,
    transOffset = ax.transData,
    )
class matplotlib.collections.TriMesh(triangulation, **kwargs)

Bases: matplotlib.collections.Collection

Class for the efficient drawing of a triangular mesh using Gouraud shading.

A triangular mesh is a Triangulation object.

static convert_mesh_to_paths(tri)

Converts a given mesh into a sequence of matplotlib.path.Path objects for easier rendering by backends that do not directly support meshes.

This function is primarily of use to backend implementers.

draw(artist, renderer, *args, **kwargs)
get_paths()
set_paths()