added offset to annotations tutorial

story645 · story645 · commit 9323dee3043e · 2022-08-11T23:41:38.000-04:00
diff --git a/tutorials/text/annotations.py b/tutorials/text/annotations.py
@@ -59,6 +59,14 @@
 # For physical coordinate systems (points or pixels) the origin is the
 # bottom-left of the figure or axes.
 #
+# The following strings are also valid for *textcoords*
+# ==================  ========================================================
+# argument            coordinate system
+# ==================  ========================================================
+# 'offset points'     offset (in points) from the xy value
+# 'offset pixels'     offset (in pixels) from the xy value
+# ==================  ========================================================
+
 # 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*.
@@ -78,9 +86,9 @@
 # ==================== =====================================================
 #
 #
-# 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 default coordinate system for
+# the axes projection (*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
@@ -104,6 +112,23 @@
 # Advanced Annotations
 # --------------------
 #
+# Placing Annotations Relative to Data
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Annotations can be positioned at a relative offset to the *xy* input to
+# annotation by setting the *textcoords* kwarg to one of the offset options.
+# In this example, the annotations are offset 1.5 points from the given *xy*
+# values.
+
+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')
+
 # Annotating with Text with Box
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
