|
13 | 13 | ############################################################################### |
14 | 14 | # .. _annotations-tutorial: |
15 | 15 | # |
16 | | -# Basic annotation |
| 16 | +# Basic Annotation |
17 | 17 | # ---------------- |
18 | 18 | # |
19 | 19 | # The uses of the basic :func:`~matplotlib.pyplot.text` will place text |
|
47 | 47 | # 'data' use the axes data coordinate system |
48 | 48 | # ================== ======================================================== |
49 | 49 | # |
50 | | -# For example to place the text coordinates in fractional axes |
51 | | -# coordinates, one could do:: |
| 50 | +# The following strings are also valid arguments for *textcoords* |
52 | 51 | # |
53 | | -# ax.annotate('local max', xy=(3, 1), xycoords='data', |
54 | | -# xytext=(0.8, 0.95), textcoords='axes fraction', |
55 | | -# arrowprops=dict(facecolor='black', shrink=0.05), |
56 | | -# horizontalalignment='right', verticalalignment='top', |
57 | | -# ) |
| 52 | +# ================== ======================================================== |
| 53 | +# argument coordinate system |
| 54 | +# ================== ======================================================== |
| 55 | +# 'offset points' offset (in points) from the xy value |
| 56 | +# 'offset pixels' offset (in pixels) from the xy value |
| 57 | +# ================== ======================================================== |
58 | 58 | # |
59 | 59 | # For physical coordinate systems (points or pixels) the origin is the |
60 | | -# bottom-left of the figure or axes. |
| 60 | +# bottom-left of the figure or axes. Points are |
| 61 | +# `typographic points <https://en.wikipedia.org/wiki/Point_(typography)>`_ |
| 62 | +# meaning that they are a physical unit measuring 1/72 of an inch. Points and |
| 63 | +# pixels are discussed in further detail in :ref:`transforms-fig-scale-dpi`. |
61 | 64 | # |
62 | | -# Optionally, you can enable drawing of an arrow from the text to the annotated |
63 | | -# point by giving a dictionary of arrow properties in the optional keyword |
64 | | -# argument *arrowprops*. |
| 65 | +# .. _annotation_basic: |
| 66 | +# |
| 67 | +# Annotating data |
| 68 | +# ~~~~~~~~~~~~~~~ |
| 69 | +# |
| 70 | +# For example to place the text coordinates in fractional axes |
| 71 | +# coordinates, one could do :: |
| 72 | + |
| 73 | +fig, ax = plt.subplots() |
| 74 | +ax.scatter(3, 1, s=20) |
| 75 | +ax.annotate('local max', xy=(3, 1), xycoords='data', |
| 76 | + xytext=(0.8, 0.95), textcoords='axes fraction', |
| 77 | + horizontalalignment='right', verticalalignment='top') |
| 78 | + |
| 79 | +################################################################### |
| 80 | +# |
| 81 | +# .. _annotation_with_arrow: |
| 82 | +# |
| 83 | +# Annotating With Arrows |
| 84 | +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
65 | 85 | # |
| 86 | +# You can enable drawing of an arrow from the text to the annotated point |
| 87 | +# by giving a dictionary of arrow properties in the optional keyword |
| 88 | +# argument *arrowprops*. |
66 | 89 | # |
67 | 90 | # ==================== ===================================================== |
68 | 91 | # *arrowprops* key description |
|
77 | 100 | # e.g., ``facecolor`` |
78 | 101 | # ==================== ===================================================== |
79 | 102 | # |
80 | | -# |
81 | | -# In the example below, the *xy* point is in native coordinates |
82 | | -# (*xycoords* defaults to 'data'). For a polar axes, this is in |
83 | | -# (theta, radius) space. The text in this example is placed in the |
| 103 | +# In the example below, the *xy* point is in the default coordinate system for |
| 104 | +# the axes projection (*xycoords* defaults to 'data'). For a polar axes, this |
| 105 | +# is in (theta, radius) space. The text in this example is placed in the |
84 | 106 | # fractional figure coordinate system. :class:`matplotlib.text.Text` |
85 | 107 | # keyword arguments like *horizontalalignment*, *verticalalignment* and |
86 | 108 | # *fontsize* are passed from `~matplotlib.axes.Axes.annotate` to the |
|
98 | 120 | # Do not proceed unless you have already read :ref:`annotations-tutorial`, |
99 | 121 | # :func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`! |
100 | 122 | # |
| 123 | +# .. _annotations-offset-text: |
| 124 | +# |
| 125 | +# Placing Text Annotations relative to data |
| 126 | +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 127 | +# Annotations can be positioned at a relative offset to the *xy* input to |
| 128 | +# annotation by setting the *textcoords* kwarg to one of the offset options |
| 129 | +# (points or pixels). |
| 130 | + |
| 131 | +fig, ax = plt.subplots() |
| 132 | +x = [1, 3, 5, 7, 9] |
| 133 | +y = [2, 4, 6, 8, 10] |
| 134 | +annotations = ["A", "B", "C", "D", "E"] |
| 135 | +ax.scatter(x, y, s=20) |
| 136 | + |
| 137 | +for xi, yi, text in zip(x, y, annotations): |
| 138 | + ax.annotate(text, xy=(xi, yi), xycoords='data', |
| 139 | + xytext=(1.5, 1.5), textcoords='offset points') |
| 140 | + |
| 141 | +############################################################################### |
| 142 | +# The annotations are offset 1.5 points (1.5*1/72 inches) from the *xy* values. |
101 | 143 | # |
102 | 144 | # .. _plotting-guide-annotation: |
103 | 145 | # |
104 | | -# Advanced Annotations |
| 146 | +# Advanced Annotation |
105 | 147 | # -------------------- |
106 | 148 | # |
107 | | -# Annotating with Text with Box |
| 149 | +# Annotating with Text in Box |
108 | 150 | # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
109 | 151 | # |
110 | 152 | # Let's start with a simple example. |
|
116 | 158 | # `~.Axes.text` takes a *bbox* keyword argument, which draws a box around the |
117 | 159 | # text:: |
118 | 160 | # |
119 | | -# t = ax.text( |
120 | | -# 0, 0, "Direction", ha="center", va="center", rotation=45, size=15, |
121 | | -# bbox=dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2)) |
| 161 | +# t = ax.text(0, 0, "Direction", ha="center", va="center", rotation=45, |
| 162 | +# size=15, bbox=dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2) |
| 163 | +# ) |
122 | 164 | # |
123 | 165 | # The patch object associated with the text can be accessed by:: |
124 | 166 | # |
|
157 | 199 | # |
158 | 200 | # bb.set_boxstyle("rarrow,pad=0.6") |
159 | 201 | # |
160 | | -# Annotating with Arrow |
161 | | -# ~~~~~~~~~~~~~~~~~~~~~ |
| 202 | +# Customizing Annotation Arrow |
| 203 | +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
162 | 204 | # |
163 | 205 | # `~.Axes.annotate` draws an arrow connecting two points in an Axes:: |
164 | 206 | # |
|
359 | 401 | # Note that unlike the legend, the ``bbox_transform`` is set |
360 | 402 | # to IdentityTransform by default. |
361 | 403 | # |
| 404 | +# Define custom BoxStyle |
| 405 | +# ~~~~~~~~~~~~~~~~~~~~~~ |
| 406 | +# |
| 407 | +# You can use a custom box style. The value for the ``boxstyle`` can be a |
| 408 | +# callable object in the following forms. :: |
| 409 | +# |
| 410 | +# def __call__(self, x0, y0, width, height, mutation_size, |
| 411 | +# aspect_ratio=1.): |
| 412 | +# ''' |
| 413 | +# Given the location and size of the box, return the path of |
| 414 | +# the box around it. |
| 415 | +# |
| 416 | +# - *x0*, *y0*, *width*, *height* : location and size of the box |
| 417 | +# - *mutation_size* : a reference scale for the mutation. |
| 418 | +# - *aspect_ratio* : aspect-ratio for the mutation. |
| 419 | +# ''' |
| 420 | +# path = ... |
| 421 | +# return path |
| 422 | +# |
| 423 | +# Here is a complete example. |
| 424 | +# |
| 425 | +# .. figure:: ../../gallery/userdemo/images/sphx_glr_custom_boxstyle01_001.png |
| 426 | +# :target: ../../gallery/userdemo/custom_boxstyle01.html |
| 427 | +# :align: center |
| 428 | +# |
| 429 | +# Similarly, you can define a custom ConnectionStyle and a custom ArrowStyle. |
| 430 | +# See the source code of ``lib/matplotlib/patches.py`` and check |
| 431 | +# how each style class is defined. |
| 432 | +# |
| 433 | +# .. _annotating_coordinate systems: |
| 434 | +# |
362 | 435 | # Coordinate systems for Annotations |
363 | | -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 436 | +# ---------------------------------- |
364 | 437 | # |
365 | 438 | # Matplotlib Annotations support several types of coordinates. Some are |
366 | 439 | # described in :ref:`annotations-tutorial`; more advanced options are |
|
462 | 535 | # and is also necessary if using :doc:`constrained_layout |
463 | 536 | # </tutorials/intermediate/constrainedlayout_guide>` for positioning the axes. |
464 | 537 | # |
465 | | -# Advanced Topics |
466 | | -# --------------- |
467 | | -# |
468 | 538 | # Zoom effect between Axes |
469 | 539 | # ~~~~~~~~~~~~~~~~~~~~~~~~ |
470 | 540 | # |
|
475 | 545 | # .. figure:: ../../gallery/subplots_axes_and_figures/images/sphx_glr_axes_zoom_effect_001.png |
476 | 546 | # :target: ../../gallery/subplots_axes_and_figures/axes_zoom_effect.html |
477 | 547 | # :align: center |
478 | | -# |
479 | | -# Define Custom BoxStyle |
480 | | -# ~~~~~~~~~~~~~~~~~~~~~~ |
481 | | -# |
482 | | -# You can use a custom box style. The value for the ``boxstyle`` can be a |
483 | | -# callable object in the following forms.:: |
484 | | -# |
485 | | -# def __call__(self, x0, y0, width, height, mutation_size, |
486 | | -# aspect_ratio=1.): |
487 | | -# ''' |
488 | | -# Given the location and size of the box, return the path of |
489 | | -# the box around it. |
490 | | -# |
491 | | -# - *x0*, *y0*, *width*, *height* : location and size of the box |
492 | | -# - *mutation_size* : a reference scale for the mutation. |
493 | | -# - *aspect_ratio* : aspect-ratio for the mutation. |
494 | | -# ''' |
495 | | -# path = ... |
496 | | -# return path |
497 | | -# |
498 | | -# Here is a complete example. |
499 | | -# |
500 | | -# .. figure:: ../../gallery/userdemo/images/sphx_glr_custom_boxstyle01_001.png |
501 | | -# :target: ../../gallery/userdemo/custom_boxstyle01.html |
502 | | -# :align: center |
503 | | -# |
504 | | -# Similarly, you can define a custom ConnectionStyle and a custom ArrowStyle. |
505 | | -# See the source code of ``lib/matplotlib/patches.py`` and check |
506 | | -# how each style class is defined. |
|
0 commit comments