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)[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 s.
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: - s : str
The text of the annotation.
- xy : (float, float)
The point (x,y) to annotate.
- xytext : (float, float), optional
The position (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. 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 '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 An Artist: xy is interpreted as a fraction of the artists 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 Annotation for more details.
Defaults to 'data'.
- textcoords : str, Artist, Transform, callable or tuple, optional
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 Defaults to the value of xycoords, i.e. use the same coordinate system for annotation point and text position.
- arrowprops : dict, optional
The properties used to draw a FancyArrowPatch arrow between the positions 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 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, i.e. no arrow is drawn.
- annotation_clip : bool or None, optional
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'.
Defaults to None.
- **kwargs
Additional kwargs are passed to Text.
Returns: - annotation : Annotation
See also
- anncoords¶
The coordinate system to use for Annotation.xyann.
- arrow¶
Deprecated since version 3.0: arrow was deprecated in Matplotlib 3.0 and will be removed in 3.2. Use arrow_patch instead.
- contains(event)[source]¶
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: - bool : bool
- draw(renderer)[source]¶
Draw the Annotation object to the given renderer.
- get_anncoords()¶
Return the coordinate system to use for Annotation.xyann.
See also xycoords in Annotation.
- get_window_extent(renderer=None)[source]¶
Return the Bbox bounding the text and arrow, in display units.
Parameters: - renderer : Renderer, 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).
- set_anncoords(coords)¶
Set the coordinate system to use for Annotation.xyann.
See also xycoords in Annotation.
- xyann¶
The the text position.
See also xytext in Annotation.
- class matplotlib.text.OffsetFrom(artist, ref_coord, unit='points')[source]¶
Bases: object
Callable helper class for working with Annotation
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.
- 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)[source]¶
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 a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha float animated bool backgroundcolor color bbox dict with properties for patches.FancyBboxPatch clip_box matplotlib.transforms.Bbox clip_on bool clip_path { (path.Path, transforms.Transform), patches.Patch, None } color color contains callable figure Figure fontfamily {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontname {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontproperties font_manager.FontProperties fontsize {size in points, '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) multialignment {'left', 'right', 'center'} path_effects AbstractPathEffect picker None or bool or float or callable position (float, float) rasterized bool or None rotation {angle in degrees, 'vertical', 'horizontal'} rotation_mode {None, 'default', 'anchor'} sketch_params (scale: float, length: float, randomness: float) snap bool or None text string or object castable to string (but None becomes '') transform Transform url str usetex bool or None verticalalignment {'center', 'top', 'bottom', 'baseline', 'center_baseline'} visible bool wrap bool x float y float zorder float - contains(mouseevent)[source]¶
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: - bool : bool
- get_bbox_patch()[source]¶
Return the bbox Patch, or None if the patches.FancyBboxPatch is not made.
- get_family(*args, **kwargs)¶
alias for get_fontfamily
- get_font_properties(*args, **kwargs)¶
alias for get_fontproperties
- get_fontproperties()[source]¶
Return the font_manager.FontProperties object
- get_ha(*args, **kwargs)¶
alias for get_horizontalalignment
- get_horizontalalignment()[source]¶
Return the horizontal alignment as string. Will be one of 'left', 'center' or 'right'.
- get_name(*args, **kwargs)¶
alias for get_fontname
- get_prop_tup(renderer=None)[source]¶
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_size(*args, **kwargs)¶
alias for get_fontsize
- get_style(*args, **kwargs)¶
alias for get_fontstyle
- get_usetex()[source]¶
Return whether this Text object uses TeX for rendering.
If the user has not manually set this value, it defaults to rcParams["text.usetex"].
- get_va(*args, **kwargs)¶
alias for get_verticalalignment
- get_variant(*args, **kwargs)¶
alias for get_fontvariant
- get_verticalalignment()[source]¶
Return the vertical alignment as string. Will be one of 'top', 'center', 'bottom' or 'baseline'.
- get_weight(*args, **kwargs)¶
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: - renderer : Renderer, 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).
- dpi : float, 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.
- static is_math_text(s, usetex=None)[source]¶
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)[source]¶
Set the background color of the text by updating the bbox.
Parameters: - color : color
See also
- set_bbox
- To change the position of the bounding box
- set_bbox(rectprops)[source]¶
Draw a bounding box around self.
Parameters: - rectprops : dict 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_clip_box(clipbox)[source]¶
Set the artist's clip Bbox.
Parameters: - clipbox : matplotlib.transforms.Bbox
- set_clip_on(b)[source]¶
Set whether artist uses clipping.
When False, artists will be visible outside of the axes, which can lead to unexpected results.
Parameters: - b : bool
- set_clip_path(path, transform=None)[source]¶
Set the artist's clip path, which may be:
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: { (path.Path, transforms.Transform),
- patches.Patch, None }
- set_family(*args, **kwargs)¶
alias for set_fontfamily
- set_font_properties(*args, **kwargs)¶
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.
Parameters: - fontname : {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
- set_fontname(fontname)[source]¶
alias for set_family
One-way alias only: the getter differs.
Parameters: - fontname : {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
- set_fontsize(fontsize)[source]¶
Set the font size. May be either a size string, relative to the default font size, or an absolute font size in points.
Parameters: - fontsize : {size in points, 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
See also
- 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'}
- set_fontstyle(fontstyle)[source]¶
Set the font style.
Parameters: - fontstyle : {'normal', 'italic', 'oblique'}
- set_fontvariant(variant)[source]¶
Set the font variant, either 'normal' or 'small-caps'.
Parameters: - variant : {'normal', 'small-caps'}
- 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'}
- set_ha(*args, **kwargs)¶
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. Default is 1.2.
Parameters: - spacing : float (multiple of font size)
- set_ma(*args, **kwargs)¶
alias for set_multialignment
- set_multialignment(align)[source]¶
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
Parameters: - align : {'left', 'right', 'center'}
- set_name(*args, **kwargs)¶
alias for set_fontname
- set_rotation(s)[source]¶
Set the rotation of the text.
Parameters: - s : {angle in degrees, 'vertical', 'horizontal'}
- 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(*args, **kwargs)¶
alias for set_fontsize
- set_stretch(*args, **kwargs)¶
alias for set_fontstretch
- set_style(*args, **kwargs)¶
alias for set_fontstyle
- set_text(s)[source]¶
Set the text string s.
It may contain newlines (\n) or math in LaTeX syntax.
Parameters: - s : string or object castable to string (but None becomes '')
- set_usetex(usetex)[source]¶
Parameters: - usetex : bool or None
Whether to render using TeX, None means to use rcParams["text.usetex"].
- set_va(*args, **kwargs)¶
alias for set_verticalalignment
- set_variant(*args, **kwargs)¶
alias for set_fontvariant
- set_verticalalignment(align)[source]¶
Set the vertical alignment
Parameters: - align : {'center', 'top', 'bottom', 'baseline', 'center_baseline'}
- set_weight(*args, **kwargs)¶
alias for set_fontweight
- 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.
- zorder = 3¶
- 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)[source]¶
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
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)[source]¶
Draw the TextWithDash object to the given renderer.
- get_dashpush()[source]¶
Get the extra spacing between the dash and the specified text position, in canvas units.
- get_prop_tup(renderer=None)[source]¶
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_window_extent(renderer=None)[source]¶
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.
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.
- set_dashdirection(dd)[source]¶
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.
Parameters: - dd : int (1 is before, 0 is after)
- set_dashpad(dp)[source]¶
Set the "pad" of the TextWithDash, which is the extra spacing between the dash and the text, in canvas units.
Parameters: - dp : float
- set_dashpush(dp)[source]¶
Set the "push" of the TextWithDash, which is the extra spacing between the beginning of the dash and the specified position.
Parameters: - dp : float
- set_figure(fig)[source]¶
Set the figure instance the artist belongs to.
Parameters: - fig : matplotlib.figure.Figure
- set_position(xy)[source]¶
Set the (x, y) position of the TextWithDash.
Parameters: - xy : (float, float)
- set_transform(t)[source]¶
Set the matplotlib.transforms.Transform instance used by this artist.
Parameters: - t : matplotlib.transforms.Transform
- set_x(x)[source]¶
Set the x position of the TextWithDash.
Parameters: - x : float
- set_y(y)[source]¶
Set the y position of the TextWithDash.
Parameters: - y : float