r"""

.. redirect-from:: /gallery/userdemo/anchored_box04

.. redirect-from:: /gallery/userdemo/annotate_explain

.. redirect-from:: /gallery/userdemo/annotate_simple01

.. redirect-from:: /gallery/userdemo/annotate_simple02

.. redirect-from:: /gallery/userdemo/annotate_simple03

.. redirect-from:: /gallery/userdemo/annotate_simple04

.. redirect-from:: /gallery/userdemo/annotate_simple_coord01

.. redirect-from:: /gallery/userdemo/annotate_simple_coord02

.. redirect-from:: /gallery/userdemo/annotate_simple_coord03

.. redirect-from:: /gallery/userdemo/annotate_text_arrow

.. redirect-from:: /gallery/userdemo/connect_simple01

.. redirect-from:: /gallery/userdemo/connectionstyle_demo

.. redirect-from:: /tutorials/text/annotations

.. redirect-from:: /gallery/text_labels_and_annotations/annotate_transform

.. _annotations:

Annotations

===========

Annotations are graphical elements, often pieces of text, that explain, add

context to, or otherwise highlight some portion of the visualized data.

`~.Axes.annotate` supports a number of coordinate systems for flexibly

positioning data and annotations relative to each other and a variety of

options of for styling the text. Axes.annotate also provides an optional arrow

from the text to the data and this arrow can be styled in various ways.

`~.Axes.text` can also be used for simple text annotation, but does not

provide as much flexibility in positioning and styling as `~.Axes.annotate`.

.. contents:: Table of Contents

:depth: 3

"""

# %%

# .. _annotations-tutorial:

#

# Basic annotation

# ----------------

#

# In an annotation, there are two points to consider: the location of the data

# being annotated *xy* and the location of the annotation text *xytext*. Both

# of these arguments are ``(x, y)`` tuples:

import matplotlib.pyplot as plt

import numpy as np

fig, ax = plt.subplots(figsize=(3, 3))

t = np.arange(0.0, 5.0, 0.01)

s = np.cos(2*np.pi*t)

line, = ax.plot(t, s, lw=2)

ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5),

arrowprops=dict(facecolor='black', shrink=0.05))

ax.set_ylim(-2, 2)

# %%

# In this example, both the *xy* (arrow tip) and *xytext* locations

# (text location) are in data coordinates. There are a variety of other

# coordinate systems one can choose -- you can specify the coordinate

# system of *xy* and *xytext* with one of the following strings for

# *xycoords* and *textcoords* (default is 'data')

#

# ================== ========================================================

# argument coordinate system

# ================== ========================================================

# '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 the Axes

# 'axes pixels' pixels from lower left corner of the Axes

# 'axes fraction' (0, 0) is lower left of Axes and (1, 1) is upper right

# 'data' use the axes data coordinate system

# ================== ========================================================

#

# The following strings are also valid arguments for *textcoords*

#

# ================== ========================================================

# argument coordinate system

# ================== ========================================================

# 'offset points' offset (in points) from the xy value

# 'offset pixels' offset (in pixels) from the xy value

# ================== ========================================================

#

# For physical coordinate systems (points or pixels) the origin is the

# bottom-left of the figure or Axes. Points are

# `typographic points <https://en.wikipedia.org/wiki/Point_(typography)>`_

# meaning that they are a physical unit measuring 1/72 of an inch. Points and

# pixels are discussed in further detail in :ref:`transforms-fig-scale-dpi`.

#

# .. _annotation-data:

#

# Annotating data

# ^^^^^^^^^^^^^^^

#

# This example places the text coordinates in fractional axes coordinates:

fig, ax = plt.subplots(figsize=(3, 3))

t = np.arange(0.0, 5.0, 0.01)

s = np.cos(2*np.pi*t)

line, = ax.plot(t, s, lw=2)

ax.annotate('local max', xy=(2, 1), xycoords='data',

xytext=(0.01, .99), textcoords='axes fraction',

va='top', ha='left',

arrowprops=dict(facecolor='black', shrink=0.05))

ax.set_ylim(-2, 2)

# %%

#

# Annotating an Artist

# ^^^^^^^^^^^^^^^^^^^^

#

# Annotations can be positioned relative to an `.Artist` instance by passing

# that Artist in as *xycoords*. Then *xy* is interpreted as a fraction of the

# Artist's bounding box.

import matplotlib.patches as mpatches

fig, ax = plt.subplots(figsize=(3, 3))

