Matplotlib

classmatplotlib.text.Annotation(text, xy, xytext=None, xycoords='data', textcoords=None, arrowprops=None, annotation_clip=None, **kwargs)[source]

Bases: matplotlib.text.Text, matplotlib.text._AnnotationBase

An Annotation is a Text that can refer to a specific position xy. Optionally an arrow pointing from the text to xy can be drawn.

Attributes

xy: The annotated position.
xycoords: The coordinate system for xy.
arrow_patch: A FancyArrowPatch to point from xytext to xy.

Annotate the point xy with text text.

In the simplest form, the text is placed at xy.

Optionally, the text can be displayed in another position xytext. An arrow pointing from the text to the annotated point xy can then be added by defining arrowprops.

Parameters

textstr

The text of the annotation.

xy(float, float)

The point (x, y) to annotate. The coordinate system is determined by xycoords.

xytext(float, float), default: xy

The position (x, y) to place the text at. The coordinate system is determined by textcoords.

xycoordsstr or Artist or Transform or callable or (float, float), default: 'data'

The coordinate system that xy is given in. The following types of values are supported:

One of the following strings:

Value	Description
'figure points'	Points from the lower left of the figure
'figure pixels'	Pixels from the lower left of the figure
'figure fraction'	Fraction of figure from lower left
'subfigure points'	Points from the lower left of the subfigure
'subfigure pixels'	Pixels from the lower left of the subfigure
'subfigure fraction'	Fraction of subfigure from lower left
'axes points'	Points from lower left corner of axes
'axes pixels'	Pixels from lower left corner of axes
'axes fraction'	Fraction of axes from lower left
'data'	Use the coordinate system of the object being annotated (default)
'polar'	(theta, r) if not native 'data' coordinates

Note that 'subfigure pixels' and 'figure pixels' are the same for the parent figure, so users who want code that is usable in a subfigure can use 'subfigure pixels'.

An Artist: xy is interpreted as a fraction of the artist's Bbox. E.g. (0, 0) would be the lower left corner of the bounding box and (0.5, 1) would be the center top of the bounding box.
A Transform to transform xy to screen coordinates.
A function with one of the following signatures:
```
def transform(renderer) -> Bbox
def transform(renderer) -> Transform
```
where renderer is a RendererBase subclass.

The result of the function is interpreted like the Artist and Transform cases above.
A tuple (xcoords, ycoords) specifying separate coordinate systems for x and y. xcoords and ycoords must each be of one of the above described types.

See Advanced Annotations for more details.

textcoordsstr or Artist or Transform or callable or (float, float), default: value of xycoords

The coordinate system that xytext is given in.

All xycoords values are valid as well as the following strings:

Value	Description
'offset points'	Offset (in points) from the xy value
'offset pixels'	Offset (in pixels) from the xy value

arrowpropsdict, optional

The properties used to draw a FancyArrowPatch arrow between the positions xy and xytext. Defaults to None, i.e. no arrow is drawn.

For historical reasons there are two different ways to specify arrows, "simple" and "fancy":

Simple arrow:

If arrowprops does not contain the key 'arrowstyle' the allowed keys are:

Key	Description
width	The width of the arrow in points
headwidth	The width of the base of the arrow head in points
headlength	The length of the arrow head in points
shrink	Fraction of total length to shrink from both ends
?	Any key to `matplotlib.patches.FancyArrowPatch`

The arrow is attached to the edge of the text box, the exact position (corners or centers) depending on where it's pointing to.

Fancy arrow:

This is used if 'arrowstyle' is provided in the arrowprops.

Valid keys are the following FancyArrowPatch parameters:

Key	Description
arrowstyle	the arrow style
connectionstyle	the connection style
relpos	see below; default is (0.5, 0.5)
patchA	default is bounding box of the text
patchB	default is None
shrinkA	default is 2 points
shrinkB	default is 2 points
mutation_scale	default is text size (in points)
mutation_aspect	default is 1.
?	any key for `matplotlib.patches.PathPatch`

The exact starting point position of the arrow is defined by relpos. It's a tuple of relative coordinates of the text box, where (0, 0) is the lower left corner and (1, 1) is the upper right corner. Values <0 and >1 are supported and specify points outside the text box. By default (0.5, 0.5) the starting point is centered in the text box.

annotation_clipbool or None, default: None

Whether to draw the annotation when the annotation point xy is outside the axes area.

If True, the annotation will only be drawn when xy is within the axes.
If False, the annotation will always be drawn.
If None, the annotation will only be drawn when xy is within the axes and xycoords is 'data'.

