10000 improve docstrings for Axes.bar, Axes.barh, Axes.stackplot · matplotlib/matplotlib@f3ca536 · GitHub
[go: up one dir, main page]
Skip to content

Commit f3ca536

Browse files
timhoffmtimhoffm
committed
improve docstrings for Axes.bar, Axes.barh, Axes.stackplot
1 parent 2296775 commit f3ca536

File tree

2 files changed

+92
-106
lines changed

2 files changed

+92
-106
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 79 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1883,96 +1883,83 @@ def bar(self, *args, **kwargs):
18831883
18841884
(x - width/2, x + width/2, bottom, bottom + height)
18851885
1886-
(left, right, bottom and top edges) by default. *x*,
1887-
*height*, *width*, and *bottom* can be either scalars or
1888-
sequences.
1886+
(left, right, bottom and top edges) by default. *x*, *height*,
1887+
*width*, and *bottom* may be either scalars or sequences of length N.
18891888
1890-
The *align* and *orientation* kwargs control the interpretation of *x*
1891-
and *bottom*
1892-
1893-
The *align* keyword-only argument controls if *x* is interpreted
1894-
as the center or the left edge of the rectangle.
18951889
18961890
Parameters
18971891
----------
18981892
x : sequence of scalars
1899-
the x coordinates of the bars.
1900-
1901-
*align* controls if *x* is the bar center (default) or
1902-
left edge.
1893+
The x coordinates of the bars. See also *align* for the
1894+
alignment of the bars to the coordinates.
19031895
19041896
height : scalar or sequence of scalars
1905-
the height(s) of the bars
1897+
The height(s) of the bars.
19061898
19071899
width : scalar or array-like, optional
1908-
the width(s) of the bars
1909-
default: 0.8
1900+
The width(s) of the bars (default: 0.8).
19101901
19111902
bottom : scalar or array-like, optional
1912-
the y coordinate(s) of the bars
1913-
default: None
1903+
The y coordinate(s) of the bars bases (default: 0).
19141904
19151905
align : {'center', 'edge'}, optional, default: 'center'
1916-
If 'center', interpret the *x* argument as the coordinates
1917-
of the centers of the bars. If 'edge', aligns bars by
1918-
their left edges
1906+
Alignment of the bars to the *x* coordinates:
19191907
1920-
To align the bars on the right edge pass a negative
1921-
*width* and ``align='edge'``
1908+
- 'center': Center the base on the *x* positions.
1909+
- 'edge': Align the left edges of the bars with the *x* positions.
1910+
1911+
To align the bars on the right edge pass a negative *width* and
1912+
``align='edge'``.
19221913
19231914
Returns
19241915
-------
1925-
bars : matplotlib.container.BarContainer
1926-
Container with all of the bars + errorbars
1916+
`matplotlib.container.BarContainer`
1917+
Container with all the bars and optionally errorbars.
19271918
19281919
Other Parameters
19291920
----------------
19301921
color : scalar or array-like, optional
1931-
the colors of the bar faces
1922+
The colors of the bar faces.
19321923
19331924
edgecolor : scalar or array-like, optional
1934-
the colors of the bar edges
1925+
The colors of the bar edges.
19351926
19361927
linewidth : scalar or array-like, optional
1937-
width of bar edge(s). If None, use default
1938-
linewidth; If 0, don't draw edges.
1939-
default: None
1928+
Width of the bar edge(s). If 0, don't draw edges.
19401929
19411930
tick_label : string or array-like, optional
1942-
the tick labels of the bars
1943-
default: None
1931+
The tick labels of the bars.
1932+
Default: None (Use default numeric labels.)
1933+
1934+
xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional
1935+
If not *None*, add horizontal / vertical errorbars to the bar tips.
1936+
The values are +/- sizes relative to the data:
19441937
1945-
xerr : scalar or array-like, optional
1946-
if not None, will be used to generate errorbar(s) on the bar chart
1947-
default: None
1938+
- scalar: symmetric +/- values for all bars
1939+
- shape(N,): symmetric +/- values for each bar
1940+
- shape(2,N): separate + and - values for each bar
19481941
1949-
yerr : scalar or array-like, optional
1950-
if not None, will be used to generate errorbar(s) on the bar chart
1951-
default: None
1942+
Default: None
19521943
1953-
ecolor : scalar or array-like, optional
1954-
specifies the color of errorbar(s)
1955-
default: None
1944+
ecolor : scalar or array-like, optional, default: 'black'
1945+
The line color of the errorbars.
19561946
19571947
capsize : scalar, optional
1958-
determines the length in points of the error bar caps
1959-
default: None, which will take the value from the
1948+
The length of the error bar caps in points.
1949+
Default: None, which will take the value from the
19601950
``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`.
19611951
19621952
error_kw : dict, optional
1963-
dictionary of kwargs to be passed to errorbar method. *ecolor* and
1964-
*capsize* may be specified here rather than as independent kwargs.
1953+
Dictionary of kwargs to be passed to the `~.Axes.errorbar()`
1954+
method. Values of *ecolor* or *capsize* defined here take
1955+
precedence over the independent kwargs.
19651956
1966-
log : boolean, optional
1967-
If true, sets the axis to be log scale.
1968-
default: False
1957+
log : bool, optional, default: False
1958+
If *True*, set the y-axis to be log scale.
19691959
19701960
orientation : {'vertical', 'horizontal'}, optional
1971-
1972-
This is for internal use, please do not directly use this,
1973-
call `barh` instead.
1974-
1975-
The orientation of the bars.
1961+
*This is for internal use only.* Please use `barh()` for
1962+
horizontal bar plots. Default: 'vertical'.
19761963
19771964
See also
19781965
--------
@@ -2215,76 +2202,79 @@ def barh(self, *args, **kwargs):
22152202
(left, left + width, y - height/2, y + height/2)
22162203
22172204
(left, right, bottom and top edges) by default. *y*, *width*,
2218-
*height*, and *left* can be either scalars or sequences.
2219-
2220-
The *align* keyword-only argument controls if *y* is interpreted
2221-
as the center or the bottom edge of the rectangle.
2205+
*height*, and *left* can be either scalars or sequences of length N.
22222206
22232207
22242208
Parameters
22252209
----------
22262210
y : scalar or array-like
2227-
the y coordinate(s) of the bars
2228-
2229-
*align* controls if *y* is the bar center (default)
2230-
or bottom edge.
2211+
The y coordinates of the bars. See also *align* for the
2212+
alignment of the bars to the coordinates.
22312213
22322214
width : scalar or array-like
2233-
the width(s) of the bars
2215+
The width(s) of the bars.
22342216
22352217
height : sequence of scalars, optional, default: 0.8
2236-
the heights of the bars
2218+
The heights of the bars.
22372219
22382220
left : sequence of scalars
2239-
the x coordinates of the left sides of the bars
2221+
The x coordinates of the left sides of the bars (default: 0).
22402222
22412223
align : {'center', 'edge'}, optional, default: 'center'
2242-
If 'center', interpret the *y* argument as the coordinates
2243-
of the centers of the bars. If 'edge', aligns bars by
2244-
their bottom edges
2224+
Alignment of the base to the *y* coordinates*:
22452225
2246-
To align the bars on the top edge pass a negative
2247-
*height* and ``align='edge'``
2226+
- 'center': Center the bars on the *y* positions.
2227+
- 'edge': Align the bottom edges of the bars with the *y*
2228+
positions.
2229+
2230+
To align the bars on the top edge pass a negative *height* and
2231+
``align='edge'``.
22482232
22492233
Returns
22502234
-------
2251-
`matplotlib.patches.Rectangle` instances.
2235+
`matplotlib.container.BarContainer`
2236+
Container with all the bars and optionally errorbars.
22522237
22532238
Other Parameters
22542239
----------------
22552240
color : scalar or array-like, optional
2256-
the colors of the bars
2241+
The colors of the bar faces.
22572242
22582243
edgecolor : scalar or array-like, optional
2259-
the colors of the bar edges
2244+
The colors of the bar edges.
22602245
2261-
linewidth : scalar or array-like, optional, default: None
2262-
width of bar edge(s). If None, use default
2263-
linewidth; If 0, don't draw edges.
2246+
linewidth : scalar or array-like, optional
2247+
Width of the bar edge(s). If 0, don't draw edges.
22642248
2265-
tick_label : string or array-like, optional, default: None
2266-
the tick labels of the bars
2249+
tick_label : string or array-like, optional
2250+
The tick labels of the bars.
2251+
Default: None (Use default numeric labels.)
2252+
2253+
xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional
2254+ 1C6A
If not *None*, add horizontal / vertical errorbars to the bar tips.
2255+
The values are +/- sizes relative to the data:
22672256
2268-
xerr : scalar or array-like, optional, default: None
2269-
if not None, will be used to generate errorbar(s) on the bar chart
2257+
- scalar: symmetric +/- values for all bars
2258+
- shape(N,): symmetric +/- values for each bar
2259+
- shape(2,N): separate + and - values for each bar
22702260
2271-
yerr : scalar or array-like, optional, default: None
2272-
if not None, will be used to generate errorbar(s) on the bar chart
2261+
Default: None
22732262
2274-
ecolor : scalar or array-like, optional, default: None
2275-
specifies the color of errorbar(s)
2263+
ecolor : scalar or array-like, optional, default: 'black'
2264+
The line color of the errorbars.
22762265
22772266
capsize : scalar, optional
2278-
determines the length in points of the error bar caps
2279-
default: None, which will take the value from the
2267+
The length of the error bar caps in points.
2268+
Default: None, which will take the value from the
22802269
``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`.
22812270
2282-
error_kw :
2283-
dictionary of kwargs to be passed to errorbar method. `ecolor` and
2284-
`capsize` may be specified here rather than as independent kwargs.
2271+
error_kw : dict, optional
2272+
Dictionary of kwargs to be passed to the `~.Axes.errorbar()`
2273+
method. Values of *ecolor* or *capsize* defined here take
2274+
precedence over the independent kwargs.
22852275
2286-
log : boolean, optional, default: False
2287-
If true, sets the axis to be log scale
2276+
log : bool, optional, default: False
2277+
If *True*, set the x-axis to be log scale.
22882278
22892279
See also
22902280
--------

