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

Skip to content

Commit 0bcc13f

Browse files
jklymakjklymak
authored
Merge pull request #10182 from timhoffm/axes-doc-minor-changes
improve docstrings for Axes.bar, Axes.barh, Axes.stackplot
2 parents a2b96bc + 40a0dd0 commit 0bcc13f

File tree

2 files changed

+102
-118
lines changed

2 files changed

+102
-118
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 88 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1877,102 +1877,88 @@ def bar(self, *args, **kwargs):
18771877
bar(x, height, width, *, align='center', **kwargs)
18781878
bar(x, height, width, bottom, *, align='center', **kwargs)
18791879
1880-
Make a bar plot with rectangles bounded by
1880+
The bars are positioned at *x* with the given *align*\ ment. Their
1881+
dimensions are given by *width* and *height*. The vertical baseline
1882+
is *bottom* (default 0).
18811883
1882-
.. math::
1883-
1884-
(x - width/2, x + width/2, bottom, bottom + height)
1885-
1886-
(left, right, bottom and top edges) by default. *x*,
1887-
*height*, *width*, and *bottom* can be either scalars or
1888-
sequences.
1884+
Each of *x*, *height*, *width*, and *bottom* may either be a scalar
1885+
applying to all bars, or it may be a sequence of length N providing a
1886+
separate value for each bar.
18891887
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.
18951888
18961889
Parameters
18971890
----------
18981891
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.
1892+
The x coordinates of the bars. See also *align* for the
1893+
alignment of the bars to the coordinates.
19031894
19041895
height : scalar or sequence of scalars
1905-
the height(s) of the bars
1896+
The height(s) of the bars.
19061897
19071898
width : scalar or array-like, optional
1908-
the width(s) of the bars
1909-
default: 0.8
1899+
The width(s) of the bars (default: 0.8).
19101900
19111901
bottom : scalar or array-like, optional
1912-
the y coordinate(s) of the bars
1913-
default: None
1902+
The y coordinate(s) of the bars bases (default: 0).
19141903
19151904
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
1905+
Alignment of the bars to the *x* coordinates:
19191906
1920-
To align the bars on the right edge pass a negative
1921-
*width* and ``align='edge'``
1907+
- 'center': Center the base on the *x* positions.
1908+
- 'edge': Align the left edges of the bars with the *x* positions.
1909+
1910+
To align the bars on the right edge pass a negative *width* and
1911+
``align='edge'``.
19221912
19231913
Returns
19241914
-------
1925-
bars : matplotlib.container.BarContainer
1926-
Container with all of the bars + errorbars
1915+
`~.BarContainer`
1916+
Container with all the bars and optionally errorbars.
19271917
19281918
Other Parameters
19291919
----------------
19301920
color : scalar or array-like, optional
1931-
the colors of the bar faces
1921+
The colors of the bar faces.
19321922
19331923
edgecolor : scalar or array-like, optional
1934-
the colors of the bar edges
1924+
The colors of the bar edges.
19351925
19361926
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
1927+
Width of the bar edge(s). If 0, don't draw edges.
19401928
19411929
tick_label : string or array-like, optional
1942-
the tick labels of the bars
1943-
default: None
1930+
The tick labels of the bars.
1931+
Default: None (Use default numeric labels.)
1932+
1933+
xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional
1934+
If not *None*, add horizontal / vertical errorbars to the bar tips.
1935+
The values are +/- sizes relative to the data:
19441936
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
1937+
- scalar: symmetric +/- values for all bars
1938+
- shape(N,): symmetric +/- values for each bar
1939+
- shape(2,N): separate + and - values for each bar
19481940
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
1941+
Default: None
19521942
1953-
ecolor : scalar or array-like, optional
1954-
specifies the color of errorbar(s)
1955-
default: None
1943+
ecolor : scalar or array-like, optional, default: 'black'
1944+
The line color of the errorbars.
19561945
19571946
capsize : scalar, optional
1958-
determines the length in points of the error bar caps
1959-
default: None, which will take the value from the
1947+
The length of the error bar caps in points.
1948+
Default: None, which will take the value from the
19601949
``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`.
19611950
19621951
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.
1952+
Dictionary of kwargs to be passed to the `~.Axes.errorbar`
1953+
method. Values of *ecolor* or *capsize* defined here take
1954+
precedence over the independent kwargs.
19651955
1966-
log : boolean, optional
1967-
If true, sets the axis to be log scale.
1968-
default: False
1956+
log : bool, optional, default: False
1957+
If *True*, set the y-axis to be log scale.
19691958
19701959
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.
1960+
*This is for internal use only.* Please use `barh` for
1961+
horizontal bar plots. Default: 'vertical'.
19761962
19771963
See also
19781964
--------
@@ -2208,83 +2194,85 @@ def barh(self, *args, **kwargs):
22082194
bar(y, width, height, *, align='center', **kwargs)
22092195
bar(y, width, height, left, *, align='center', **kwargs)
22102196
2211-
Make a horizontal bar plot with rectangles by default bounded by
2197+
The bars are positioned at *y* with the given *align*\ ment. Their
2198+
dimensions are given by *width* and *height*. The horizontal baseline
2199+
is *left* (default 0).
22122200
2213-
.. math::
2214-
2215-
(left, left + width, y - height/2, y + height/2)
2216-
2217-
(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.
2201+
Each of *y*, *width*, *height*, and *left* may either be a scalar
2202+
applying to all bars, or it may be a sequence of length N providing a
2203+
separate value for each bar.
22222204
22232205
22242206
Parameters
22252207
----------
22262208
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.
2209+
The y coordinates of the bars. See also *align* for the
2210+
alignment of the bars to the coordinates.
22312211
22322212
width : scalar or array-like
2233-
the width(s) of the bars
2213+
The width(s) of the bars.
22342214
22352215
height : sequence of scalars, optional, default: 0.8
2236-
the heights of the bars
2216+
The heights of the bars.
22372217
22382218
left : sequence of scalars
2239-
the x coordinates of the left sides of the bars
2219+
The x coordinates of the left sides of the bars (default: 0).
22402220
22412221
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
2222+
Alignment of the base to the *y* coordinates*:
22452223
2246-
To align the bars on the top edge pass a negative
2247-
*height* and ``align='edge'``
2224+
- 'center': Center the bars on the *y* positions.
2225+
- 'edge': Align the bottom edges of the bars with the *y*
2226+
positions.
2227+
2228+
To align the bars on the top edge pass a negative *height* and
2229+
``align='edge'``.
22482230
22492231
Returns
22502232
-------
2251-
`matplotlib.patches.Rectangle` instances.
2233+
`~.BarContainer`
2234+
Container with all the bars and optionally errorbars.
22522235
22532236
Other Parameters
22542237
----------------
22552238
color : scalar or array-like, optional
2256-
the colors of the bars
2239+
The colors of the bar faces.
22572240
22582241
edgecolor : scalar or array-like, optional
2259-
the colors of the bar edges
2242+
The colors of the bar edges.
22602243
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.
2244+
linewidth : scalar or array-like, optional
2245+
Width of the bar edge(s). If 0, don't draw edges.
22642246
2265-
tick_label : string or array-like, optional, default: None
2266-
the tick labels of the bars
2247+
tick_label : string or array-like, optional
2248+
The tick labels of the bars.
2249+
Default: None (Use default numeric labels.)
22672250
2268-
xerr : scalar or array-like, optional, default: None
2269-
if not None, will be used to generate errorbar(s) on the bar chart
2251+
xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional
2252+
If not *None*, add horizontal / vertical errorbars to the bar tips.
2253+
The values are +/- sizes relative to the data:
22702254
2271-
yerr : scalar or array-like, optional, default: None
2272-
if not None, will be used to generate errorbar(s) on the bar chart
2255+
- scalar: symmetric +/- values for all bars
2256+
- shape(N,): symmetric +/- values for each bar
2257+
- shape(2,N): separate + and - values for each bar
22732258
2274-
ecolor : scalar or array-like, optional, default: None
2275-
specifies the color of errorbar(s)
2259+
Default: None
2260+
2261+
ecolor : scalar or array-like, optional, default: 'black'
2262+
The line color of the errorbars.
22762263
22772264
capsize : scalar, optional
2278-
determines the length in points of the error bar caps
2279-
default: None, which will take the value from the
2265+
The length of the error bar caps in points.
2266+
Default: None, which will take the value from the
22802267
``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`.
22812268
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.
2269+
error_kw : dict, optional
2270+
Dictionary of kwargs to be passed to the `~.Axes.errorbar`
2271+
method. Values of *ecolor* or *capsize* defined here take
2272+
precedence over the independent kwargs.
22852273
2286-
log : boolean, optional, default: False
2287-
If true, sets the axis to be log scale
2274+
log : bool, optional, default: False
2275+
If *True*, set the x-axis to be log scale.
22882276
22892277
See also
22902278
--------

‎lib/matplotlib/stackplot.py

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -26,45 +26,41 @@ def stackplot(axes, x, *args, **kwargs):
2626
----------
2727
x : 1d array of dimension N
2828
29-
y : 2d array (dimension MxN), OR sequence of 1d arrays (each dimension 1xN)
29+
y : 2d array (dimension MxN), or sequence of 1d arrays (each dimension 1xN)
3030
3131
The data is assumed to be unstacked. Each of the following
3232
calls is legal::
3333
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 `~.PolyCollection`
62+
A list of `~.PolyCollection` instances, one for each element in the
63+
stacked area plot.
6864
"""
6965

7066
y = np.row_stack(args)

0 commit comments

Comments
 (0)