arr = mpatches.FancyArrowPatch((1.25, 1.5), (1.75, 1.5),

arrowstyle='->,head_width=.15', mutation_scale=20)

ax.add_patch(arr)

ax.annotate("label", (.5, .5), xycoords=arr, ha='center', va='bottom')

ax.set(xlim=(1, 2), ylim=(1, 2))

# %%

# Here the annotation is placed at position (.5,.5) relative to the arrow's

# lower left corner and is vertically and horizontally at that position.

# Vertically, the bottom aligns to that reference point so that the label

# is above the line. For an example of chaining annotation Artists, see the

# :ref:`Artist section <artist_annotation_coord>` of

# :ref:`annotating_coordinate_systems`.

#

#

# .. _annotation-with-arrow:

#

# Annotating with arrows

# ^^^^^^^^^^^^^^^^^^^^^^

#

# You can enable drawing of an arrow from the text to the annotated point

# by giving a dictionary of arrow properties in the optional keyword

# argument *arrowprops*.

#

# ==================== =====================================================

# *arrowprops* 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 move the tip and base some percent away from

# the annotated point and text

#

# \*\*kwargs any key for :class:`matplotlib.patches.Polygon`,

# e.g., ``facecolor``

# ==================== =====================================================

#

# In the example below, the *xy* point is in the data coordinate system

# since *xycoords* defaults to 'data'. For a polar Axes, this is in

# (theta, radius) space. The text in this example is placed in the

# fractional figure coordinate system. :class:`matplotlib.text.Text`

# keyword arguments like *horizontalalignment*, *verticalalignment* and

# *fontsize* are passed from `~matplotlib.axes.Axes.annotate` to the

# ``Text`` instance.

fig = plt.figure()

ax = fig.add_subplot(projection='polar')

r = np.arange(0, 1, 0.001)

theta = 2 * 2*np.pi * r

line, = ax.plot(theta, r, color='#ee8d18', lw=3)

ind = 800

thisr, thistheta = r[ind], theta[ind]

ax.plot([thistheta], [thisr], 'o')

ax.annotate('a polar annotation',

xy=(thistheta, thisr), # theta, radius

xytext=(0.05, 0.05), # fraction, fraction

textcoords='figure fraction',

arrowprops=dict(facecolor='black', shrink=0.05),

horizontalalignment='left',

verticalalignment='bottom')

# %%

# For more on plotting with arrows, see :ref:`annotation_with_custom_arrow`

#

# .. _annotations-offset-text:

#

# Placing text annotations relative to data

# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# Annotations can be positioned at a relative offset to the *xy* input to

# annotation by setting the *textcoords* keyword argument to ``'offset points'``

# or ``'offset pixels'``.

fig, ax = plt.subplots(figsize=(3, 3))

x = [1, 3, 5, 7, 9]

y = [2, 4, 6, 8, 10]

annotations = ["A", "B", "C", "D", "E"]

ax.scatter(x, y, s=20)

for xi, yi, text in zip(x, y, annotations):

ax.annotate(text,

xy=(xi, yi), xycoords='data',

xytext=(1.5, 1.5), textcoords='offset points')

# %%

# The annotations are offset 1.5 points (1.5*1/72 inches) from the *xy* values.

#

# .. _plotting-guide-annotation:

#

# Advanced annotation

# -------------------

#

# We recommend reading :ref:`annotations-tutorial`, :func:`~matplotlib.pyplot.text`

# and :func:`~matplotlib.pyplot.annotate` before reading this section.

#

# Annotating with boxed text

# ^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# `~.Axes.text` takes a *bbox* keyword argument, which draws a box around the

# text:

fig, ax = plt.subplots(figsize=(5, 5))

t = ax.text(0.5, 0.5, "Direction",

ha="center", va="center", rotation=45, size=15,

bbox=dict(boxstyle="rarrow,pad=0.3",

fc="lightblue", ec="steelblue", lw=2))

# %%

# The arguments are the name of the box style with its attributes as

# keyword arguments. Currently, following box styles are implemented:

#

# ========== ============== ====================================

# Class Name Attrs

# ========== ============== ====================================

# Circle ``circle`` pad=0.3

# DArrow ``darrow`` pad=0.3,head_width=1.5,head_angle=90

# Ellipse ``ellipse`` pad=0.3

# LArrow ``larrow`` pad=0.3,head_width=1.5,head_angle=90

