Annotating plot

:func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`

:ref:`plotting-guide-annotation`

.. _plotting-guide-annotation:

Annotating Axes

Do not proceed unless you already have read

:func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`!

Annotating with Text with Box

Let's start with a simple example.

.. plot:: users/plotting/examples/annotate_text_arrow.py

The :func:`~matplotlib.pyplot.text` function in the pyplot module (or

text method of the Axes class) takes bbox keyword argument, and when

given, a box around the text is drawn. ::

The patch object associated with the text can be accessed by::

The return value is an instance of FancyBboxPatch and the patch

properties like facecolor, edgewidth, etc. can be accessed and

modified as usual. To change the shape of the box, use *set_boxstyle*

method. ::

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

keyword arguments. Currently, followign box styles are implemented.

Class Name Attrs

LArrow ``larrow`` pad=0.3

RArrow ``rarrow`` pad=0.3

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

.. plot:: mpl_examples/pylab_examples/fancybox_demo2.py

Note that the attrubutes arguments can be specified within the style

name with separating comma (this form can be used as "boxstyle" value

of bbox argument when initializing the text instance) ::

Annotating with Arrow

The :func:`~matplotlib.pyplot.annotate` function in the pyplot module

(or annotate method of the Axes class) is used to draw an arrow

connecting two points on the plot. ::

This annotates a point at ``xy`` in the given coordinate (``xycoords``)

with the text at ``xytext`` given in ``textcoords``. Often, the

annotated point is specified in the *data* coordinate and the annotating

text in *offset points*.

See :func:`~matplotlib.pyplot.annotate` for available coordinate systems.

An arrow connecting two point (xy & xytext) can be optionally drawn by

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

empty string as the first argument. ::

.. plot:: users/plotting/examples/annotate_simple01.py

The arrow drawing takes a few steps.

1. a connecting path between two points are created. This is

controlled by ``connectionstyle`` key value.

2. If patch object is given (*patchA* & *patchB*), the path is clipped to

avoid the patch.

3. The path is further shrinked by given amount of pixels (*shirnkA*

& *shrinkB*)

4. The path is transmuted to arrow patch, which is controlled by the

``arrowstyle`` key value.

.. plot:: users/plotting/examples/annotate_explain.py

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

``connectionstyle`` key and follwing 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 option only can

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, it may be changed in the future).

.. plot:: users/plotting/examples/connectionstyle_demo.py

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

``-|>`` 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

.. plot:: mpl_examples/pylab_examples/fancyarrow_demo.py

Some arrowstyles only work with connection style that generates a

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

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

style.

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

of the text by default.

.. plot:: users/plotting/examples/annotate_simple02.py

As in the text command, a box around the text can be drawn using

the ``bbox`` argument.

.. plot:: users/plotting/examples/annotate_simple03.py

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.

.. plot:: users/plotting/examples/annotate_simple04.py

Using ConnectorPatch

The ConnectorPatch is like an annotation without a text. While the

annotate function is recommended in most of situation, the

ConnectorPatch is useful when you want to connect points in different

axes. ::

The above code connects point xy in data coordinate of ``ax1`` to

point xy int data coordiante of ``ax2``. Here is a simple example.

.. plot:: users/plotting/examples/connect_simple01.py

While the ConnectorPatch instance can be added to any axes, but you

may want it to be added to the axes in the latter (?) of the axes

drawing order to prevent overlap (?) by other axes.

Placing Artist at the anchored location of the Axes

There are class of artist that can be placed at the anchored location

of the Axes. A common example is the legend. This type of artists can

be created by using the OffsetBox class. A few predefined classes are

available in ``mpl_toolkits.axes_grid.anchored_artists``. ::

.. plot:: users/plotting/examples/anchored_box01.py

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 knwon 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

``AnchoredDrawingArea``. The instance is created with a size of the

drawing area (in pixel). And user can add arbitrary artist to the

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

the drawing area has nothing to do with the placement of the drawing

area itself. The initial size only matters. ::

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

transform set (they will be overridden) and the dimension of those

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

circles in above example are 10 pixel and 5 pixel, respectively.

.. plot:: users/plotting/examples/anchored_box02.py

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

other coordinate than canvas pixel). You can use

``AnchoredAuxTransformBox`` class. This is similar to

``AnchoredDrawingArea`` except that the extent of the artist is

determined during the drawing time respecting the specified transform. ::

The ellipse in the above example will have width and height

corresponds to 0.1 and 0.4 in data coordinate and will be

automatically scaled when the view limits of the axes change.

.. plot:: users/plotting/examples/anchored_box03.py

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).

.. plot:: users/plotting/examples/anchored_box04.py

Note that unlike the legend, the ``bbox_transform`` is set

to IdentityTransform by default.

Advanced Topics

Zoom effect between Axes

mpl_toolkits.axes_grid.inset_locator defines some patch classs useful

for interconnect two axes. Understanding the code requires some

knowledge of how mpl's transform works. But, utilizing it will be

straight forward.

.. plot:: mpl_examples/pylab_examples/axes_zoom_effect.py

Define Custom BoxStyle

You can use a custom box style. The value for the ``boxstyle`` can be a

callable object in following forms.::

Here is a complete example.

.. plot:: users/plotting/examples/custom_boxstyle01.py

However, it is recommended that you derive from the

matplotlib.patches.BoxStyle._Base as demonstrated below.

.. plot:: users/plotting/examples/custom_boxstyle02.py

:include-source:

Similarly, you can define custom ConnectionStyle and Custome ArrowStyle.

See the source code of ``lib/matplotlib/patches.py`` and check

how each style class is defined.

import matplotlib.pyplot as plt

from mpl_toolkits.axes_grid.anchored_artists import AnchoredText

fig=plt.figure(1, figsize=(3,3))

ax = plt.subplot(111)

at = AnchoredText("Figure 1a",

prop=dict(size=15), frameon=True,

loc=2,

)

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

ax.add_artist(at)

plt.show()

from matplotlib.patches import Circle

import matplotlib.pyplot as plt

from mpl_toolkits.axes_grid.anchored_artists import AnchoredDrawingArea

fig=plt.figure(1, figsize=(3,3))

ax = plt.subplot(111)

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

loc=1, 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)

plt.show()

from matplotlib.patches import Ellipse

import matplotlib.pyplot as plt

from mpl_toolkits.axes_grid.anchored_artists import AnchoredAuxTransformBox

fig=plt.figure(1, figsize=(3,3))

ax = plt.subplot(111)

box = AnchoredAuxTransformBox(ax.transData, loc=2)

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)

plt.show()