text

matplotlib.text

Classes for including text in a figure.

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

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

Annotate the point xy with text s.

Additional kwargs are passed to Text.

Parameters:

s : str

The text of the annotation

xy : iterable

Length 2 sequence specifying the (x,y) point to annotate

xytext : iterable, optional

Length 2 sequence specifying the (x,y) to place the text at. If None, defaults to xy.

xycoords : str, Artist, Transform, callable or tuple, optional

The coordinate system that xy is given in.

For a str the allowed values are:

Property	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
‘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

If a Artist object is passed in the units are fraction if it’s bounding box.

If a Transform object is passed in use that to transform xy to screen coordinates

If a callable it must take a RendererBase object as input and return a Transform or Bbox object

If a tuple must be length 2 tuple of str, Artist, Transform or callable objects. The first transform is used for the x coordinate and the second for y.

See Annotating Axes for more details.

Defaults to 'data'

textcoords : str, Artist, Transform, callable or tuple, optional

The coordinate system that xytext is given, which may be different than the coordinate system used for xy.

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

Property	Description
‘offset points’	offset (in points) from the xy value
‘offset pixels’	offset (in pixels) from the xy value

defaults to the input of xycoords

arrowprops : dict, optional

If not None, properties used to draw a FancyArrowPatch arrow between xy and xytext.

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`

If the arrowprops contains the key 'arrowstyle' the above keys are forbidden. The allowed values of 'arrowstyle' are:

Name	Attrs
`'-'`	None
`'->'`	head_length=0.4,head_width=0.2
`'-['`	widthB=1.0,lengthB=0.2,angleB=None
`'\|-\|'`	widthA=1.0,widthB=1.0
`'-\|>'`	head_length=0.4,head_width=0.2
`'<-'`	head_length=0.4,head_width=0.2
`'<->'`	head_length=0.4,head_width=0.2
`'<\|-'`	head_length=0.4,head_width=0.2
`'<\|-\|>'`	head_length=0.4,head_width=0.2
`'fancy'`	head_length=0.4,head_width=0.4,tail_width=0.4
`'simple'`	head_length=0.5,head_width=0.5,tail_width=0.2
`'wedge'`	tail_width=0.3,shrink_factor=0.5

Valid keys for FancyArrowPatch are:

Key	Description
arrowstyle	the arrow style
connectionstyle	the connection style
relpos	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`

Defaults to None

annotation_clip : bool, optional

Controls the visibility of the annotation when it goes outside the axes area.

If True, the annotation will only be drawn when the xy is inside the axes. If False, the annotation will always be drawn regardless of its position.

The default is None, which behave as True only if xycoords is “data”.

Returns:

Annotation

anncoords

contains(event)

draw(artist, renderer, *args, **kwargs): Draw the Annotation object to the given renderer.

get_window_extent(renderer=None)

Return a Bbox object bounding the text and arrow annotation, in display units.

renderer defaults to the _renderer attribute of the text object. This is not assigned until the first execution of draw(), so you must use this kwarg if you want to call get_window_extent() prior to the first draw(). For getting web page regions, it is simpler to call the method after saving the figure. The dpi used defaults to self.figure.dpi; the renderer dpi is irrelevant.

set_figure(fig)

update_positions(renderer): “Update the pixel positions of the annotated point and the text.

xyann

class matplotlib.text.OffsetFrom(artist, ref_coord, unit='points')

Bases: object

Callable helper class for working with Annotation

Parameters:

Parameters:	artist : `Artist`, `BboxBase`, or `Transform` The object to compute the offset from. ref_coord : length 2 sequence If `artist` is an `Artist` or `BboxBase`, this values is the location to of the offset origin in fractions of the `artist` bounding box. If `artist` is a transform, the offset origin is the transform applied to this value. unit : {‘points, ‘pixels’} The screen units to use (pixels or points) for the offset input.

artist : Artist, BboxBase, or Transform

The object to compute the offset from.

ref_coord : length 2 sequence

If artist is an Artist or BboxBase, this values is the location to of the offset origin in fractions of the artist bounding box.

If artist is a transform, the offset origin is the transform applied to this value.

unit : {‘points, ‘pixels’}

The screen units to use (pixels or points) for the offset input.

get_unit(): The unit for input to the transform used by __call__

set_unit(unit)

The unit for input to the transform used by __call__

Parameters:	unit : {‘points’, ‘pixels’}

