Repository: matplotlib/matplotlib
File: galleries/examples/text_labels_and_annotations/demo_annotation_box.py (Python)

Code before:
"""
======================
Artists as annotations
======================

`.AnnotationBbox` facilitates annotating parts of the figure or axes using arbitrary
artists, such as texts, images, and `matplotlib.patches`. `.AnnotationBbox` supports
these artists via inputs that are subclasses of `.OffsetBox`, which is a class of
container artists for positioning an artist relative to a parent artist.
"""

import matplotlib.pyplot as plt
import numpy as np

from matplotlib.cbook import get_sample_data
from matplotlib.offsetbox import AnnotationBbox, DrawingArea, OffsetImage, TextArea
from matplotlib.patches import Annulus, Circle, ConnectionPatch

# %%%%
# Text
# ====
#
# `.AnnotationBbox` supports positioning annotations relative to data, Artists, and
# callables, as described in :ref:`annotations`. The  `.TextArea` is used to create a
# textbox that is not explicitly attached to an axes, which allows it to be used for
# annotating figure objects. The `Axes.annotate` method should be used when annotating
# an axes element (such as a plot) with text.
#
fig, axd = plt.subplot_mosaic([['t1', '.', 't2']], layout='compressed')

# Define a 1st position to annotate (display it with a marker)
xy1 = (.25, .75)
xy2 = (.75, .25)
axd['t1'].plot(*xy1, ".r")

Review comment (suggestion):
We should explain what we mean by "annotate". My mental model of annotating is heavily text-biased.

Some thing like

> `.AnnotationBbox` allows to use arbitrary artists as annotations, i.e. a box containing the artists is placed at coordinates *xybox* and a line or arrow can be drawn from the box to another location *xycoords*.
>
> The box containing the artists is a subclass of `.OffsetBox`, which is a container for positioning an artist relative to a parent artist.


Code after:
"""
======================
Artists as annotations
======================

`.AnnotationBbox` facilitates using arbitrary artists as annotations, i.e. data at
position *xy* is annotated by a box containing an artist at position *xybox*. The
coordinate systems for these points are set via the *xycoords* and *boxcoords*
parameters, respectively; see the *xycoords* and *textcoords* parameters of
`.Axes.annotate` for a full listing of supported coordinate systems.
The box containing the artist is a subclass of `.OffsetBox`, which is a container
artist for positioning an artist relative to a parent artist.
"""
from pathlib import Path

import PIL

import matplotlib.pyplot as plt
import numpy as np

from matplotlib import get_data_path
from matplotlib.offsetbox import AnnotationBbox, DrawingArea, OffsetImage, TextArea
from matplotlib.patches import Annulus, Circle, ConnectionPatch

# %%%%
# Text
# ====
#
# `.AnnotationBbox` supports positioning annotations relative to data, Artists, and
# callables, as described in :ref:`annotations`. The  `.TextArea` is used to create a
# textbox that is not explicitly attached to an axes, which allows it to be used for
# annotating figure objects. When annotating an axes element (such as a plot) with text,
# use `.Axes.annotate` because it will create the text artist for you.