8000 improve docstrings for Axes.bar, Axes.barh, Axes.stackplot by timhoffm · Pull Request #10182 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

improve docstrings for Axes.bar, Axes.barh, Axes.stackplot #10182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 9, 2018
Merged

improve docstrings for Axes.bar, Axes.barh, Axes.stackplot #10182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 88 additions & 100 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
10000
Original file line number Diff line number Diff line change
Expand Up @@ -1877,102 +1877,88 @@ def bar(self, *args, **kwargs):
bar(x, height, width, *, align='center', **kwargs)
bar(x, height, width, bottom, *, align='center', **kwargs)

Make a bar plot with rectangles bounded by
The bars are positioned at *x* with the given *align*\ ment. Their
dimensions are given by *width* and *height*. The vertical baseline
is *bottom* (default 0).

.. math::

(x - width/2, x + width/2, bottom, bottom + height)

(left, right, bottom and top edges) by default. *x*,
*height*, *width*, and *bottom* can be either scalars or
sequences.
Each of *x*, *height*, *width*, and *bottom* may either be a scalar
applying to all bars, or it may be a sequence of length N providing a
separate value for each bar.

The *align* and *orientation* kwargs control the interpretation of *x*
and *bottom*

The *align* keyword-only argument controls if *x* is interpreted
as the center or the left edge of the rectangle.

Parameters
----------
x : sequence of scalars
the x coordinates of the bars.

*align* controls if *x* is the bar center (default) or
left edge.
The x coordinates of the bars. See also *align* for the
alignment of the bars to the coordinates.

height : scalar or sequence of scalars
the height(s) of the bars
The height(s) of the bars.

width : scalar or array-like, optional
the width(s) of the bars
default: 0.8
The width(s) of the bars (default: 0.8).

bottom : scalar or array-like, optional
the y coordinate(s) of the bars
default: None
The y coordinate(s) of the bars bases (default: 0).

align : {'center', 'edge'}, optional, default: 'center'
If 'center', interpret the *x* argument as the coordinates
of the centers of the bars. If 'edge', aligns bars by
their left edges
Alignment of the bars to the *x* coordinates:

To align the bars on the right edge pass a negative
*width* and ``align='edge'``
- 'center': Center the base on the *x* positions.
- 'edge': Align the left edges of the bars with the *x* positions.

To align the bars on the right edge pass a negative *width* and
``align='edge'``.

Returns
-------
bars : matplotlib.container.BarContainer
Container with all of the bars + errorbars
`~.BarContainer`
Container with all the bars and optionally errorbars.

Other Parameters
----------------
color : scalar or array-like, optional
the colors of the bar faces
The colors of the bar faces.

edgecolor : scalar or array-like, optional
the colors of the bar edges
The colors of the bar edges.

linewidth : scalar or array-like, optional
width of bar edge(s). If None, use default
linewidth; If 0, don't draw edges.
default: None
Width of the bar edge(s). If 0, don't draw edges.

tick_label : string or array-like, optional
the tick labels of the bars
default: None
The tick labels of the bars.
Default: None (Use default numeric labels.)

xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional
If not *None*, add horizontal / vertical errorbars to the bar tips.
The values are +/- sizes relative to the data:

xerr : scalar or array-like, optional
if not None, will be used to generate errorbar(s) on the bar chart
default: None
- scalar: symmetric +/- values for all bars
- shape(N,): symmetric +/- values for each bar
- shape(2,N): separate + and - values for each bar

yerr : scalar or array-like, optional
if not None, will be used to generate errorbar(s) on the bar chart
default: None
Default: None

ecolor : scalar or array-like, optional
specifies the color of errorbar(s)
default: None
ecolor : scalar or array-like, optional, default: 'black'
The line color of the errorbars.