# RArrow ``rarrow`` pad=0.3,head_width=1.5,head_angle=90

# Round ``round`` pad=0.3,rounding_size=None

# Round4 ``round4`` pad=0.3,rounding_size=None

# Roundtooth ``roundtooth`` pad=0.3,tooth_size=None

# Sawtooth ``sawtooth`` pad=0.3,tooth_size=None

# Square ``square`` pad=0.3

# ========== ============== ====================================

#

# .. figure:: /gallery/shapes_and_collections/images/sphx_glr_fancybox_demo_001.png

# :target: /gallery/shapes_and_collections/fancybox_demo.html

# :align: center

#

# The patch object (box) associated with the text can be accessed using::

#

# bb = t.get_bbox_patch()

#

# The return value is a `.FancyBboxPatch`; patch properties

# (facecolor, edgewidth, etc.) can be accessed and modified as usual.

# `.FancyBboxPatch.set_boxstyle` sets the box shape::

#

# bb.set_boxstyle("rarrow", pad=0.6)

#

# The attribute arguments can also be specified within the style

# name with separating comma::

#

# bb.set_boxstyle("rarrow, pad=0.6")

#

#

# Defining custom box styles

# ^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# Custom box styles can be implemented as a function that takes arguments specifying

# both a rectangular box and the amount of "mutation", and returns the "mutated" path.

# The specific signature is the one of ``custom_box_style`` below.

#

# Here, we return a new path which adds an "arrow" shape on the left of the box.

#

# The custom box style can then be used by passing

# ``bbox=dict(boxstyle=custom_box_style, ...)`` to `.Axes.text`.

from matplotlib.path import Path

def custom_box_style(x0, y0, width, height, mutation_size):

"""

Given the location and size of the box, return the path of the box around it.

Rotation is automatically taken care of.

Parameters

----------

x0, y0, width, height : float

Box location and size.

mutation_size : float

Mutation reference scale, typically the text font size.

"""

# padding

mypad = 0.3

pad = mutation_size * mypad

# width and height with padding added.

width = width + 2 * pad

height = height + 2 * pad

# boundary of the padded box

x0, y0 = x0 - pad, y0 - pad

x1, y1 = x0 + width, y0 + height

# return the new path

return Path([(x0, y0), (x1, y0), (x1, y1), (x0, y1),

(x0-pad, (y0+y1)/2), (x0, y0), (x0, y0)],

closed=True)

fig, ax = plt.subplots(figsize=(3, 3))

ax.text(0.5, 0.5, "Test", size=30, va="center", ha="center", rotation=30,

bbox=dict(boxstyle=custom_box_style, alpha=0.2))

# %%

# Likewise, custom box styles can be implemented as classes that implement

# ``__call__``.

#

# The classes can then be registered into the ``BoxStyle._style_list`` dict,

# which allows specifying the box style as a string,

# ``bbox=dict(boxstyle="registered_name,param=value,...", ...)``.

# Note that this registration relies on internal APIs and is therefore not

# officially supported.

from matplotlib.patches import BoxStyle

class MyStyle:

"""A simple box."""

def __init__(self, pad=0.3):

"""

The arguments must be floats and have default values.

Parameters

----------

pad : float

amount of padding

"""

self.pad = pad

super().__init__()

def __call__(self, x0, y0, width, height, mutation_size):

"""

Given the location and size of the box, return the path of the box around it.

Rotation is automatically taken care of.

Parameters

----------

x0, y0, width, height : float

Box location and size.

mutation_size : float

Reference scale for the mutation, typically the text font size.

"""

# padding

pad = mutation_size * self.pad

# width and height with padding added

width = width + 2 * pad

height = height + 2 * pad

# boundary of the padded box

x0, y0 = x0 - pad, y0 - pad

x1, y1 = x0 + width, y0 + height

# return the new path

return Path([(x0, y0), (x1, y0), (x1, y1), (x0, y1),

(x0-pad, (y0+y1)/2), (x0, y0), (x0, y0)],

closed=True)

BoxStyle._style_list["angled"] = MyStyle # Register the custom style.

fig, ax = plt.subplots(figsize=(3, 3))

ax.text(0.5, 0.5, "Test", size=30, va="center", ha="center", rotation=30,

bbox=dict(boxstyle="angled,pad=0.5", alpha=0.2))

del BoxStyle._style_list["angled"] # Unregister it.

# %%

# Similarly, you can define a custom `.ConnectionStyle` and a custom `.ArrowStyle`. View