**kwargs

Additional kwargs are passed to Text.

Returns

Annotation

See also

Advanced Annotations

propertyanncoords: The coordinate system to use for Annotation.xyann.

contains(event)[source]: Return whether the mouse event occurred inside the axis-aligned bounding-box of the text.

draw(renderer)[source]

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.

get_anncoords()[source]

Return the coordinate system to use for Annotation.xyann.

Notes

This method is overridden in the Artist subclasses.

get_bbox_patch()[source]: Return the bbox Patch, or None if the patches.FancyBboxPatch is not made.

get_c()[source]: Alias for get_color.

get_color()[source]: Return the color of the text.

get_family()[source]: Alias for get_fontfamily.

get_font()[source]: Alias for get_fontproperties.

get_font_properties()[source]: Alias for get_fontproperties.

get_fontfamily()[source]

Return the list of font families used for font lookup.

See also

font_manager.FontProperties.get_family

get_fontname()[source]

Return the font name as a string.

See also

font_manager.FontProperties.get_name

get_fontproperties()[source]: Return the font_manager.FontProperties.

get_fontsize()[source]

Return the font size as an integer.

See also

font_manager.FontProperties.get_size_in_points

get_fontstyle()[source]

Return the font style as a string.

See also

font_manager.FontProperties.get_style

get_fontvariant()[source]

Return the font variant as a string.

See also

font_manager.FontProperties.get_variant

get_fontweight()[source]

Return the font weight as a string or a number.

See also

font_manager.FontProperties.get_weight

get_ha()[source]: Alias for get_horizontalalignment.

get_horizontalalignment()[source]: Return the horizontal alignment as a string. Will be one of 'left', 'center' or 'right'.

get_math_fontfamily()[source]

Return the font family name for math text rendered by Matplotlib.

The default value is rcParams["mathtext.fontset"] (default: 'dejavusans').

See also

set_math_fontfamily

get_name()[source]: Alias for get_fontname.

get_parse_math()[source]: Return whether mathtext parsing is considered for this Text.

get_position()[source]: Return the (x, y) position of the text.

get_prop_tup(renderer=None)[source]

[Deprecated] Return a hashable tuple of properties.

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

Notes

Deprecated since version 3.5.

get_rotation()[source]: Return the text angle in degrees between 0 and 360.

get_rotation_mode()[source]: Return the text rotation mode.

get_size()[source]: Alias for get_fontsize.

get_stretch()[source]

Return the font stretch as a string or a number.

See also

font_manager.FontProperties.get_stretch

get_style()[source]: Alias for get_fontstyle.

get_text()[source]: Return the text string.

get_transform_rotates_text()[source]: Return whether rotations of the transform affect the text direction.

get_unitless_position()[source]: Return the (x, y) unitless position of the text.

get_usetex()[source]: Return whether this Text object uses TeX for rendering.

get_va()[source]: Alias for get_verticalalignment.

get_variant()[source]: Alias for get_fontvariant.

get_verticalalignment()[source]: Return the vertical alignment as a string. Will be one of 'top', 'center', 'bottom', 'baseline' or 'center_baseline'.

get_weight()[source]: Alias for get_fontweight.

get_window_extent(renderer=None, dpi=None)[source]

Return the Bbox bounding the text, in display units.

In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.

Parameters

rendererRenderer, optional: A renderer is needed to compute the bounding box. If the artist has already been drawn, the renderer is cached; thus, it is only necessary to pass this argument when calling get_window_extent before the first draw. In practice, it is usually easier to trigger a draw first (e.g. by saving the figure).
dpifloat, optional: The dpi value for computing the bbox, defaults to self.figure.dpi (not the renderer dpi); should be set e.g. if to match regions with a figure saved with a custom dpi value.

get_wrap()[source]: Return whether the text can be wrapped.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, backgroundcolor=<UNSET>, bbox=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, fontfamily=<UNSET>, fontproperties=<UNSET>, fontsize=<UNSET>, fontstretch=<UNSET>, fontstyle=<UNSET>, fontvariant=<UNSET>, fontweight=<UNSET>, gid=<UNSET>, horizontalalignment=<UNSET>, in_layout=<UNSET>, label=<UNSET>, linespacing=<UNSET>, math_fontfamily=<UNSET>, multialignment=<UNSET>, parse_math=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, rasterized=<UNSET>, rotation=<UNSET>, rotation_mode=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text=<UNSET>, transform=<UNSET>, transform_rotates_text=<UNSET>, url=<UNSET>, usetex=<UNSET>, verticalalignment=<UNSET>, visible=<UNSET>, wrap=<UNSET>, x=<UNSET>, y=<UNSET>, zorder=<UNSET>)[source]