capsize : scalar, optional
determines the length in points of the error bar caps
default: None, which will take the value from the
The length of the error bar caps in points.
Default: None, which will take the value from the
``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`.

error_kw : dict, optional
dictionary of kwargs to be passed to errorbar method. *ecolor* and
*capsize* may be specified here rather than as independent kwargs.
Dictionary of kwargs to be passed to the `~.Axes.errorbar`
method. Values of *ecolor* or *capsize* defined here take
precedence over the independent kwargs.

log : boolean, optional
If true, sets the axis to be log scale.
default: False
log : bool, optional, default: False
If *True*, set the y-axis to be log scale.

orientation : {'vertical', 'horizontal'}, optional

This is for internal use, please do not directly use this,
call `barh` instead.

The orientation of the bars.
*This is for internal use only.* Please use `barh` for
horizontal bar plots. Default: 'vertical'.

See also
--------
Expand Down Expand Up @@ -2208,83 +2194,85 @@ def barh(self, *args, **kwargs):
bar(y, width, height, *, align='center', **kwargs)
bar(y, width, height, left, *, align='center', **kwargs)

Make a horizontal bar plot with rectangles by default bounded by
The bars are positioned at *y* with the given *align*\ ment. Their
dimensions are given by *width* and *height*. The horizontal baseline
is *left* (default 0).

.. math::

(left, left + width, y - height/2, y + height/2)

(left, right, bottom and top edges) by default. *y*, *width*,
*height*, and *left* can be either scalars or sequences.

The *align* keyword-only argument controls if *y* is interpreted
as the center or the bottom edge of the rectangle.
Each of *y*, *width*, *height*, and *left* may either be a scalar
applying to all bars, or it may be a sequence of length N providing a
separate value for each bar.


Parameters
----------
y : scalar or array-like
the y coordinate(s) of the bars

*align* controls if *y* is the bar center (default)
or bottom edge.
The y coordinates of the bars. See also *align* for the
alignment of the bars to the coordinates.

width : scalar or array-like
the width(s) of the bars
The width(s) of the bars.

height : sequence of scalars, optional, default: 0.8
the heights of the bars
The heights of the bars.

left : sequence of scalars
the x coordinates of the left sides of the bars
The x coordinates of the left sides of the bars (default: 0).

align : {'center', 'edge'}, optional, default: 'center'
If 'center', interpret the *y* argument as the coordinates
of the centers of the bars. If 'edge', aligns bars by
their bottom edges
Alignment of the base to the *y* coordinates*:

To align the bars on the top edge pass a negative
*height* and ``align='edge'``
- 'center': Center the bars on the *y* positions.
- 'edge': Align the bottom edges of the bars with the *y*
positions.

To align the bars on the top edge pass a negative *height* and
``align='edge'``.

Returns
-------
`matplotlib.patches.Rectangle` instances.
`~.BarContainer`
Container with all the bars and optionally errorbars.

Other Parameters
----------------
color : scalar or array-like, optional
the colors of the bars
The colors of the bar faces.

edgecolor : scalar or array-like, optional
the colors of the bar edges
The colors of the bar edges.

linewidth : scalar or array-like, optional, default: None
width of bar edge(s). If None, use default
linewidth; If 0, don't draw edges.
linewidth : scalar or array-like, optional
Width of the bar edge(s). If 0, don't draw edges.

tick_label : string or array-like, optional, default: None
the tick labels of the bars
tick_label : string or array-like, optional
The tick labels of the bars.
Default: None (Use default numeric labels.)

xerr : scalar or array-like, optional, default: None
if not None, will be used to generate errorbar(s) on the bar chart
xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional
If not *None*, add horizontal / vertical errorbars to the bar tips.
The values are +/- sizes relative to the data:

yerr : scalar or array-like, optional, default: None
if not None, will be used to generate errorbar(s) on the bar chart
- scalar: symmetric +/- values for all bars
- shape(N,): symmetric +/- values for each bar
- shape(2,N): separate + and - values for each bar

ecolor : scalar or array-like, optional, default: None
specifies the color of errorbar(s)
Default: None

ecolor : scalar or array-like, optional, default: 'black'
The line color of the errorbars.

capsize : scalar, optional
determines the length in points of the error bar caps
default: None, which will take the value from the
The length of the error bar caps in points.
Default: None, which will take the value from the
``errorbar.capsize`` :data:`rcParam<matplotlib.rcParams>`.

error_kw :
dictionary of kwargs to be passed to errorbar method. `ecolor` and
`capsize` may be specified here rather than as independent kwargs.
error_kw : dict, optional
Dictionary of kwargs to be passed to the `~.Axes.errorbar`
method. Values of *ecolor* or *capsize* defined here take
precedence over the independent kwargs.

log : boolean, optional, default: False
If true, sets the axis to be log scale
log : bool, optional, default: False
If *True*, set the x-axis to be log scale.

See also
--------
Expand Down
32 changes: 14 additions & 18 deletions lib/matplotlib/stackplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,45 +26,41 @@ def stackplot(axes, x, *args, **kwargs):
----------
x : 1d array of dimension N

y : 2d array (dimension MxN), OR sequence of 1d arrays (each dimension 1xN)
y : 2d array (dimension MxN), or sequence of 1d arrays (each dimension 1xN)

The data is assumed to be unstacked. Each of the following
calls is legal::

stackplot(x, y) # where y is MxN
stackplot(x, y1, y2, y3, y4) # where y1, y2, y3, y4, are all 1xNm

baseline : string
One of ``['zero', 'sym', 'wiggle', 'weighted_wiggle']``.

Method used to calculate the baseline. ``'zero'`` is just a
simple stacked plot.
``'sym'`` is symmetric around zero and is sometimes called
'ThemeRiver'.
``'wiggle'`` minimizes the sum of the squared slopes.
``'weighted_wiggle'`` does the same but weights to account for size of
each layer. It is also called 'Streamgraph'-layout. More details
can be found at http://leebyron.com/streamgraph/.
baseline : ['zero' | 'sym' | 'wiggle' | 'weighted_wiggle']
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in the doc for y (just above): OR -> or (lowercase)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

changed.

Method used to calculate the baseline:

- ``'zero'``: Constant zero baseline, i.e. a simple stacked plot.
- ``'sym'``: Symmetric around zero and is sometimes called
'ThemeRiver'.
- ``'wiggle'``: Minimizes the sum of the squared slopes.
- ``'weighted_wiggle'``: Does the same but weights to account for
size of each layer. It is also called 'Streamgraph'-layout. More
details can be found at http://leebyron.com/streamgraph/.

labels : Length N sequence of strings
Labels to assign to each data series.


colors : Length N sequence of colors
A list or tuple of colors. These will be cycled through and used to
colour the stacked areas.

**kwargs :
All other keyword arguments are passed to
`Axes.fill_between`
All other keyword arguments are passed to `Axes.fill_between()`.


Returns
-------
r : list
A list of `PolyCollection`, one for each element in the stacked area
plot.
list of `~.PolyCollection`
A list of `~.PolyCollection` instances, one for each element in the
stacked area plot.
"""

y = np.row_stack(args)
Expand Down
0