# the source code at `.patches` to learn how each class is defined.

#

# .. _annotation_with_custom_arrow:

#

# Customizing annotation arrows

# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# An arrow connecting *xy* to *xytext* can be optionally drawn by

# specifying the *arrowprops* argument. To draw only an arrow, use

# empty string as the first argument:

fig, ax = plt.subplots(figsize=(3, 3))

ax.annotate("",

xy=(0.2, 0.2), xycoords='data',

xytext=(0.8, 0.8), textcoords='data',

arrowprops=dict(arrowstyle="->", connectionstyle="arc3"))

# %%

# The arrow is drawn as follows:

#

# 1. A path connecting the two points is created, as specified by the

# *connectionstyle* parameter.

# 2. The path is clipped to avoid patches *patchA* and *patchB*, if these are

# set.

# 3. The path is further shrunk by *shrinkA* and *shrinkB* (in pixels).

# 4. The path is transmuted to an arrow patch, as specified by the *arrowstyle*

# parameter.

#

# .. plot::

# :show-source-link: False

#

# import matplotlib.patches as mpatches

#

# x1, y1 = 0.3, 0.3

# x2, y2 = 0.7, 0.7

# arrowprops = {

# "1. connect with connectionstyle":

# dict(arrowstyle="-", patchB=False, shrinkB=0),

# "2. clip against patchB": dict(arrowstyle="-", patchB=True, shrinkB=0),

# "3. shrink by shrinkB": dict(arrowstyle="-", patchB=True, shrinkB=5),

# "4. mutate with arrowstyle": dict(arrowstyle="fancy", patchB=True, shrinkB=5),

# }

#

# fig, axs = plt.subplots(2, 2, figsize=(6, 6), layout='compressed')

# for ax, (name, props) in zip(axs.flat, arrowprops.items()):

# ax.plot([x1, x2], [y1, y2], ".")

#

# el = mpatches.Ellipse((x1, y1), 0.3, 0.4, angle=30, alpha=0.2)

# ax.add_artist(el)

#

# props["patchB"] = el if props["patchB"] else None

#

# ax.annotate(

# "",

# xy=(x1, y1), xycoords='data',

# xytext=(x2, y2), textcoords='data',

# arrowprops={"color": "0.5", "connectionstyle": "arc3,rad=0.3", **props})

# ax.text(.05, .95, name, transform=ax.transAxes, ha="left", va="top")

#

# ax.set(xlim=(0, 1), ylim=(0, 1), xticks=[], yticks=[], aspect=1)

#

# fig.get_layout_engine().set(wspace=0, hspace=0, w_pad=0, h_pad=0)

#

# The creation of the connecting path between two points is controlled by

# ``connectionstyle`` key and the following styles are available:

#

# ========== =============================================

# Name Attrs

# ========== =============================================

# ``angle`` angleA=90,angleB=0,rad=0.0

# ``angle3`` angleA=90,angleB=0

# ``arc`` angleA=0,angleB=0,armA=None,armB=None,rad=0.0

# ``arc3`` rad=0.0

# ``bar`` armA=0.0,armB=0.0,fraction=0.3,angle=None

# ========== =============================================

#

# Note that "3" in ``angle3`` and ``arc3`` is meant to indicate that the

# resulting path is a quadratic spline segment (three control

# points). As will be discussed below, some arrow style options can only

# be used when the connecting path is a quadratic spline.

#

# The behavior of each connection style is (limitedly) demonstrated in the

# example below. (Warning: The behavior of the ``bar`` style is currently not

# well-defined and may be changed in the future).

#

# .. plot::

# :caption: Connection styles for annotations

#

# def demo_con_style(ax, connectionstyle):

# x1, y1 = 0.3, 0.2

# x2, y2 = 0.8, 0.6

#

# ax.plot([x1, x2], [y1, y2], ".")

# ax.annotate("",

# xy=(x1, y1), xycoords='data',

# xytext=(x2, y2), textcoords='data',

# arrowprops=dict(arrowstyle="->", color="0.5",

# shrinkA=5, shrinkB=5,

# patchA=None, patchB=None,

# connectionstyle=connectionstyle,

# ),

# )

#

# ax.text(.05, .95, connectionstyle.replace(",", ",\n"),

# transform=ax.transAxes, ha="left", va="top")

#

# ax.set(xlim=(0, 1), ylim=(0, 1.25), xticks=[], yticks=[], aspect=1.25)

#

