The matplotlib.pyplot.annotate
function in the matplotlib.pyplot module is used to Annotate the point xy
with text text
.
In the simplest form, the text is placed at xy
.
Optionally, the text can be displayed in another position xytext
. An arrow pointing from the text to the annotated point xy
can then be added by defining arrowprops
.
matplotlib.pyplot.annotate Syntax
The syntax of the matplotlib.pyplot.annotate
method is as follows:
matplotlib.pyplot.annotate(text, xy, *args, **kwargs)
matplotlib.pyplot.annotate Parameters
The matplotlib.pyplot.annotate
accepts the following parameters:
Parameter | Description |
---|---|
text |
string. The text of the annotation. |
xy |
(float, float) The point (x, y) to annotate. The coordinate system is determined by xycoords . |
xytext |
(float, float), default: xy The position (x, y) to place the text at. The coordinate system is determined by textcoords . |
xycoords |
string or Artist or Transform or callable or (float, float), default: ‘data’ The coordinate system that xy is given in. An Artist: xy is interpreted as a fraction of the artist’s Bbox. E.g. (0, 0) would be the lower left corner of the bounding box and (0.5, 1) would be the center top of the bounding box. A Transform to transform xy to screen coordinates. A function with one of the following signatures: def transform(renderer) -> Bbox def transform(renderer) -> Transform A tuple (xcoords, ycoords) specifying separate coordinate systems for x and y. xcoords and ycoords must each be of one of the above described types. |
textcoords |
string or Artist or Transform or callable or (float, float), default: value of xycoords The coordinate system that xytext is given in. |
arrowprops |
dict The properties used to draw a FancyArrowPatch arrow between the positions xy and xytext. Defaults to None, i.e. no arrow is drawn. For historical reasons there are two different ways to specify arrows, "simple" and "fancy". |
annotation_clip |
bool or None, default: None Whether to draw the annotation when the annotation point xy is outside the axes area.If True, the annotation will only be drawn when xy is within the axes. If False, the annotation will always be drawn. If None, the annotation will only be drawn when xy is within the axes and xycoords is ‘data’. |
**kwargs |
Additional kwargs are passed to Text. |
For xycoords, The following types of values are supported:
Value | Description |
---|---|
‘figure points’ | Points from the lower left of the figure |
‘figure pixels’ | Pixels from the lower left of the figure |
‘figure fraction’ | Fraction of figure from lower left |
‘subfigure points’ | Points from the lower left of the subfigure |
‘subfigure pixels’ | Pixels from the lower left of the subfigure |
‘subfigure fraction’ | Fraction of subfigure from lower left |
‘axes points’ | Points from lower left corner of axes |
‘axes pixels’ | Pixels from lower left corner of axes |
‘axes fraction’ | Fraction of axes from lower left |
‘data’ | Use the coordinate system of the object being annotated (default) |
‘polar’ | (theta, r) if not native ‘data’ coordinates |
Note that ‘subfigure pixels’ and ‘figure pixels’ are the same for the parent figure, so users who want code that is usable in a subfigure can use ‘subfigure pixels’.
Simple arrow:
If arrowprops does not contain the key ‘arrowstyle’ the allowed keys are:
Key | Description |
---|---|
width | The width of the arrow in points |
headwidth | The width of the base of the arrow head in points |
headlength | The length of the arrow head in points |
shrink | Fraction of total length to shrink from both ends |
? | Any key to matplotlib.patches.FancyArrowPatch |
The arrow is attached to the edge of the text box, the exact position (corners or centers) depending on where it’s pointing to.
Fancy arrow:
This is used if ‘arrowstyle’ is provided in the arrowprops.
Valid keys are the following FancyArrowPatch parameters:
Key | Description |
---|---|
arrowstyle | the arrow style |
connectionstyle | the connection style |
relpos | see below; default is (0.5, 0.5) |
patchA | default is bounding box of the text |
patchB | default is None |
shrinkA | default is 2 points |
shrinkB | default is 2 points |
mutation_scale | default is text size (in points) |
mutation_aspect | default is 1. |
? | any key for matplotlib.patches.PathPatch |
The exact starting point position of the arrow is defined by relpos. It’s a tuple of relative coordinates of the text box, where (0, 0) is the lower left corner and (1, 1) is the upper right corner. Values <0 and >1 are supported and specify points outside the text box. By default (0.5, 0.5) the starting point is centered in the text box.
matplotlib.pyplot.annotate Returns
The return value of the matplotlib.pyplot.annotate
function is annotation
.
Demo #1: Basic usage of matplotlib.pyplot.annotate
The following example demonstrates the use of the matplotlib.pyplot.annotate
method −
# Demo of matplotlib.pyplot.annotate function
import numpy as np
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
t = np.arange(0.0, 5.0, 0.01)
s = np.cos(2*np.pi*t)
line, = ax.plot(t, s, lw=2)
ax.annotate('local max', xy=(4, 1), xytext=(3, 1.5),
arrowprops=dict(facecolor='black', shrink=0.05),
)
ax.annotate('local min', xy=(3.5, -1), xytext=(3, -1.5),
arrowprops=dict(facecolor='red', shrink=0.1),
)
ax.set_ylim(-2, 2)
plt.title('matplotlib.pyplot.annotate ApiDemos.com')
plt.show()
When we run above program, it produces following result −
Demo#2:
# Demo of matplotlib.pyplot.annotate function
import numpy as np
import matplotlib.pyplot as plt
x = np.arange(0, 10, 0.005)
y = np.exp(-x / 3.) * np.sin(3 * np.pi * x)
fig, ax = plt.subplots()
ax.plot(x, y)
ax.set_xlim(0, 10)
ax.set_ylim(-1, 1)
# Setting up the parameters
xdata, ydata = 2, 0
xdisplay, ydisplay = ax.transData.transform((xdata, ydata))
bbox = dict(boxstyle="round", fc="0.8")
arrowprops = dict(
arrowstyle="->",
connectionstyle="angle, angleA = 0, angleB = 90,\
rad = 10")
offset = 72
# Annotation
ax.annotate('data = (%.1f, %.1f)' % (xdata, ydata),
(xdata, ydata), xytext=(-2 * offset, offset),
textcoords='offset points',
bbox=bbox, arrowprops=arrowprops)
disp = ax.annotate('display = (%.1f, %.1f)' % (xdisplay, ydisplay),
(xdisplay, ydisplay), xytext=(0.5 * offset, -offset),
xycoords='figure pixels',
textcoords='offset points',
bbox=bbox, arrowprops=arrowprops)
plt.title('matplotlib.pyplot.annotate ApiDemos.com')
plt.show()
When we run above program, it produces following result −