Skip to content

plt.subplots and plt.figure docstring changes #11382

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
Jun 9, 2018
Merged

plt.subplots and plt.figure docstring changes #11382

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
25 changes: 15 additions & 10 deletions lib/matplotlib/figure.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1254,10 +1254,13 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
"""
Add a set of subplots to this figure.

This utility wrapper makes it convenient to create common layouts of
subplots in a single call.

Parameters
----------
nrows, ncols : int, default: 1
Number of rows/cols of the subplot grid.
nrows, ncols : int, optional, default: 1
Number of rows/columns of the subplot grid.

sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False
Controls sharing of properties among x (`sharex`) or y (`sharey`)
Expand Down Expand Up @@ -1291,25 +1294,27 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
is always a 2D array containing Axes instances, even if it ends
up being 1x1.

subplot_kw : dict, default: {}
subplot_kw : dict, optional
Dict with keywords passed to the
:meth:`~matplotlib.figure.Figure.add_subplot` call used to create
each subplots.
each subplot.

gridspec_kw : dict, default: {}
gridspec_kw : dict, optional
Dict with keywords passed to the
:class:`~matplotlib.gridspec.GridSpec` constructor used to create
`~matplotlib.gridspec.GridSpec` constructor used to create
the grid the subplots are placed on.

Returns
-------
ax : single Axes object or array of Axes objects
The added axes. The dimensions of the resulting array can be
controlled with the squeeze keyword, see above.
ax : Axes object or array of Axes objects.
*ax* can be either a single `~matplotlib.axes.Axes` object or
an array of Axes objects if more than one subplot was created. The
dimensions of the resulting array can be controlled with the
squeeze keyword, see above.

See Also
--------
pyplot.subplots : pyplot API; docstring includes examples.
:func:`.pyplot.subplots`: docstring includes examples.
"""

if isinstance(sharex, bool):
Expand Down
63 changes: 36 additions & 27 deletions lib/matplotlib/pyplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,43 +426,46 @@ def figure(num=None, # autoincrement if None, else integer from 1-N
`num`.

figsize : tuple of integers, optional, default: None
width, height in inches. If not provided, defaults to rc
figure.figsize.
width, height in inches. If not provided, defaults to
:rc:`figure.figsize` = ``[6.4, 4.8]``.

dpi : integer, optional, default: None
resolution of the figure. If not provided, defaults to rc figure.dpi.
resolution of the figure. If not provided, defaults to
:rc:`figure.dpi` = ``100``.

facecolor :
the background color. If not provided, defaults to rc figure.facecolor.
the background color. If not provided, defaults to
:rc:`figure.facecolor` = ``'w'``.

edgecolor :
the border color. If not provided, defaults to rc figure.edgecolor.
the border color. If not provided, defaults to
:rc:`figure.edgecolor` = ``'w'``.

frameon : bool, optional, default: True
If False, suppress drawing the figure frame.

FigureClass : class derived from matplotlib.figure.Figure
Optionally use a custom Figure instance.
FigureClass : subclass of `~matplotlib.figure.Figure`
Optionally use a custom `.Figure` instance.

clear : bool, optional, default: False
If True and the figure already exists, then it is cleared.

Returns
-------
figure : Figure
The Figure instance returned will also be passed to new_figure_manager
in the backends, which allows to hook custom Figure classes into the
pylab interface. Additional kwargs will be passed to the figure init
function.
figure : `~matplotlib.figure.Figure`
The `.Figure` instance returned will also be passed to new_figure_manager
in the backends, which allows to hook custom `.Figure` classes into the
pyplot interface. Additional kwargs will be passed to the `.Figure`
init function.

Notes
-----
If you are creating many figures, make sure you explicitly call "close"
on the figures you are not using, because this will enable pylab
to properly clean up the memory.
If you are creating many figures, make sure you explicitly call
:func:`.pyplot.close` on the figures you are not using, because this will
enable pyplot to properly clean up the memory.

rcParams defines the default values, which can be modified in the
matplotlibrc file.
`~matplotlib.rcParams` defines the default values, which can be modified
in the matplotlibrc file.
"""

if figsize is None:
Expand Down Expand Up @@ -1020,7 +1023,7 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,

squeeze : bool, optional, default: True
- If True, extra dimensions are squeezed out from the returned
array of Axes:
array of `~matplotlib.axes.Axes`:

- if only one subplot is constructed (nrows=ncols=1), the
resulting single Axes object is returned as a scalar.
Expand All @@ -1038,20 +1041,19 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
subplot.

gridspec_kw : dict, optional
Dict with keywords passed to the
:class:`~matplotlib.gridspec.GridSpec` constructor used to create the
grid the subplots are placed on.
Dict with keywords passed to the `~matplotlib.gridspec.GridSpec`
constructor used to create the grid the subplots are placed on.

**fig_kw :
All additional keyword arguments are passed to the :func:`figure` call.
All additional keyword arguments are passed to the
:func:`.pyplot.figure` call.

Returns
-------
fig : :class:`matplotlib.figure.Figure` object
fig : `~matplotlib.figure.Figure`

ax : Axes object or array of Axes objects.

ax can be either a single :class:`matplotlib.axes.Axes` object or an
*ax* can be either a single `~matplotlib.axes.Axes` object or an
array of Axes objects if more than one subplot was created. The
dimensions of the resulting array can be controlled with the squeeze
keyword, see above.
Expand Down Expand Up @@ -1098,10 +1100,17 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,

>>> plt.subplots(2, 2, sharex=True, sharey=True)

Creates figure number 10 with a single subplot
and clears it if it already exists.

>>> fig, ax=plt.subplots(num=10, clear=True)

See Also
--------
figure
subplot
:func:`.pyplot.figure`
:func:`.pyplot.subplot`
:meth:`.Figure.add_subplot`
:meth:`.Figure.subplots`
"""
fig = figure(**fig_kw)
axs = fig.subplots(nrows=nrows, ncols=ncols, sharex=sharex, sharey=sharey,
Expand Down