added offset section and restructured annotations tutorial and reworked

story645 · jklymak · timhoffm · story645 · commit c9468c10aabe · 2022-08-17T14:38:03.000-04:00
AnchoredOffsetbox section

also minor consistency and linking tweaks throughout

Co-authored-by: Jody Klymak &lt;jklymak@gmail.com&gt;
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
Co-authored-by: Elliott Sales de Andrade &lt;quantum.analyst@gmail.com&gt;
diff --git a/tutorials/text/annotations.py b/tutorials/text/annotations.py
@@ -47,22 +47,46 @@
 # 'data'              use the axes data coordinate system
 # ==================  ========================================================
 #
-# For example to place the text coordinates in fractional axes
-# coordinates, one could do::
+# The following strings are also valid arguments for *textcoords*
 #
-#     ax.annotate('local max', xy=(3, 1),  xycoords='data',
-#                 xytext=(0.8, 0.95), textcoords='axes fraction',
-#                 arrowprops=dict(facecolor='black', shrink=0.05),
-#                 horizontalalignment='right', verticalalignment='top',
-#                 )
+# ==================  ========================================================
+# 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.
+# 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`.
 #
-# Optionally, 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*.
+# .. _annotation-data:
+#
+# Annotating data
+# ~~~~~~~~~~~~~~~
+#
+# For example to place the text coordinates in fractional axes
+# coordinates, one could do :
+
+fig, ax = plt.subplots()
+ax.scatter(3, 1, s=20)
+ax.annotate('local max',
+            xy=(3, 1),  xycoords='data',
+            xytext=(0.8, 0.95), textcoords='axes fraction',
+            horizontalalignment='right', verticalalignment='top')
+
+###################################################################
+#
+# .. _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
@@ -77,10 +101,9 @@
 #                      e.g., ``facecolor``
 # ==================== =====================================================
 #
-#
-# In the example below, the *xy* point is in native coordinates
-# (*xycoords* defaults to 'data').  For a polar axes, this is in
-# (theta, radius) space.  The text in this example is placed in the
+# 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
@@ -94,18 +117,38 @@
 # annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
 # and :doc:`/gallery/text_labels_and_annotations/annotation_demo`.
 #
+# .. _annotations-offset-text:
 #
-# Do not proceed unless you have already read :ref:`annotations-tutorial`,
-# :func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`!
-#
+# 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()
+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 Annotations
-# --------------------
+# Advanced annotation
+# -------------------
 #
-# Annotating with Text with Box
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# We recommend reading :ref:`annotations-tutorial`, :func:`~matplotlib.pyplot.text`
+# and :func:`~matplotlib.pyplot.annotate` before reading this section.
+#
+# Annotating with boxed text
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 # Let's start with a simple example.
 #
@@ -116,9 +159,9 @@
 # `~.Axes.text` takes a *bbox* keyword argument, which draws a box around the
 # text::
 #
-#     t = ax.text(
-#         0, 0, "Direction", ha="center", va="center", rotation=45, size=15,
-#         bbox=dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2))
+#     t = ax.text(0, 0, "Direction",
+#                 ha="center", va="center", rotation=45, size=15,
+#                 bbox=dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2))
 #
 # The patch object associated with the text can be accessed by::
 #
@@ -155,17 +198,16 @@
 # name with separating comma (this form can be used as "boxstyle" value
 # of bbox argument when initializing the text instance) ::
 #
-#    bb.set_boxstyle("rarrow,pad=0.6")
+#    bb.set_boxstyle("rarrow, pad=0.6")
 #
-# Annotating with Arrow
-# ~~~~~~~~~~~~~~~~~~~~~
+# Customizing annotation arrows
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 # `~.Axes.annotate` draws an arrow connecting two points in an Axes::
 #
 #     ax.annotate("Annotation",
 #                 xy=(x1, y1), xycoords='data',
-#                 xytext=(x2, y2), textcoords='offset points',
-#                 )
+#                 xytext=(x2, y2), textcoords='offset points')
 #
 # This annotates a point at *xy* in the given coordinate (*xycoords*)
 # with the text at *xytext* given in *textcoords*. Often, the
