8000 Add documentation to axes_grid1.anchored_artists.AnchoredSizeBar · matplotlib/matplotlib@c27633c · GitHub
[go: up one dir, main page]
Skip to content

Commit c27633c

Browse files
sargassargas
committed
Add documentation to axes_grid1.anchored_artists.AnchoredSizeBar
1 parent efb3f5a commit c27633c

File tree

1 file changed

+67
-26
lines changed

1 file changed

+67
-26
lines changed

‎lib/mpl_toolkits/axes_grid1/anchored_artists.py

Lines changed: 67 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
from __future__ import (absolute_import, division, print_function,
22
unicode_literals)
33

4+
from matplotlib import docstring
45
from matplotlib.offsetbox import (AnchoredOffsetbox, AuxTransformBox,
56
DrawingArea, TextArea, VPacker)
67
from matplotlib.patches import Rectangle, Ellipse
@@ -58,69 +59,109 @@ def __init__(self, transform, width, height, angle, loc,
5859

5960

6061
class AnchoredSizeBar(AnchoredOffsetbox):
62+
@docstring.dedent
6163
def __init__(self, transform, size, label, loc,
6264
pad=0.1, borderpad=0.1, sep=2,
6365
frameon=True, size_vertical=0, color='black',
6466
label_top=False, fontproperties=None,
6567
**kwargs):
6668
"""
67-
Draw a horizontal bar with the size in data coordinate of the given axes.
68-
A label will be drawn underneath (center-aligned).
69+
Draw a horizontal scale bar with a center-aligned label underneath.
70+
71+
Parameters
72+
----------
73+
transform : `matplotlib.transforms.Transform`
74+
The transformation object for the coordinate system in use, i.e.,
75+
:attr:`matplotlib.axes.Axes.transData`.
6976
70-
Parameters:
71-
-----------
72-
transform : matplotlib transformation object
7377
size : int or float
74-
horizontal length of the size bar, given in data coordinates
78+
Horizontal length of the size bar, given in coordinates of
79+
*transform*.
80+
7581
label : str
82+
Label to display.
83+
7684
loc : int
85+
Location of this size bar. Valid location codes are::
86+
87+
'upper right' : 1,
88+
'upper left' : 2,
89+
'lower left' : 3,
90+
'lower right' : 4,
91+
'right' : 5,
92+
'center left' : 6,
93+
'center right' : 7,
94+
'lower center' : 8,
95+
'upper center' : 9,
96+
'center' : 10
97+
7798
pad : int or float, optional
78-
in fraction of the legend font size (or prop)
99+
Padding around the label and size bar, in fraction of the font
100+
size. Defaults to 0.1.
101+
79102
borderpad : int or float, optional
80-
in fraction of the legend font size (or prop)
103+
Border padding, in fraction of the font size.
104+
Defaults to 0.1.
105+
81106
sep : int or float, optional
82-
in points
107+
Seperation between the label and the size bar, in points.
108+
Defaults to 2.
109+
83110
frameon : bool, optional
84-
if True, will draw a box around the horizontal bar and label
111+
If True, draw a box around the horizontal bar and label.
112+
Defaults to True.
113+
85114
size_vertical : int or float, optional
86-
vertical length of the size bar, given in data coordinates
115+
Vertical length of the size bar, given in coordinates of
116+
*transform*. Defaults to 0.
117+
87118
color : str, optional
88-
color for the size bar and label
119+
Color for the size bar and label.
120+
Defaults to black.
121+
89122
label_top : bool, optional
90-
if True, the label will be over the rectangle
91-
fontproperties: a matplotlib.font_manager.FontProperties instance, optional
92-
sets the font properties for the label text
123+
If True, the label will be over the size bar.
124+
Defaults to False.
93125
94-
Returns:
95-
--------
96-
AnchoredSizeBar object
126+
fontproperties : `matplotlib.font_manager.FontProperties`, optional
127+
Font properties for the label text.
97128
98-
Example:
129+
**kwargs :
130+
Keyworded arguments to pass to
131+
:class:`matplotlib.offsetbox.AnchoredOffsetbox`.
132+
133+
Notes
134+
-----
135+
If *prop* is passed as a keyworded argument, but *fontproperties* is
136+
not, then *prop* is be assumed to be the intended *fontproperties*.
137+
Using both *prop* and *fontproperties* is not supported.
138+
139+
Examples
99140
--------
100141
>>> import matplotlib.pyplot as plt
101142
>>> import numpy as np
102-
>>> from mpl_toolkits.axes_grid1.anchored_artists import AnchoredSizeBar
143+
>>> from mpl_toolkits.axes_grid1.anchored_artists import \
144+
AnchoredSizeBar
103145
>>> fig, ax = plt.subplots()
104146
>>> ax.imshow(np.random.random((10,10)))
105-
>>> bar = AnchoredSizeBar(ax.transData, 3, '3 units', 4)
147+
>>> bar = AnchoredSizeBar(ax.transData, 3, '3 data units', 4)
106148
>>> ax.add_artist(bar)
107149
>>> fig.show()
108150
109151
Using all the optional parameters
110152
111153
>>> import matplotlib.font_manager as fm
112154
>>> fontprops = fm.FontProperties(size=14, family='monospace')
113-
>>> bar = AnchoredSizeBar(ax.transData, 3, '3 units', 4, pad=0.5, sep=5, borderpad=0.5, frameon=False, size_vertical=0.5, color='white', fontproperties=fontprops)
114-
155+
>>> bar = AnchoredSizeBar(ax.transData, 3, '3 units', 4, pad=0.5, \
156+
sep=5, borderpad=0.5, frameon=False, \
157+
size_vertical=0.5, color='white', \
158+
fontproperties=fontprops)
115159
"""
116160
self.size_bar = AuxTransformBox(transform)
117161
self.size_bar.add_artist(Rectangle((0, 0), size, size_vertical,
118162
fill=True, facecolor=color,
119163
edgecolor=color))
120164

121-
# if fontproperties is None, but `prop` is not, assume that
122-
# prop should be used to set the font properties. This is
123-
# questionable behavior
124165
if fontproperties is None and 'prop' in kwargs:
125166
fontproperties = kwargs.pop('prop')
126167

0 commit comments

Comments
 (0)
0