Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 59cc54d

Browse filesBrowse files
tacaswelltacaswell
committed
DOC: update annotation docstrings
 - Annotation class - OffsetFrom class - Axes.annotate
1 parent 37eb2aa commit 59cc54d
Copy full SHA for 59cc54d

File tree

Expand file treeCollapse file tree

2 files changed

+183
-156
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+183
-156
lines changed

‎lib/matplotlib/axes/_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_axes.py
+1-51Lines changed: 1 addition & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -633,63 +633,13 @@ def text(self, x, y, s, fontdict=None,
633633

634634
@docstring.dedent_interpd
635635
def annotate(self, *args, **kwargs):
636-
"""
637-
Create an annotation: a piece of text referring to a data
638-
point.
639-
640-
Parameters
641-
----------
642-
s : string
643-
label
644-
645-
xy : (x, y)
646-
position of element to annotate. See *xycoords* to control what
647-
coordinate system this value is interpretated in.
648-
649-
xytext : (x, y) , optional, default: None
650-
position of the label `s`. See *textcoords* to control what
651-
coordinate system this value is interpreted in.
652-
653-
xycoords : string, optional, default: "data"
654-
string that indicates what type of coordinates `xy` is. Examples:
655-
"figure points", "figure pixels", "figure fraction", "axes
656-
points", .... See `matplotlib.text.Annotation` for more details.
657-
658-
textcoords : string, optional, default: None
659-
string that indicates what type of coordinates `text` is. Examples:
660-
"figure points", "figure pixels", "figure fraction", "axes
661-
points", .... See `matplotlib.text.Annotation` for more details.
662-
663-
arrowprops : `matplotlib.lines.Line2D` properties, optional
664-
Dictionary of line properties for the arrow that connects
665-
the annotation to the point. If the dictionnary has a key
666-
`arrowstyle`, a `~matplotlib.patches.FancyArrowPatch`
667-
instance is created and drawn. See
668-
`matplotlib.text.Annotation` for more details on valid
669-
options. Default is None.
670-
671-
Returns
672-
-------
673-
a : `~matplotlib.text.Annotation`
674-
675-
676-
Notes
677-
-----
678-
679-
%(Annotation)s
680-
681-
Examples
682-
--------
683-
684-
.. plot:: mpl_examples/pylab_examples/annotation_demo2.py
685-
"""
686636
a = mtext.Annotation(*args, **kwargs)
687637
a.set_transform(mtransforms.IdentityTransform())
688638
if 'clip_on' in kwargs:
689639
a.set_clip_path(self.patch)
690640
self._add_text(a)
691641
return a
692-
642+
annotate.__doc__ = mtext.Annotation.__init__.__doc__
693643
#### Lines and spans
694644

695645
@docstring.dedent_interpd

‎lib/matplotlib/text.py

Copy file name to clipboardExpand all lines: lib/matplotlib/text.py
+182-105Lines changed: 182 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1657,17 +1657,41 @@ def set_figure(self, fig):
16571657

16581658

16591659
class OffsetFrom(object):
1660+
'''Callable helper class for working with `Annotation`
1661+
'''
16601662
def __init__(self, artist, ref_coord, unit="points"):
1663+
'''
1664+
Parameters
1665+
----------
1666+
artist : `Artist`, `BboxBase`, or `Transform`
1667+
The object to compute the offset from.
1668+
1669+
ref_coord : length 2 sequence
1670+
The location to offset relative to (in fractions of
1671+
the `artist` bounding box. If `artist` is a transform,
1672+
offset relative to the transform applied to this value
1673+
1674+
unit : {'points, 'pixels'}
1675+
The screen units to use (pixels or points) for the offset
1676+
input.
1677+
'''
16611678
self._artist = artist
16621679
self._ref_coord = ref_coord
16631680
self.set_unit(unit)
16641681

16651682
def set_unit(self, unit):
1683+
'''The unit for input to the transform used by ``__call__``
1684+
1685+
Parameters
1686+
----------
1687+
unit : {'points', 'pixels'}
1688+
'''
16661689
if unit not in ["points", "pixels"]:
16671690
raise ValueError("'unit' must be one of [ 'points' | 'pixels' ]")
16681691
self._unit = unit
16691692

16701693
def get_unit(self):
1694+
'The unit for input to the transform used by ``__call__``'
16711695
return self._unit
16721696

16731697
def _get_scale(self, renderer):
@@ -1678,6 +1702,19 @@ def _get_scale(self, renderer):
16781702
return renderer.points_to_pixels(1.)
16791703

16801704
def __call__(self, renderer):
1705+
'''Return the offset transform.
1706+
1707+
Parameters
1708+
----------
1709+
renderer : `RendererBase`
1710+
The renderer to use to compute the offset
1711+
1712+
Returns
1713+
-------
1714+
transform : `Transform`
1715+
Maps (x, y) in pixel or point units to screen units
1716+
relative to the given artist.
1717+
'''
16811718
if isinstance(self._artist, Artist):
16821719
bbox = self._artist.get_window_extent(renderer)
16831720
l, b, w, h = bbox.bounds
@@ -1915,16 +1952,6 @@ def draggable(self, state=None, use_blit=False):
19151952

19161953

19171954
class Annotation(Text, _AnnotationBase):
1918-
"""
1919-
A :class:`~matplotlib.text.Text` class to make annotating things
1920-
in the figure, such as :class:`~matplotlib.figure.Figure`,
1921-
:class:`~matplotlib.axes.Axes`,
1922-
:class:`~matplotlib.patches.Rectangle`, etc., easier.
1923-
1924-
Annotate the *x*, *y* point *xy* with text *s* at *x*, *y*
1925-
location *xytext*. (If *xytext* = *None*, defaults to *xy*,
1926-
and if *textcoords* = *None*, defaults to *xycoords*).
1927-
"""
19281955
def __str__(self):
19291956
return "Annotation(%g,%g,%s)" % (self.xy[0],
19301957
self.xy[1],
@@ -1938,101 +1965,151 @@ def __init__(self, s, xy,
19381965
arrowprops=None,
19391966
annotation_clip=None,
19401967
**kwargs):
1941-
"""
1942-
*arrowprops*, if not *None*, is a dictionary of line properties
1943-
(see :class:`matplotlib.lines.Line2D`) for the arrow that connects
1944-
annotation to the point.
1945-
1946-
If the dictionary has a key *arrowstyle*, a
1947-
`~matplotlib.patches.FancyArrowPatch` instance is created with
1948-
the given dictionary and is drawn. Otherwise, a
1949-
`~matplotlib.patches.YAArrow` patch instance is created and
1950-
drawn. Valid keys for `~matplotlib.patches.YAArrow` are:
1951-
1952-
1953-
========= ===========================================================
1954-
Key Description
1955-
========= ===========================================================
1956-
width the width of the arrow in points
1957-
frac the fraction of the arrow length occupied by the head
1958-
headwidth the width of the base of the arrow head in points
1959-
shrink oftentimes it is convenient to have the arrowtip
1960-
and base a bit away from the text and point being
1961-
annotated. If *d* is the distance between the text and
1962-
annotated point, shrink will shorten the arrow so the tip
1963-
and base are shink percent of the distance *d* away from
1964-
the endpoints. i.e., ``shrink=0.05 is 5%%``
1965-
? any key for :class:`matplotlib.patches.polygon`
1966-
========= ===========================================================
1967-
1968-
1969-
Valid keys for `~matplotlib.patches.FancyArrowPatch` are:
1970-
1971-
1972-
=============== ======================================================
1973-
Key Description
1974-
=============== ======================================================
1975-
arrowstyle the arrow style
1976-
connectionstyle the connection style
1977-
relpos default is (0.5, 0.5)
1978-
patchA default is bounding box of the text
1979-
patchB default is None
1980-
shrinkA default is 2 points
1981-
shrinkB default is 2 points
1982-
mutation_scale default is text size (in points)
1983-
mutation_aspect default is 1.
1984-
? any key for :class:`matplotlib.patches.PathPatch`
1985-
=============== ======================================================
1986-
1987-
1988-
*xycoords* and *textcoords* are strings that indicate the
1989-
coordinates of *xy* and *xytext*, and may be one of the
1990-
following values:
1991-
1992-
================= ===================================================
1993-
Property Description
1994-
================= ===================================================
1995-
'figure points' points from the lower left corner of the figure
1996-
'figure pixels' pixels from the lower left corner of the figure
1997-
'figure fraction' 0,0 is lower left of figure and 1,1 is upper right
1998-
'axes points' points from lower left corner of axes
1999-
'axes pixels' pixels from lower left corner of axes
2000-
'axes fraction' 0,0 is lower left of axes and 1,1 is upper right
2001-
'data' use the coordinate system of the object being
2002-
annotated (default)
2003-
'offset points' Specify an offset (in points) from the *xy* value
2004-
2005-
'polar' you can specify *theta*, *r* for the annotation,
2006-
even in cartesian plots. Note that if you
2007-
are using a polar axes, you do not need
2008-
to specify polar for the coordinate
2009-
system since that is the native "data" coordinate
2010-
system.
2011-
================= ===================================================
2012-
2013-
If a 'points' or 'pixels' option is specified, values will be
2014-
added to the bottom-left and if negative, values will be
2015-
subtracted from the top-right. e.g.::
2016-
2017-
# 10 points to the right of the left border of the axes and
2018-
# 5 points below the top border
2019-
xy=(10,-5), xycoords='axes points'
2020-
2021-
You may use an instance of
2022-
:class:`~matplotlib.transforms.Transform` or
2023-
:class:`~matplotlib.artist.Artist`. See
2024-
:ref:`plotting-guide-annotation` for more details.
2025-
2026-
The *annotation_clip* attribute controls the visibility of the
2027-
annotation when it goes outside the axes area. If `True`, the
2028-
annotation will only be drawn when the *xy* is inside the
2029-
axes. If `False`, the annotation will always be drawn
2030-
regardless of its position. The default is `None`, which
2031-
behave as `True` only if *xycoords* is "data".
2032-
2033-
Additional kwargs are `~matplotlib.text.Text` properties:
1968+
"""Annotate the point ``xy`` with text ``s``
1969+
1970+
Additional kwargs are passed to `~matplotlib.text.Text`.
1971+
1972+
Parameters
1973+
----------
1974+
1975+
s : str
1976+
The text of the annotation
1977+
1978+
xy : iterable
1979+
Length 2 sequence specifying the *(x,y)* point to annotate
1980+
1981+
xytext : iterable, optional
1982+
Length 2 sequence specifying the *(x,y)* to place the text
1983+
at. If None, defaults to ``xy``.
1984+
1985+
xycoords : str, Artist, Transform, callable or tuple, optional
1986+
1987+
The coordinate system that ``xy`` is given in.
1988+
1989+
The a `str` the allowed values are:
1990+
1991+
================= ===============================================
1992+
Property Description
1993+
================= ===============================================
1994+
'figure points' points from the lower left of the figure
1995+
'figure pixels' pixels from the lower left of the figure
1996+
'figure fraction' fraction of figure from lower left
1997+
'axes points' points from lower left corner of axes
1998+
'axes pixels' pixels from lower left corner of axes
1999+
'axes fraction' fraction of axes from lower left
2000+
'data' use the coordinate system of the object being
2001+
annotated (default)
2002+
'polar' *(theta,r)* if not native 'data' coordinates
2003+
================= ===============================================
2004+
2005+
If a `~matplotlib.artist.Artist` object is passed in the units are
2006+
fraction if it's bounding box.
2007+
2008+
If a `~matplotlib.transforms.Transform` object is passed in use that
2009+
to transform ``xy`` to screen coordinates
2010+
2011+
If a callable it must take a `~matplotlib.backend_bases.RendererBase`
2012+
object as input and return a `~matplotlib.transforms.Transform` or
2013+
`~matplotlib.transforms.Bbox` object
2014+
2015+
If a `tuple` must be length 2 tuple of str, `Artist`,
2016+
`Transform` or callable objects. The first transform is used for the
2017+
*x* coordinate and the second for *y*.
2018+
2019+
See :ref:`plotting-guide-annotation` for more details.
2020+
2021+
Defaults to ``'data'``
2022+
2023+
textcoords : str, `Artist`, `Transform`, callable or tuple, optional
2024+
The coordinate system that ``xytext`` is given, which maybe different
2025+
than the coordinate system used for ``xy``.
2026+
2027+
All ``xycoords`` values are valid as well as the following strings:
2028+
2029+
================= ===================================================
2030+
Property Description
2031+
================= ===================================================
2032+
'offset points' Specify an offset (in points) from the *xy* value
2033+
'offset pixels' Specify an offset (in pixels) from the *xy* value
2034+
================= ===================================================
2035+
2036+
defaults to the input of ``xycoords``
2037+
2038+
arrowprops : dict, optional
2039+
If not None, properties used to draw a
2040+
`~matplotlib.patches.FancyArrowPatch` arrow between ``xy`` and
2041+
``xytext``.
2042+
2043+
If `arrowprops` does not contain the key ``'arrowstyle'`` the
2044+
allowed keys are:
2045+
2046+
========== =======================================================
2047+
Key Description
2048+
========== =======================================================
2049+
width the width of the arrow in points
2050+
headwidth the width of the base of the arrow head in points
2051+
headlength the length of the arrow head in points
2052+
shrink fraction of total length to 'shrink' from both ends
2053+
? any key for :class:`matplotlib.patches.FancyArrowPatch`
2054+
========== =======================================================
2055+
2056+
If the `arrowprops` contains the key ``'arrowstyle'`` the above keys
2057+
are forbidden. The allowed values of ``'arrowstyle'`` are:
2058+
2059+
============ =============================================
2060+
Name Attrs
2061+
============ =============================================
2062+
``'-'`` None
2063+
``'->'`` head_length=0.4,head_width=0.2
2064+
``'-['`` widthB=1.0,lengthB=0.2,angleB=None
2065+
``'|-|'`` widthA=1.0,widthB=1.0
2066+
``'-|>'`` head_length=0.4,head_width=0.2
2067+
``'<-'`` head_length=0.4,head_width=0.2
2068+
``'<->'`` head_length=0.4,head_width=0.2
2069+
``'<|-'`` head_length=0.4,head_width=0.2
2070+
``'<|-|>'`` head_length=0.4,head_width=0.2
2071+
``'fancy'`` head_length=0.4,head_width=0.4,tail_width=0.4
2072+
``'simple'`` head_length=0.5,head_width=0.5,tail_width=0.2
2073+
``'wedge'`` tail_width=0.3,shrink_factor=0.5
2074+
============ =============================================
2075+
2076+
Valid keys for `~matplotlib.patches.FancyArrowPatch` are:
2077+
2078+
=============== ==================================================
2079+
Key Description
2080+
=============== ==================================================
2081+
arrowstyle the arrow style
2082+
connectionstyle the connection style
2083+
relpos default is (0.5, 0.5)
2084+
patchA default is bounding box of the text
2085+
patchB default is None
2086+
shrinkA default is 2 points
2087+
shrinkB default is 2 points
2088+
mutation_scale default is text size (in points)
2089+
mutation_aspect default is 1.
2090+
? any key for :class:`matplotlib.patches.PathPatch`
2091+
=============== ==================================================
2092+
2093+
Defaults to None
2094+
2095+
annotation_clip : bool, optional
2096+
controls the visibility of the
2097+
annotation when it goes outside the axes area.
2098+
2099+
If `True`, the annotation will only be drawn when the
2100+
``xy`` is inside the axes. If `False`, the annotation will
2101+
always be drawn regardless of its position.
2102+
2103+
The default is `None`, which behave as `True` only if
2104+
*xycoords* is "data".
2105+
2106+
Returns
2107+
-------
2108+
Annotation
2109+
2110+
Notes
2111+
-----
20342112
2035-
%(Text)s
20362113
"""
20372114

20382115
_AnnotationBase.__init__(self,
@@ -2155,7 +2232,7 @@ def _update_position_xytext(self, renderer, xy_pixel):
21552232
frac = d.pop('frac', None)
21562233
if frac is not None:
21572234
warnings.warn(
2158-
"'frac' option in 'arrowstyle' is no longer supported;"
2235+
"'frac' option in 'arrowprops' is no longer supported;"
21592236
" use 'headlength' to set the head length in points.")
21602237
headlength = d.pop('headlength', 12)
21612238

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.