Set multiple properties at once.

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
`alpha`	scalar or None
`animated`	bool
`backgroundcolor`	color
`bbox`	dict with properties for `patches.FancyBboxPatch`
`clip_box`	unknown
`clip_on`	unknown
`clip_path`	unknown
`color`	color
`figure`	`Figure`
`fontfamily`	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
`fontproperties`	`font_manager.FontProperties` or `str` or `pathlib.Path`
`fontsize`	float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
`fontstretch`	{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
`fontstyle`	{'normal', 'italic', 'oblique'}
`fontvariant`	{'normal', 'small-caps'}
`fontweight`	{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
`gid`	str
`horizontalalignment`	{'center', 'right', 'left'}
`in_layout`	bool
`label`	object
`linespacing`	float (multiple of font size)
`math_fontfamily`	str
`multialignment`	{'left', 'right', 'center'}
`parse_math`	bool
`path_effects`	`AbstractPathEffect`
`picker`	None or bool or float or callable
`position`	(float, float)
`rasterized`	bool
`rotation`	float or {'vertical', 'horizontal'}
`rotation_mode`	{None, 'default', 'anchor'}
`sketch_params`	(scale: float, length: float, randomness: float)
`snap`	bool or None
`text`	object
`transform`	`Transform`
`transform_rotates_text`	bool
`url`	str
`usetex`	bool or None
`verticalalignment`	{'center', 'top', 'bottom', 'baseline', 'center_baseline'}
`visible`	bool
`wrap`	bool
`x`	float
`y`	float
`zorder`	float

set_backgroundcolor(color)[source]

Set the background color of the text by updating the bbox.

Parameters

colorcolor

See also

set_bbox: To change the position of the bounding box

set_bbox(rectprops)[source]

Draw a bounding box around self.

Parameters

rectpropsdict with properties for patches.FancyBboxPatch: The default boxstyle is 'square'. The mutation scale of the patches.FancyBboxPatch is set to the fontsize.

Examples

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

set_c(color)[source]: Alias for set_color.

set_clip_box(clipbox)[source]

Set the artist's clip Bbox.

Parameters

clipboxBbox

set_clip_on(b)[source]

Set whether the artist uses clipping.

When False artists will be visible outside of the axes which can lead to unexpected results.

Parameters

bbool

set_clip_path(path, transform=None)[source]

Set the artist's clip path.

Parameters

pathPatch or Path or TransformedPath or None: The clip path. If given a Path, transform must be provided as well. If None, a previously set clip path is removed.
transformTransform, optional: Only used if path is a Path, in which case the given Path is converted to a TransformedPath using transform.

Notes

For efficiency, if path is a Rectangle this method will set the clipping box to the corresponding rectangle and set the clipping path to None.

For technical reasons (support of set), a tuple (path, transform) is also accepted as a single positional parameter.

set_color(color)[source]

Set the foreground color of the text

Parameters

colorcolor

set_family(fontname)[source]: Alias for set_fontfamily.

set_font(fp)[source]: Alias for set_fontproperties.

set_font_properties(fp)[source]: Alias for set_fontproperties.

set_fontfamily(fontname)[source]

Set the font family. May be either a single string, or a list of strings in decreasing priority. Each string may be either a real font name or a generic font class name. If the latter, the specific font names will be looked up in the corresponding rcParams.

If a Text instance is constructed with fontfamily=None, then the font is set to rcParams["font.family"] (default: ['sans-serif']), and the same is done when set_fontfamily() is called on an existing Text instance.

Parameters

fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

See also

font_manager.FontProperties.set_family

set_fontname(fontname)[source]

Alias for set_family.

One-way alias only: the getter differs.

Parameters

fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

See also

font_manager.FontProperties.set_family

set_fontproperties(fp)[source]

Set the font properties that control the text.

Parameters

fpfont_manager.FontProperties or str or pathlib.Path: If a str, it is interpreted as a fontconfig pattern parsed by FontProperties. If a pathlib.Path, it is interpreted as the absolute path to a font file.

set_fontsize(fontsize)[source]

Set the font size.

Parameters

fontsizefloat or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}: If float, the fontsize in points. The string values denote sizes relative to the default font size.

See also

font_manager.FontProperties.set_size

set_fontstretch(stretch)[source]

Set the font stretch (horizontal condensation or expansion).

Parameters

stretch{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}

See also

font_manager.FontProperties.set_stretch

set_fontstyle(fontstyle)[source]

Set the font style.

Parameters

fontstyle{'normal', 'italic', 'oblique'}

See also

font_manager.FontProperties.set_style

set_fontvariant(variant)[source]

Set the font variant.

Parameters

variant{'normal', 'small-caps'}

See also

font_manager.FontProperties.set_variant

set_fontweight(weight)[source]

Set the font weight.

Parameters

weight{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}

See also

font_manager.FontProperties.set_weight

set_ha(align)[source]: Alias for set_horizontalalignment.

set_horizontalalignment(align)[source]

Set the horizontal alignment to one of

Parameters

align{'center', 'right', 'left'}

set_linespacing(spacing)[source]

Set the line spacing as a multiple of the font size.

The default line spacing is 1.2.

Parameters

spacingfloat (multiple of font size)

set_ma(align)[source]: Alias for set_multialignment.

set_math_fontfamily(fontfamily)[source]

Set the font family for math text rendered by Matplotlib.

This does only affect Matplotlib's own math renderer. It has no effect when rendering with TeX (usetex=True).

Parameters

fontfamilystr

The name of the font family.

Available font families are defined in the matplotlibrc.template file.

See also

get_math_fontfamily

set_multialignment(align)[source]

Set the text alignment for multiline texts.

The layout of the bounding box of all the lines is determined by the horizontalalignment and verticalalignment properties. This property controls the alignment of the text lines within that box.

Parameters

align{'left', 'right', 'center'}

set_name(fontname)[source]: Alias for set_fontname.

set_parse_math(parse_math)[source]

Override switch to disable any mathtext parsing for this Text.

Parameters

parse_mathbool: If False, this Text will never use mathtext. If True, mathtext will be used if there is an even number of unescaped dollar signs.

set_position(xy)[source]

Set the (x, y) position of the text.

Parameters

xy(float, float)

set_rotation(s)[source]

Set the rotation of the text.

Parameters

sfloat or {'vertical', 'horizontal'}: The rotation angle in degrees in mathematically positive direction (counterclockwise). 'horizontal' equals 0, 'vertical' equals 90.

set_rotation_mode(m)[source]

Set text rotation mode.

Parameters

m{None, 'default', 'anchor'}: If None or "default", the text will be first rotated, then aligned according to their horizontal and vertical alignments. If "anchor", then alignment occurs before rotation.

set_size(fontsize)[source]: Alias for set_fontsize.

set_stretch(stretch)[source]: Alias for set_fontstretch.

set_style(fontstyle)[source]: Alias for set_fontstyle.

set_text(s)[source]

Set the text string s.

It may contain newlines (\n) or math in LaTeX syntax.

Parameters

sobject: Any object gets converted to its str representation, except for None which is converted to an empty string.

set_transform_rotates_text(t)[source]

Whether rotations of the transform affect the text direction.

Parameters

tbool

set_usetex(usetex)[source]

Parameters

usetexbool or None: Whether to render using TeX, None means to use rcParams["text.usetex"] (default: False).

set_va(align)[source]: Alias for set_verticalalignment.

set_variant(variant)[source]: Alias for set_fontvariant.

set_verticalalignment(align)[source]

Set the vertical alignment.

Parameters

align{'center', 'top', 'bottom', 'baseline', 'center_baseline'}

set_weight(weight)[source]: Alias for set_fontweight.

set_wrap(wrap)[source]

Set whether the text can be wrapped.

Parameters

wrapbool

Notes

Wrapping does not work together with savefig(..., bbox_inches='tight') (which is also used internally by %matplotlib inline in IPython/Jupyter). The 'tight' setting rescales the canvas to accommodate all content and happens before wrapping.

set_x(x)[source]

Set the x position of the text.

Parameters

xfloat

set_y(y)[source]

Set the y position of the text.

Parameters

yfloat

update(kwargs)[source]

Update this artist's properties from the dict props.

Parameters

propsdict

update_bbox_position_size(renderer)[source]

Update the location and the size of the bbox.

This method should be used when the position and size of the bbox needs to be updated before actually drawing the bbox.

update_from(other)[source]: Copy properties from other to self.

zorder=3

matplotlib.text.get_rotation(rotation)[source]

Return rotation normalized to an angle between 0 and 360 degrees.

Parameters

rotationfloat or {None, 'horizontal', 'vertical'}: Rotation angle in degrees. None and 'horizontal' equal 0, 'vertical' equals 90.

Returns

float

Docs

Docs4dev

Title here

matplotlib.text

Notes

Notes

Notes

Examples

Notes

Notes