# fig, axs = plt.subplots(3, 5, figsize=(7, 6.3), layout="compressed")

# demo_con_style(axs[0, 0], "angle3,angleA=90,angleB=0")

# demo_con_style(axs[1, 0], "angle3,angleA=0,angleB=90")

# demo_con_style(axs[0, 1], "arc3,rad=0.")

# demo_con_style(axs[1, 1], "arc3,rad=0.3")

# demo_con_style(axs[2, 1], "arc3,rad=-0.3")

# demo_con_style(axs[0, 2], "angle,angleA=-90,angleB=180,rad=0")

# demo_con_style(axs[1, 2], "angle,angleA=-90,angleB=180,rad=5")

# demo_con_style(axs[2, 2], "angle,angleA=-90,angleB=10,rad=5")

# demo_con_style(axs[0, 3], "arc,angleA=-90,angleB=0,armA=30,armB=30,rad=0")

# demo_con_style(axs[1, 3], "arc,angleA=-90,angleB=0,armA=30,armB=30,rad=5")

# demo_con_style(axs[2, 3], "arc,angleA=-90,angleB=0,armA=0,armB=40,rad=0")

# demo_con_style(axs[0, 4], "bar,fraction=0.3")

# demo_con_style(axs[1, 4], "bar,fraction=-0.3")

# demo_con_style(axs[2, 4], "bar,angle=180,fraction=-0.2")

#

# axs[2, 0].remove()

# fig.get_layout_engine().set(wspace=0, hspace=0, w_pad=0, h_pad=0)

#

# The connecting path (after clipping and shrinking) is then mutated to

# an arrow patch, according to the given ``arrowstyle``:

#

# ========== =============================================

# 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

# ========== =============================================

#

# .. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_fancyarrow_demo_001.png

# :target: /gallery/text_labels_and_annotations/fancyarrow_demo.html

# :align: center

#

# Some arrowstyles only work with connection styles that generate a

# quadratic-spline segment. They are ``fancy``, ``simple``, and ``wedge``.

# For these arrow styles, you must use the "angle3" or "arc3" connection

# style.

#

# If the annotation string is given, the patch is set to the bbox patch

# of the text by default.

fig, ax = plt.subplots(figsize=(3, 3))

ax.annotate("Test",

xy=(0.2, 0.2), xycoords='data',

xytext=(0.8, 0.8), textcoords='data',

size=20, va="center", ha="center",

arrowprops=dict(arrowstyle="simple",

connectionstyle="arc3,rad=-0.2"))

# %%

# As with `~.Axes.text`, a box around the text can be drawn using the *bbox*

# argument.

fig, ax = plt.subplots(figsize=(3, 3))

ann = ax.annotate("Test",

xy=(0.2, 0.2), xycoords='data',

xytext=(0.8, 0.8), textcoords='data',

size=20, va="center", ha="center",

bbox=dict(boxstyle="round4", fc="w"),

arrowprops=dict(arrowstyle="-|>",

connectionstyle="arc3,rad=-0.2",

fc="w"))

# %%

# By default, the starting point is set to the center of the text

# extent. This can be adjusted with ``relpos`` key value. The values

# are normalized to the extent of the text. For example, (0, 0) means

# lower-left corner and (1, 1) means top-right.

fig, ax = plt.subplots(figsize=(3, 3))

ann = ax.annotate("Test",

xy=(0.2, 0.2), xycoords='data',

xytext=(0.8, 0.8), textcoords='data',

size=20, va="center", ha="center",

bbox=dict(boxstyle="round4", fc="w"),

arrowprops=dict(arrowstyle="-|>",

connectionstyle="arc3,rad=0.2",

relpos=(0., 0.),

fc="w"))

ann = ax.annotate("Test",

xy=(0.2, 0.2), xycoords='data',

xytext=(0.8, 0.8), textcoords='data',

size=20, va="center", ha="center",

bbox=dict(boxstyle="round4", fc="w"),

arrowprops=dict(arrowstyle="-|>",

connectionstyle="arc3,rad=-0.2",

relpos=(1., 0.),

fc="w"))

# %%

# Placing Artist at anchored Axes locations

# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# There are classes of artists that can be placed at an anchored

# location in the Axes. A common example is the legend. This type

# of artist can be created by using the `.OffsetBox` class. A few

# predefined classes are available in :mod:`matplotlib.offsetbox` and in

# :mod:`mpl_toolkits.axes_grid1.anchored_artists`.