‎lib/matplotlib/stackplot.py

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -34,37 +34,33 @@ def stackplot(axes, x, *args, **kwargs):
3434
stackplot(x, y) # where y is MxN
3535
stackplot(x, y1, y2, y3, y4) # where y1, y2, y3, y4, are all 1xNm
3636
37-
baseline : string
38-
One of ``['zero', 'sym', 'wiggle', 'weighted_wiggle']``.
39-
40-
Method used to calculate the baseline. ``'zero'`` is just a
41-
simple stacked plot.
42-
``'sym'`` is symmetric around zero and is sometimes called
43-
'ThemeRiver'.
44-
``'wiggle'`` minimizes the sum of the squared slopes.
45-
``'weighted_wiggle'`` does the same but weights to account for size of
46-
each layer. It is also called 'Streamgraph'-layout. More details
47-
can be found at http://leebyron.com/streamgraph/.
37+
baseline : ['zero' | 'sym' | 'wiggle' | 'weighted_wiggle']
38+
Method used to calculate the baseline:
4839
40+
- ``'zero'``: Constant zero baseline, i.e. a simple stacked plot.
41+
- ``'sym'``: Symmetric around zero and is sometimes called
42+
'ThemeRiver'.
43+
- ``'wiggle'``: Minimizes the sum of the squared slopes.
44+
- ``'weighted_wiggle'``: Does the same but weights to account for
45+
size of each layer. It is also called 'Streamgraph'-layout. More
46+
details can be found at http://leebyron.com/streamgraph/.
4947
5048
labels : Length N sequence of strings
5149
Labels to assign to each data series.
5250
53-
5451
colors : Length N sequence of colors
5552
A list or tuple of colors. These will be cycled through and used to
5653
colour the stacked areas.
5754
5855
**kwargs :
59-
All other keyword arguments are passed to
60-
`Axes.fill_between`
56+
All other keyword arguments are passed to `Axes.fill_between()`.
6157
6258
6359
Returns
6460
-------
65-
r : list
66-
A list of `PolyCollection`, one for each element in the stacked area
67-
plot.
61+
list of `~matplotlib.collections.PolyCollection`
62+
A list of `~matplotlib.collections.PolyCollection` instances, one for
63+
each element in the stacked area plot.
6864
"""
6965

7066
y = np.row_stack(args)

0 commit comments

Comments
 (0)
0