matplotlib.quiver.QuiverKey

class matplotlib.quiver.QuiverKey(Q, X, Y, U, label, *, angle=0, coordinates='axes', color=None, labelsep=0.1, labelpos='N', labelcolor=None, fontproperties=None, zorder=None, **kwargs)

Bases: Artist

Labelled arrow for use as a quiver plot scale key.

Add a key to a quiver plot.

The positioning of the key depends on X, Y, coordinates, and labelpos. If labelpos is 'N' or 'S', X, Y give the position of the middle of the key arrow. If labelpos is 'E', X, Y positions the head, and if labelpos is 'W', X, Y positions the tail; in either of these two cases, X, Y is somewhere in the middle of the arrow+label key object.

Parameters:

QQuiver

A Quiver object as returned by a call to quiver().

X, Yfloat

The location of the key.

Ufloat

The length of the key.

labelstr

The key label (e.g., length and units of the key).

anglefloat, default: 0

The angle of the key arrow, in degrees anti-clockwise from the horizontal axis.

coordinates{'axes', 'figure', 'data', 'inches'}, default: 'axes'

Coordinate system and units for X, Y: 'axes' and 'figure' are normalized coordinate systems with (0, 0) in the lower left and (1, 1) in the upper right; 'data' are the axes data coordinates (used for the locations of the vectors in the quiver plot itself); 'inches' is position in the figure in inches, with (0, 0) at the lower left corner.

colorcolor

Overrides face and edge colors from Q.

labelpos{'N', 'S', 'E', 'W'}

Position the label above, below, to the right, to the left of the arrow, respectively.

labelsepfloat, default: 0.1

Distance in inches between the arrow and the label.

labelcolorcolor, default: rcParams["text.color"] (default: 'black')

Label color.

fontpropertiesdict, optional

A dictionary with keyword arguments accepted by the FontProperties initializer: family, style, variant, size, weight.

zorderfloat

The zorder of the key. The default is 0.1 above Q.

**kwargs

Any additional keyword arguments are used to override vector properties taken from Q.

contains(mouseevent)

Test whether the artist contains the mouse event.

Parameters:

mouseeventMouseEvent

Returns:

containsbool

Whether any values are within the radius.

detailsdict

An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.

draw(renderer)

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:

rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

property fontproperties

[Deprecated]

Notes

Deprecated since version 3.11: Use quiverkey.text.get_fontproperties() instead.

halign = {'E': 'left', 'N': 'center', 'S': 'center', 'W': 'right'}

property kw

[Deprecated]

Notes

Deprecated since version 3.11:

property labelcolor

[Deprecated]

Notes

Deprecated since version 3.11: Use quiverkey.text.get_color() instead.

property labelsep

pivot = {'E': 'tip', 'N': 'middle', 'S': 'middle', 'W': 'tail'}

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or None
animated	bool
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
figure	unknown
gid	str
in_layout	bool
label	object
mouseover	bool
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
rasterized	bool
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
visible	bool
zorder	float

set_figure(fig)

Set the Figure or SubFigure instance the artist belongs to.

Warning

This function should typically not be called by users.

This is a low-level API and only modifies the internal state of the Artist. Only modifying this is not enough and will typically lead to an inconsistent state, because the state of the figure has to be changed as well.

Users should typically instead call one of the high-level APIs, i.e. Figure.add_artist or one of the Axes methods Adding artists.

Parameters:

figFigure or SubFigure

valign = {'E': 'center', 'N': 'bottom', 'S': 'top', 'W': 'center'}

property verts

[Deprecated]

Notes

Deprecated since version 3.11: Use [p.vertices for p in quiverkey.vector.get_paths()] instead.

Examples using matplotlib.quiver.QuiverKey

Advanced quiver and quiverkey functions

Advanced quiver and quiverkey functions