@@ -180,9 +222,7 @@
 #     ax.annotate("",
 #                 xy=(0.2, 0.2), xycoords='data',
 #                 xytext=(0.8, 0.8), textcoords='data',
-#                 arrowprops=dict(arrowstyle="->",
-#                                 connectionstyle="arc3"),
-#                 )
+#                 arrowprops=dict(arrowstyle="->", connectionstyle="arc3"))
 #
 # .. figure:: ../../gallery/userdemo/images/sphx_glr_annotate_simple01_001.png
 #    :target: ../../gallery/userdemo/annotate_simple01.html
@@ -292,8 +332,8 @@
 from matplotlib.offsetbox import AnchoredText
 
 fig, ax = plt.subplots()
-at = AnchoredText(
-    "Figure 1a", prop=dict(size=15), frameon=True, loc='upper left')
+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)
 
@@ -348,19 +388,64 @@
 ax.add_artist(box)
 
 ###############################################################################
-# As in the legend, the bbox_to_anchor argument can be set.  Using the
-# HPacker and VPacker, you can have an arrangement(?) of artist as in the
-# legend (as a matter of fact, this is how the legend is created).
+# 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)
+#
+#   box1 = TextArea(" Test: ", textprops=dict(color="k"))
+#   box2 = DrawingArea(60, 20, 0, 0)
+#   # see gallery example for ellipse drawing code
+#   box = HPacker(children=[box1, box2], align="center", pad=0, sep=5)
+#   anchored_box = AnchoredOffsetbox(loc='lower left', child=box, pad=0.,
+#                                    frameon=True, borderpad=0.,
+#                                    bbox_to_anchor=(0., 1.02),
+#                                    bbox_transform=ax.transAxes)
 #
 # .. figure:: ../../gallery/userdemo/images/sphx_glr_anchored_box04_001.png
 #    :target: ../../gallery/userdemo/anchored_box04.html
 #    :align: center
 #
-# Note that unlike the legend, the ``bbox_transform`` is set
-# to IdentityTransform by default.
+# Note that, unlike in `.Legend`, the ``bbox_transform`` is set to
+# IdentityTransform by default. The full example can be found at
+# :doc:`/gallery/userdemo/anchored_box04`.
 #
-# Coordinate systems for Annotations
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Defining custom box styles
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# You can use a custom box style. The value for the ``boxstyle`` can be a
+# callable object in the following forms. ::
+#
+#         def __call__(self, x0, y0, width, height, mutation_size,
+#                      aspect_ratio=1.):
+#             '''
+#             Given the location and size of the box, return the path of
+#             the box around it.
+#
+#               - *x0*, *y0*, *width*, *height* : location and size of the box
+#               - *mutation_size* : a reference scale for the mutation.
+#               - *aspect_ratio* : aspect-ratio for the mutation.
+#             '''
+#             path = ...
+#             return path
+#
+# Here is a complete example.
+#
+# .. figure:: ../../gallery/userdemo/images/sphx_glr_custom_boxstyle01_001.png
+#    :target: ../../gallery/userdemo/custom_boxstyle01.html
+#    :align: center
+#
+# Similarly, you can define a custom `.ConnectionStyle` and a custom
+# `.ArrowStyle`. View the source code at `.patches` to learn how each class
+# is defined.
+#
+# .. _annotating_coordinate_systems:
+#
+# Coordinate systems for annotations
+# ----------------------------------
 #
 # Matplotlib Annotations support several types of coordinates.  Some are
 # described in :ref:`annotations-tutorial`; more advanced options are
@@ -376,18 +461,22 @@
 #    This allows annotating a point in another axes::
 #
 #      fig, (ax1, ax2) = plt.subplots(1, 2)