from matplotlib.offsetbox import AnchoredText

fig, ax = plt.subplots(figsize=(3, 3))

at = AnchoredText("Figure 1a",

prop=dict(size=15), frameon=True, loc='upper left')

at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")

ax.add_artist(at)

# %%

# The *loc* keyword has same meaning as in the legend command.

#

# A simple application is when the size of the artist (or collection of

# artists) is known in pixel size during the time of creation. For

# example, If you want to draw a circle with fixed size of 20 pixel x 20

# pixel (radius = 10 pixel), you can utilize

# `~mpl_toolkits.axes_grid1.anchored_artists.AnchoredDrawingArea`. The instance

# is created with a size of the drawing area (in pixels), and arbitrary artists

# can be added to the drawing area. Note that the extents of the artists that are

# added to the drawing area are not related to the placement of the drawing

# area itself. Only the initial size matters.

#

# The artists that are added to the drawing area should not have a

# transform set (it will be overridden) and the dimensions of those

# artists are interpreted as a pixel coordinate, i.e., the radius of the

# circles in above example are 10 pixels and 5 pixels, respectively.

from matplotlib.patches import Circle

from mpl_toolkits.axes_grid1.anchored_artists import AnchoredDrawingArea

fig, ax = plt.subplots(figsize=(3, 3))

ada = AnchoredDrawingArea(40, 20, 0, 0,

loc='upper right', pad=0., frameon=False)

p1 = Circle((10, 10), 10)

ada.drawing_area.add_artist(p1)

p2 = Circle((30, 10), 5, fc="r")

ada.drawing_area.add_artist(p2)

ax.add_artist(ada)

# %%

# Sometimes, you want your artists to scale with the data coordinate (or

# coordinates other than canvas pixels). You can use

# `~mpl_toolkits.axes_grid1.anchored_artists.AnchoredAuxTransformBox` class.

# This is similar to

# `~mpl_toolkits.axes_grid1.anchored_artists.AnchoredDrawingArea` except that

# the extent of the artist is determined during the drawing time respecting the

# specified transform.

#

# The ellipse in the example below will have width and height

# corresponding to 0.1 and 0.4 in data coordinates and will be

# automatically scaled when the view limits of the Axes change.

from matplotlib.patches import Ellipse

from mpl_toolkits.axes_grid1.anchored_artists import AnchoredAuxTransformBox

fig, ax = plt.subplots(figsize=(3, 3))

box = AnchoredAuxTransformBox(ax.transData, loc='upper left')

el = Ellipse((0, 0), width=0.1, height=0.4, angle=30) # in data coordinates!

box.drawing_area.add_artist(el)

ax.add_artist(box)

# %%

# Another method of anchoring an artist relative to a parent Axes or anchor

# point is via the *bbox_to_anchor* argument of `.AnchoredOffsetbox`. This

# artist can then be automatically positioned relative to another artist using

# `.HPacker` and `.VPacker`:

from matplotlib.offsetbox import (AnchoredOffsetbox, DrawingArea, HPacker,

TextArea)

fig, ax = plt.subplots(figsize=(3, 3))

box1 = TextArea(" Test: ", textprops=dict(color="k"))

box2 = DrawingArea(60, 20, 0, 0)

el1 = Ellipse((10, 10), width=16, height=5, angle=30, fc="r")

el2 = Ellipse((30, 10), width=16, height=5, angle=170, fc="g")

el3 = Ellipse((50, 10), width=16, height=5, angle=230, fc="b")

box2.add_artist(el1)

box2.add_artist(el2)

box2.add_artist(el3)

box = HPacker(children=[box1, box2],

align="center",

pad=0, sep=5)

anchored_box = AnchoredOffsetbox(loc='lower left',

child=box, pad=0.,

frameon=True,

bbox_to_anchor=(0., 1.02),

bbox_transform=ax.transAxes,

borderpad=0.,)

ax.add_artist(anchored_box)

fig.subplots_adjust(top=0.8)

# %%

# Note that, unlike in `.Legend`, the ``bbox_transform`` is set to

# `.IdentityTransform` by default

#

# .. _annotations-bbox:

#

# Using an Artist as an annotation

# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

# `.AnnotationBbox` uses artists in `.OffsetBox` container artists as the annotations

# and supports positioning these annotations using the same coordinate systems as the

# other annotation methods. For more examples, see

# :doc:`/gallery/text_labels_and_annotations/demo_annotation_box`

