Classes for including text in a figure.
Bases: matplotlib.text.Text, matplotlib.text._AnnotationBase
A Text class to make annotating things in the figure, such as Figure, Axes, Rectangle, etc., easier.
Annotate the x, y point xy with text s at x, y location xytext. (If xytext = None, defaults to xy, and if textcoords = None, defaults to xycoords).
arrowprops, if not None, is a dictionary of line properties (see matplotlib.lines.Line2D) for the arrow that connects annotation to the point.
If the dictionary has a key arrowstyle, a FancyArrowPatch instance is created with the given dictionary and is drawn. Otherwise, a YAArrow patch instance is created and drawn. Valid keys for YAArrow are:
| Key | Description |
|---|---|
| width | the width of the arrow in points |
| frac | the fraction of the arrow length occupied by the head |
| headwidth | the width of the base of the arrow head in points |
| shrink | oftentimes it is convenient to have the arrowtip and base a bit away from the text and point being annotated. If d is the distance between the text and annotated point, shrink will shorten the arrow so the tip and base are shink percent of the distance d away from the endpoints. i.e., shrink=0.05 is 5% |
| ? | any key for matplotlib.patches.polygon |
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 |
xycoords and textcoords are strings that indicate the coordinates of xy and xytext, and may be one of the following values:
| Property | Description |
|---|---|
| ‘figure points’ | points from the lower left corner of the figure |
| ‘figure pixels’ | pixels from the lower left corner of the figure |
| ‘figure fraction’ | 0,0 is lower left of figure and 1,1 is upper right |
| ‘axes points’ | points from lower left corner of axes |
| ‘axes pixels’ | pixels from lower left corner of axes |
| ‘axes fraction’ | 0,0 is lower left of axes and 1,1 is upper right |
| ‘data’ | use the coordinate system of the object being annotated (default) |
| ‘offset points’ | Specify an offset (in points) from the xy value |
| ‘polar’ | you can specify theta, r for the annotation, even in cartesian plots. Note that if you are using a polar axes, you do not need to specify polar for the coordinate system since that is the native “data” coordinate system. |
If a ‘points’ or ‘pixels’ option is specified, values will be added to the bottom-left and if negative, values will be subtracted from the top-right. e.g.:
# 10 points to the right of the left border of the axes and
# 5 points below the top border
xy=(10,-5), xycoords='axes points'
You may use an instance of Transform or Artist. See Annotating Axes for more details.
The annotation_clip attribute 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”.
Additional kwargs are Text properties:
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 rectangle 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 fontfamily or fontname 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) lod [True | False] 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 va or ma [ ‘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’ ] x float y float zorder any number
Draw the Annotation object to the given renderer.
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 the pixel positions of the annotated point and the text.
Bases: object
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 rectangle 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 fontfamily or fontname 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) lod [True | False] 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 va or ma [ ‘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’ ] x float y float zorder any number
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.
Return the bbox Patch object. Returns None if the the FancyBboxPatch is not made.
Return the color of the text
Return the list of font families used for font lookup
alias for get_fontproperties
alias for get_family
alias for get_name
Return the FontProperties object
alias for get_size
alias for get_stretch
alias for get_style
alias for get_variant
alias for get_weight
alias for get_horizontalalignment
Return the horizontal alignment as string. Will be one of ‘left’, ‘center’ or ‘right’.
Return the font name as string
Return the position of the text as a tuple (x, y)
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.
return the text angle as float in degrees
get text rotation mode
Return the font size as integer
Get the font stretch as a string or number
Return the font style as string
Get the text as string
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']
alias for getverticalalignment()
Return the font variant as a string
Return the vertical alignment as string. Will be one of ‘top’, ‘center’, ‘bottom’ or ‘baseline’.
Get the font weight as string or number
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.
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.
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 the background color of the text by updating the bbox.
See also
ACCEPTS: any matplotlib color
Draw a bounding box around self. rectprops are any settable properties for a rectangle, e.g., facecolor=’red’, alpha=0.5.
t.set_bbox(dict(facecolor=’red’, alpha=0.5))
If rectprops has “boxstyle” key. A FancyBboxPatch is initialized with rectprops and will be drawn. The mutation scale of the FancyBboxPath is set to the fontsize.
ACCEPTS: rectangle prop dict
Set the foreground color of the text
ACCEPTS: any matplotlib color
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 matplotlibrc file.
alias for set_fontproperties
alias for set_family
Set the font properties that control the text. fp must be a matplotlib.font_manager.FontProperties object.
ACCEPTS: a matplotlib.font_manager.FontProperties instance
alias for set_size
alias for set_stretch
alias for set_style
alias for set_variant
alias for set_weight
alias for set_horizontalalignment
Set the horizontal alignment to one of
ACCEPTS: [ ‘center’ | ‘right’ | ‘left’ ]
Set the line spacing as a multiple of the font size. Default is 1.2.
ACCEPTS: float (multiple of font size)
alias for set_verticalalignment
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
ACCEPTS: [‘left’ | ‘right’ | ‘center’ ]
alias for set_family
Set the (x, y) position of the text
ACCEPTS: (x,y)
Set the rotation of the text
ACCEPTS: [ angle in degrees | ‘vertical’ | ‘horizontal’ ]
set text rotation mode. If “anchor”, the un-rotated text will first aligned according to their ha and va, and then will be rotated with the alignement reference point as a origin. If None (default), the text will be rotated first then will be aligned.
Set the font size. May be either a size string, relative to the default font size, or an absolute font size in points.
Set the font stretch (horizontal condensation or expansion).
Set the font style.
ACCEPTS: [ ‘normal’ | ‘italic’ | ‘oblique’]
Set the text string s
It may contain newlines (\n) or math in LaTeX syntax.
ACCEPTS: string or anything printable with ‘%s’ conversion.
Set this Text object to render using TeX (or not).
If None is given, the option will be reset to use the value of rcParams['text.usetex']
alias for set_verticalalignment
Set the font variant, either ‘normal’ or ‘small-caps’.
ACCEPTS: [ ‘normal’ | ‘small-caps’ ]
Set the vertical alignment
ACCEPTS: [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ]
Set the font weight.
Set the x position of the text
ACCEPTS: float
Set the y position of the text
ACCEPTS: float
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.
Copy properties from other to self
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 the TextWithDash object to the given renderer.
Get the direction dash. 1 is before the text and 0 is after.
Get the length of the dash.
Get the extra spacing between the dash and the text, in canvas units.
Get the extra spacing between the dash and the specified text position, in canvas units.
Get the rotation of the dash in degrees.
return the figure instance the artist belongs to
Return the position of the text as a tuple (x, y)
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.
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 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.
ACCEPTS: int (1 is before, 0 is after)
Set the length of the dash.
ACCEPTS: float (canvas units)
Set the “pad” of the TextWithDash, which is the extra spacing between the dash and the text, in canvas units.
ACCEPTS: float (canvas units)
Set the “push” of the TextWithDash, which is the extra spacing between the beginning of the dash and the specified position.
ACCEPTS: float (canvas units)
Set the rotation of the dash, in degrees
ACCEPTS: float (degrees)
Set the figure instance the artist belong to.
ACCEPTS: a matplotlib.figure.Figure instance
Set the (x, y) position of the TextWithDash.
ACCEPTS: (x, y)
Set the matplotlib.transforms.Transform instance used by this artist.
ACCEPTS: a matplotlib.transforms.Transform instance
Set the x position of the TextWithDash.
ACCEPTS: float
Set the y position of the TextWithDash.
ACCEPTS: float
Computes the actual x, y coordinates for text based on the input x, y and the dashlength. Since the rotation is with respect to the actual canvas’s coordinates we need to map back and forth.
Return the text angle as float. The returned angle is between 0 and 360 deg.
rotation may be ‘horizontal’, ‘vertical’, or a numeric value in degrees.