-#      ax2.annotate("Test", xy=(0.5, 0.5), xycoords=ax1.transData,
+#      ax2.annotate("Test",
+#                   xy=(0.5, 0.5), xycoords=ax1.transData,
 #                   xytext=(0.5, 0.5), textcoords=ax2.transData,
 #                   arrowprops=dict(arrowstyle="->"))
 #
 # 2. An `.Artist` instance. The *xy* value (or *xytext*) is interpreted as a
 #    fractional coordinate of the bbox (return value of *get_window_extent*) of
-#    the artist::
+#    the artist: ::
 #
-#      an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",
+#      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 the an1's bbox
+#
+#      an2 = ax.annotate("Test 2",
+#                        xy=(1, 0.5), xycoords=an1,  # (1, 0.5) of the an1's bbox
 #                        xytext=(30, 0), textcoords="offset points",
 #                        va="center", ha="left",
 #                        bbox=dict(boxstyle="round", fc="w"),
@@ -405,12 +494,14 @@
 #    returns either a `.Transform` or a `.BboxBase`.  The return value is then
 #    handled as in (1), for transforms, or in (2), for bboxes.  For example, ::
 #
-#      an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1,
+#      an2 = ax.annotate("Test 2",
+#                        xy=(1, 0.5), xycoords=an1,
 #                        xytext=(30, 0), textcoords="offset points")
 #
 #    is identical to::
 #
-#      an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1.get_window_extent,
+#      an2 = ax.annotate("Test 2",
+#                        xy=(1, 0.5), xycoords=an1.get_window_extent,
 #                        xytext=(30, 0), textcoords="offset points")
 #
 # 4. A pair of coordinate specifications -- the first for the x-coordinate, and
@@ -434,18 +525,18 @@
 #       :target: ../../gallery/userdemo/annotate_simple_coord03.html
 #       :align: center
 #
-#    You may take a look at this example
+#    This example can be found at
 #    :doc:`/gallery/text_labels_and_annotations/annotation_demo`.
 #
 # Using ConnectionPatch
 # ~~~~~~~~~~~~~~~~~~~~~
 #
 # ConnectionPatch is like an annotation without text. While `~.Axes.annotate`
-# is sufficient in most situations, ConnectionPatch is useful when you want to
+# is sufficient in most situations, `.ConnectionPatch` is useful when you want to
 # connect points in different axes. ::
 #
 #   from matplotlib.patches import ConnectionPatch
-#   xy = (0.2, 0.2)
+#   xy = (0.3, 0.2)
 #   con = ConnectionPatch(xyA=xy, coordsA=ax1.transData,
 #                         xyB=xy, coordsB=ax2.transData)
 #   fig.add_artist(con)
@@ -462,9 +553,6 @@
 # and is also necessary if using :doc:`constrained_layout
 # </tutorials/intermediate/constrainedlayout_guide>` for positioning the axes.
 #
-# Advanced Topics
-# ---------------
-#
 # Zoom effect between Axes
 # ~~~~~~~~~~~~~~~~~~~~~~~~
 #
@@ -475,32 +563,3 @@
 # .. 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
-#
-# Define Custom BoxStyle
-# ~~~~~~~~~~~~~~~~~~~~~~
-#
-# You can use a custom box style. The value for the ``boxstyle`` can be a
-# callable object in the following forms.::
-#
-#         def __call__(self, x0, y0, width, height, mutation_size,
-#                      aspect_ratio=1.):
-#             '''
-#             Given the location and size of the box, return the path of
-#             the box around it.
-#
-#               - *x0*, *y0*, *width*, *height* : location and size of the box
-#               - *mutation_size* : a reference scale for the mutation.
-#               - *aspect_ratio* : aspect-ratio for the mutation.
-#             '''
-#             path = ...
-#             return path
-#
-# Here is a complete example.
-#
-# .. figure:: ../../gallery/userdemo/images/sphx_glr_custom_boxstyle01_001.png
-#    :target: ../../gallery/userdemo/custom_boxstyle01.html
-#    :align: center
-#
-# Similarly, you can define a custom ConnectionStyle and a custom ArrowStyle.
-# See the source code of ``lib/matplotlib/patches.py`` and check
-# how each style class is defined.
