8000 DOC: yet more re-organization / consolidation · matplotlib/matplotlib@cdc11fe · GitHub
[go: up one dir, main page]
Skip to content

Commit cdc11fe

Browse files
tacaswelltacaswell
committed
DOC: yet more re-organization / consolidation
1 parent 39636b0 commit cdc11fe

13 files changed

+285
-254
lines changed

‎doc/users/annotations_guide.rst renamed to ‎doc/users/annotations.rst

Lines changed: 102 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,108 @@
1-
.. _plotting-guide-annotation:
1+
============
2+
Annotation
3+
============
4+
5+
.. contents:: Table of Contents
6+
:depth: 3
7+
8+
.. _annotations-tutorial:
9+
10+
Basic annotation
11+
================
12+
13+
The uses of the basic :func:`~matplotlib.pyplot.text` command above
14+
place text at an arbitrary position on the Axes. A common use case of
15+
text is to annotate some feature of the plot, and the
16+
:func:`~matplotlib.Axes.annotate` method provides helper functionality
17+
to make annotations easy. In an annotation, there are two points to
18+
consider: the location being annotated represented by the argument
19+
``xy`` and the location of the text ``xytext``. Both of these
20+
arguments are ``(x,y)`` tuples.
21+
22+
.. plot:: pyplots/annotation_basic.py
23+
:include-source:
24+
25+
26+
In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
27+
(text location) are in data coordinates. There are a variety of other
28+
coordinate systems one can choose -- you can specify the coordinate
29+
system of ``xy`` and ``xytext`` with one of the following strings for
30+
``xycoords`` and ``textcoords`` (default is 'data')
31+
32+
==================== ====================================================
33+
argument coordinate system
34+
==================== ====================================================
35+
'figure points' points from the lower left corner of the figure
36+
'figure pixels' pixels from the lower left corner of the figure
37+
'figure fraction' 0,0 is lower left of figure and 1,1 is upper right
38+
'axes points' points from lower left corner of axes
39+
'axes pixels' pixels from lower left corner of axes
40+
'axes fraction' 0,0 is lower left of axes and 1,1 is upper right
41+
'data' use the axes data coordinate system
42+
==================== ====================================================
43+
44+
For example to place the text coordinates in fractional axes
45+
coordinates, one could do::
46+
47+
ax.annotate('local max', xy=(3, 1), xycoords='data',
48+
xytext=(0.8, 0.95), textcoords='axes fraction',
49+
arrowprops=dict(facecolor='black', shrink=0.05),
50+
horizontalalignment='right', verticalalignment='top',
51+
)
52+
53+
For physical coordinate systems (points or pixels) the origin is the
54+
(bottom, left) of the figure or axes. If the value is negative,
55+
however, the origin is from the (right, top) of the figure or axes,
56+
analogous to negative indexing of sequences.
57+
58+
Optionally, you can specify arrow properties which draws an arrow
59+
from the text to the annotated point by giving a dictionary of arrow
60+
properties in the optional keyword argument ``arrowprops``.
61+
62+
63+
==================== =====================================================
64+
``arrowprops`` key description
65+
==================== =====================================================
66+
width the width of the arrow in points
67+
frac the fraction of the arrow length occupied by the head
68+
headwidth the width of the base of the arrow head in points
69+
shrink move the tip and base some percent away from
70+
the annotated point and text
71+
72+
\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
73+
e.g., ``facecolor``
74+
==================== =====================================================
75+
76+
77+
In the example below, the ``xy`` point is in native coordinates
78+
(``xycoords`` defaults to 'data'). For a polar axes, this is in
79+
(theta, radius) space. The text in this example is placed in the
80+
fractional figure coordinate system. :class:`matplotlib.text.Text`
81+
keyword args like ``horizontalalignment``, ``verticalalignment`` and
82+
``fontsize are passed from the `~matplotlib.Axes.annotate` to the
83+
``Text`` instance
84+
85+
.. plot:: pyplots/annotation_polar.py
86+
:include-source:
87+
88+
For more on all the wild and wonderful things you can do with
89+
annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
90+
and :ref:`pylab_examples-annotation_demo`.
291

3-
****************
4-
Annotating Axes
5-
****************
692

793
Do not proceed unless you already have read :ref:`annotations-tutorial`,
894
:func:`~matplotlib.pyplot.text` and
995
:func:`~matplotlib.pyplot.annotate`!
1096

1197

98+
.. _plotting-guide-annotation:
99+
100+
Advanced Annotation
101+
===================
12102

13103

14104
Annotating with Text with Box
15-
=============================
105+
-----------------------------
16106

17107
Let's start with a simple example.
18108

@@ -70,7 +160,7 @@ of bbox argument when initializing the text instance) ::
70160

71161

72162
Annotating with Arrow
73-
=====================
163+
---------------------
74164

75165
The :func:`~matplotlib.pyplot.annotate` function in the pyplot module
76166
(or annotate method of the Axes class) is used to draw an arrow
@@ -189,7 +279,7 @@ lower-left corner and (1,1) means top-right.
189279

190280

191281
Placing Artist at the anchored location of the Axes
192-
===================================================
282+
---------------------------------------------------
193283

194284
There are class of artist that can be placed at the anchored location
195285
of the Axes. A common example is the legend. This type of artists can
@@ -264,7 +354,7 @@ Note that unlike the legend, the ``bbox_transform`` is set
264354
to IdentityTransform by default.
265355

266356
Using Complex Coordinate with Annotation
267-
========================================
357+
----------------------------------------
268358

269359
The Annotation in matplotlib support several types of coordinate as
270360
described in :ref:`annotations-tutorial`. For an advanced user who wants
@@ -343,7 +433,7 @@ more control, it supports a few other options.
343433
You may take a look at this example :ref:`pylab_examples-annotation_demo3`.
344434

345435
Using ConnectorPatch
346-
====================
436+
--------------------
347437

348438
The ConnectorPatch is like an annotation without a text. While the
349439
annotate function is recommended in most of situation, the
@@ -370,10 +460,10 @@ drawing order to prevent overlap (?) by other axes.
370460

371461

372462
Advanced Topics
373-
***************
463+
~~~~~~~~~~~~~~~
374464

375465
Zoom effect between Axes
376-
========================
466+
------------------------
377467

378468
mpl_toolkits.axes_grid.inset_locator defines some patch classes useful
379469
for interconnect two axes. Understanding the code requires some
@@ -385,7 +475,7 @@ straight forward.
385475

386476

387477
Define Custom BoxStyle
388-
======================
478+
----------------------
389479

390480
You can use a custom box style. The value for the ``boxstyle`` can be a
391481
callable object in following forms.::

‎doc/users/annotations_intro.rst

Lines changed: 0 additions & 87 deletions
This file was deleted.

‎doc/users/beginner.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎doc/users/color_index.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _color-index:
2+
3+
========
4+
Colors
5+
========
6+
7+
.. htmlonly::
8+
9+
:Release: |version|
10+
:Date: |today|
11+
12+
.. toctree::
13+
14+
colors.rst
15+
colormaps.rst
16+
colormapnorms.rst

0 commit comments

Comments
 (0)
0