class matplotlib.text.Text(x=0, y=0, text='', color=None, verticalalignment='baseline', horizontalalignment='left', multialignment=None, fontproperties=None, rotation=None, linespacing=None, rotation_mode=None, usetex=None, wrap=False, **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

Property	Description
`agg_filter`	unknown
`alpha`	float (0.0 transparent through 1.0 opaque)
`animated`	[True \| False]
`axes`	an `Axes` instance
`backgroundcolor`	any matplotlib color
`bbox`	FancyBboxPatch prop dict
`clip_box`	a `matplotlib.transforms.Bbox` instance
`clip_on`	[True \| False]
`clip_path`	[ (`Path`, `Transform`) \| `Patch` \| None ]
`color`	any matplotlib color
`contains`	a callable function
`family` or fontname or fontfamily or name	[FONTNAME \| ‘serif’ \| ‘sans-serif’ \| ‘cursive’ \| ‘fantasy’ \| ‘monospace’ ]
`figure`	a `matplotlib.figure.Figure` instance
`fontproperties` or font_properties	a `matplotlib.font_manager.FontProperties` instance
`gid`	an id string
`horizontalalignment` or ha	[ ‘center’ \| ‘right’ \| ‘left’ ]
`label`	string or anything printable with ‘%s’ conversion.
`linespacing`	float (multiple of font size)
`multialignment`	[‘left’ \| ‘right’ \| ‘center’ ]
`path_effects`	unknown
`picker`	[None\|float\|boolean\|callable]
`position`	(x,y)
`rasterized`	[True \| False \| None]
`rotation`	[ angle in degrees \| ‘vertical’ \| ‘horizontal’ ]
`rotation_mode`	unknown
`size` or fontsize	[size in points \| ‘xx-small’ \| ‘x-small’ \| ‘small’ \| ‘medium’ \| ‘large’ \| ‘x-large’ \| ‘xx-large’ ]
`sketch_params`	unknown
`snap`	unknown
`stretch` or fontstretch	[a numeric value in range 0-1000 \| ‘ultra-condensed’ \| ‘extra-condensed’ \| ‘condensed’ \| ‘semi-condensed’ \| ‘normal’ \| ‘semi-expanded’ \| ‘expanded’ \| ‘extra-expanded’ \| ‘ultra-expanded’ ]
`style` or fontstyle	[ ‘normal’ \| ‘italic’ \| ‘oblique’]
`text`	string or anything printable with ‘%s’ conversion.
`transform`	`Transform` instance
`url`	a url string
`usetex`	unknown
`variant` or fontvariant	[ ‘normal’ \| ‘small-caps’ ]
`verticalalignment` or ma or va	[ ‘center’ \| ‘top’ \| ‘bottom’ \| ‘baseline’ ]
`visible`	[True \| False]
`weight` or fontweight	[a numeric value in range 0-1000 \| ‘ultralight’ \| ‘light’ \| ‘normal’ \| ‘regular’ \| ‘book’ \| ‘medium’ \| ‘roman’ \| ‘semibold’ \| ‘demibold’ \| ‘demi’ \| ‘bold’ \| ‘heavy’ \| ‘extra bold’ \| ‘black’ ]
`wrap`	unknown
`x`	float
`y`	float
`zorder`	any number

contains(mouseevent)

Test whether the mouse event occurred in the patch.

In the case of text, a hit is true anywhere in the axis-aligned bounding-box containing the text.

Returns True or False.

draw(artist, renderer, *args, **kwargs): Draws the Text object to the given renderer.

get_bbox_patch(): Return the bbox Patch object. Returns None if the FancyBboxPatch is not made.

get_color(): Return the color of the text

get_family(): Return the list of font families used for font lookup

get_font_properties(): alias for get_fontproperties

get_fontfamily(): alias for get_family

get_fontname(): alias for get_name

get_fontproperties(): Return the FontProperties object

get_fontsize(): alias for get_size

get_fontstretch(): alias for get_stretch

get_fontstyle(): alias for get_style

get_fontvariant(): alias for get_variant

get_fontweight(): alias for get_weight

get_ha(): alias for get_horizontalalignment

get_horizontalalignment(): Return the horizontal alignment as string. Will be one of ‘left’, ‘center’ or ‘right’.

get_name(): Return the font name as string

get_position(): Return the position of the text as a tuple (x, y)

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 (e.g., layouts) and need to know if the text has changed.

get_rotation(): return the text angle as float in degrees

get_rotation_mode(): get text rotation mode

get_size(): Return the font size as integer

get_stretch(): Get the font stretch as a string or number

get_style(): Return the font style as string

get_text(): Get the text as string

get_unitless_position(): Return the unitless position of the text as a tuple (x, y)

get_usetex()

Return whether this Text object will render using TeX.

If the user has not manually set this value, it will default to the value of rcParams['text.usetex']

get_va(): alias for getverticalalignment()

get_variant(): Return the font variant as a string

get_verticalalignment(): Return the vertical alignment as string. Will be one of ‘top’, ‘center’, ‘bottom’ or ‘baseline’.

get_weight(): Get the font weight as string or number

get_window_extent(renderer=None, dpi=None)

Return a Bbox object 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.

dpi defaults to self.figure.dpi; the renderer dpi is irrelevant. For the web application, if figure.dpi is not the value used when saving the figure, then the value that was used must be specified as the dpi argument.

get_wrap(): Returns the wrapping state for the text.

static is_math_text(s): Returns a cleaned string and a boolean flag. The flag indicates if the given string s contains any mathtext, determined by counting unescaped dollar signs. If no mathtext is present, the cleaned string has its dollar signs unescaped. If usetex is on, the flag always has the value “TeX”.

set_backgroundcolor(color)

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