from matplotlib.offsetbox import AnnotationBbox, DrawingArea, OffsetImage

from matplotlib.patches import Annulus

fig, ax = plt.subplots()

text = ax.text(.2, .8, "Green!", color='green')

da = DrawingArea(20, 20)

annulus = Annulus((10, 10), 10, 5, color='tab:green')

da.add_artist(annulus)

# position annulus relative to text

ab1 = AnnotationBbox(da, xy=(.5, 0),

xybox=(.5, .25),

xycoords=text,

boxcoords=(text, "data"),

arrowprops=dict(arrowstyle="->"),

bboxprops=dict(alpha=0.5))

ax.add_artist(ab1)

N = 25

arr = np.repeat(np.linspace(0, 1, N), N).reshape(N, N)

im = OffsetImage(arr, cmap='Greens')

im.image.axes = ax

# position gradient relative to text and annulus

ab2 = AnnotationBbox(im, xy=(.5, 0),

xybox=(.75, 0),

xycoords=text,

boxcoords=('data', annulus),

arrowprops=dict(arrowstyle="->"),

bboxprops=dict(alpha=0.5))

ax.add_artist(ab2)

# %%%%

# .. _annotating_coordinate_systems:

#

# Coordinate systems for annotations

# ----------------------------------

#

# Matplotlib Annotations support several types of coordinate systems. The

# examples in :ref:`annotations-tutorial` used the ``data`` coordinate system;

# Some others more advanced options are:

#

# `.Transform` instance

# ^^^^^^^^^^^^^^^^^^^^^

#

# Transforms map coordinates into different coordinate systems, usually the

# display coordinate system. See :ref:`transforms_tutorial` for a detailed

# explanation. Here Transform objects are used to identify the coordinate

# system of the corresponding points. For example, the ``Axes.transAxes``

# transform positions the annotation relative to the Axes coordinates; therefore

# using it is identical to setting the coordinate system to "axes fraction":

fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, figsize=(6, 3))

ax1.annotate("Test", xy=(0.2, 0.2), xycoords=ax1.transAxes)

ax2.annotate("Test", xy=(0.2, 0.2), xycoords="axes fraction")

# %%

# Another commonly used `.Transform` instance is ``Axes.transData``. This

# transform is the coordinate system of the data plotted in the Axes. In this

# example, it is used to draw an arrow between related data points in two

# Axes. We have passed an empty text because in this case, the annotation

# connects data points.

x = np.linspace(-1, 1)

fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, figsize=(6, 3))

ax1.plot(x, -x**3)

ax2.plot(x, -3*x**2)

ax2.annotate("",

xy=(0, 0), xycoords=ax1.transData,

xytext=(0, 0), textcoords=ax2.transData,

arrowprops=dict(arrowstyle="<->"))

# %%

# .. _artist_annotation_coord:

#

# `.Artist` instance

# ^^^^^^^^^^^^^^^^^^

#

# The *xy* value (or *xytext*) is interpreted as a fractional coordinate of the

# bounding box (bbox) of the artist:

fig, ax = plt.subplots(nrows=1, ncols=1, figsize=(3, 3))

an1 = ax.annotate("Test 1",

xy=(0.5, 0.5), xycoords="data",

va="center", ha="center",

bbox=dict(boxstyle="round", fc="w"))

an2 = ax.annotate("Test 2",

xy=(1, 0.5), xycoords=an1, # (1, 0.5) of an1's bbox

xytext=(30, 0), textcoords="offset points",

va="center", ha="left",

bbox=dict(boxstyle="round", fc="w"),

arrowprops=dict(arrowstyle="->"))

# %%

# Note that you must ensure that the extent of the coordinate artist (*an1* in

# this example) is determined before *an2* gets drawn. Usually, this means

# that *an2* needs to be drawn after *an1*. The base class for all bounding

# boxes is `.BboxBase`

#

# Callable that returns `.Transform` of `.BboxBase`

# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# A callable object that takes the renderer instance as single argument, and

# returns either a `.Transform` or a `.BboxBase`. For example, the return

# value of `.Artist.get_window_extent` is a bbox, so this method is identical

# to (2) passing in the artist:

fig, ax = plt.subplots(nrows=1, ncols=1, figsize=(3, 3))

an1 = ax.annotate("Test 1",

xy=(0.5, 0.5), xycoords="data",

va="center", ha="center",

bbox=dict(boxstyle="round", fc="w"))

