Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 59cc54d

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

File tree

2 files changed

+183
-156
lines changed

2 files changed

+183
-156
lines changed

‎lib/matplotlib/axes/_axes.py

Lines 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

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