an2 = ax.annotate("Test 2",

xy=(1, 0.5), xycoords=an1.get_window_extent,

xytext=(30, 0), textcoords="offset points",

va="center", ha="left",

bbox=dict(boxstyle="round", fc="w"),

arrowprops=dict(arrowstyle="->"))

# %%

# `.Artist.get_window_extent` is the bounding box of the Axes object and is

# therefore identical to setting the coordinate system to axes fraction:

fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, figsize=(6, 3))

an1 = ax1.annotate("Test1", xy=(0.5, 0.5), xycoords="axes fraction")

an2 = ax2.annotate("Test 2", xy=(0.5, 0.5), xycoords=ax2.get_window_extent)

# %%

# Blended coordinate specification

# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#

# A blended pair of coordinate specifications -- the first for the

# x-coordinate, and the second is for the y-coordinate. For example, x=0.5 is

# in data coordinates, and y=1 is in normalized axes coordinates:

fig, ax = plt.subplots(figsize=(3, 3))

ax.annotate("Test", xy=(0.5, 1), xycoords=("data", "axes fraction"))

ax.axvline(x=.5, color='lightgray')

ax.set(xlim=(0, 2), ylim=(1, 2))

# %%

# Any of the supported coordinate systems can be used in a blended

# specification. For example, the text "Anchored to 1 & 2" is positioned

# relative to the two `.Text` Artists:

fig, ax = plt.subplots(figsize=(3, 3))

t1 = ax.text(0.05, .05, "Text 1", va='bottom', ha='left')

t2 = ax.text(0.90, .90, "Text 2", ha='right')

t3 = ax.annotate("Anchored to 1 & 2", xy=(0, 0), xycoords=(t1, t2),

va='bottom', color='tab:orange',)

# %%

# `.text.OffsetFrom`

# ^^^^^^^^^^^^^^^^^^

#

# Sometimes, you want your annotation with some "offset points", not from the

# annotated point but from some other point or artist. `.text.OffsetFrom` is

# a helper for such cases.

from matplotlib.text import OffsetFrom

fig, ax = plt.subplots(figsize=(3, 3))

an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",

va="center", ha="center",

bbox=dict(boxstyle="round", fc="w"))

offset_from = OffsetFrom(an1, (0.5, 0))

an2 = ax.annotate("Test 2", xy=(0.1, 0.1), xycoords="data",

xytext=(0, -10), textcoords=offset_from,

# xytext is offset points from "xy=(0.5, 0), xycoords=an1"

va="top", ha="center",

bbox=dict(boxstyle="round", fc="w"),

arrowprops=dict(arrowstyle="->"))

# %%

# Non-text annotations

# --------------------

#

# .. _using_connectionpatch:

#

# Using ConnectionPatch

# ^^^^^^^^^^^^^^^^^^^^^

#

# `.ConnectionPatch` is like an annotation without text. While `~.Axes.annotate`

# is sufficient in most situations, `.ConnectionPatch` is useful when you want

# to connect points in different Axes. For example, here we connect the point

# *xy* in the data coordinates of ``ax1`` to point *xy* in the data coordinates

# of ``ax2``:

from matplotlib.patches import ConnectionPatch

fig, (ax1, ax2) = plt.subplots(nrows=1, ncols=2, figsize=(6, 3))

xy = (0.3, 0.2)

con = ConnectionPatch(xyA=xy, coordsA=ax1.transData,

xyB=xy, coordsB=ax2.transData)

fig.add_artist(con)

# %%

# Here, we added the `.ConnectionPatch` to the *figure*

# (with `~.Figure.add_artist`) rather than to either Axes. This ensures that

# the ConnectionPatch artist is drawn on top of both Axes, and is also necessary

# when using :ref:`constrained_layout <constrainedlayout_guide>`

# for positioning the Axes.

#

# Zoom effect between Axes

# ^^^^^^^^^^^^^^^^^^^^^^^^

#

# `mpl_toolkits.axes_grid1.inset_locator` defines some patch classes useful for

# interconnecting two Axes.

#

# .. figure:: /gallery/subplots_axes_and_figures/images/sphx_glr_axes_zoom_effect_001.png

# :target: /gallery/subplots_axes_and_figures/axes_zoom_effect.html

# :align: center

#

# The code for this figure is at

# :doc:`/gallery/subplots_axes_and_figures/axes_zoom_effect` and

# familiarity with :ref:`transforms_tutorial`

# is recommended.