8000 Merge pull request #7232 from NelleV/7230_subplots_docstring_example · matplotlib/matplotlib@6ad368b · GitHub
[go: up one dir, main page]
Skip to content

Commit 6ad368b

Browse files
tacaswelltacaswell
authored
Merge pull request #7232 from NelleV/7230_subplots_docstring_example
DOC: improved subplots' docstring
2 parents cb0d0e5 + cf09849 commit 6ad368b

File tree

2 files changed

+119
-123
lines changed

2 files changed

+119
-123
lines changed

‎lib/matplotlib/figure.py

Lines changed: 29 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1025,48 +1025,40 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
10251025
10261026
Parameters
10271027
----------
1028-
nrows : int, default: 1
1029-
Number of rows of the subplot grid.
1028+
nrows, ncols : int, default: 1
1029+
Number of rows/cols of the subplot grid.
10301030
1031-
ncols : int, default: 1
1032-
Number of columns of the subplot grid.
1031+
sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False
1032+
Controls sharing of properties among x (`sharex`) or y (`sharey`)
1033+
axes:
10331034
1034-
sharex : {"none", "all", "row", "col"} or bool, default: False
1035-
If *False*, or "none", each subplot has its own X axis.
1035+
- True or 'all': x- or y-axis will be shared among all
1036+
subplots.
1037+
- False or 'none': each subplot x- or y-axis will be
1038+
independent.
1039+
- 'row': each subplot row will share an x- or y-axis.
1040+
- 'col': each subplot column will share an x- or y-axis.
10361041
1037-
If *True*, or "all", all subplots will share an X axis, and the x
1038-
tick labels on all but the last row of plots will be invisible.
1039-
1040-
If "col", each subplot column will share an X axis, and the x
1041-
tick labels on all but the last row of plots will be invisible.
1042-
1043-
If "row", each subplot row will share an X axis.
1044-
1045-
sharey : {"none", "all", "row", "col"} or bool, default: False
1046-
If *False*, or "none", each subplot has its own Y axis.
1047-
1048-
If *True*, or "all", all subplots will share an Y axis, and the y
1049-
tick labels on all but the first column of plots will be invisible.
1050-
1051-
If "row", each subplot row will share an Y axis, and the y tick
1052-
labels on all but the first column of plots will be invisible.
1053-
1054-
If "col", each subplot column will share an Y axis.
1042+
When subplots have a shared x-axis along a column, only the x tick
1043+
labels of the bottom subplot are visible. Similarly, when
1044+
subplots have a shared y-axis along a row, only the y tick labels
1045+
of the first column subplot are visible.
10551046
10561047
squeeze : bool, default: True
1057-
If *True*, extra dimensions are squeezed out from the returned axes
1058-
array:
1059-
1060-
- if only one subplot is constructed (nrows=ncols=1), the resulting
1061-
single Axes object is returned as a scalar.
1062-
1063-
- for Nx1 or 1xN subplots, the returned object is a 1-d numpy
1064-
object array of Axes objects are returned as numpy 1-d arrays.
1065-
1066-
- for NxM subplots with N>1 and M>1 are returned as a 2d array.
1067-
1068-
If *False*, no squeezing at all is done: the returned object is
1069-
always a 2-d array of Axes instances, even if it ends up being 1x1.
1048+
- If True, extra dimensions are squeezed out from the returned
1049+
axis object:
1050+
1051+
- if only one subplot is constructed (nrows=ncols=1), the
1052+
resulting single Axes object is returned as a scalar.
1053+
- for Nx1 or 1xN subplots, the returned object is a 1D numpy
1054+
object array of Axes objects are returned as numpy 1D
1055+
arrays.
1056+
- for NxM, subplots with N>1 and M>1 are returned as a 2D
1057+
arrays.
1058+
1059+
- If False, no squeezing at all is done: the returned Axes object
1060+
is always a 2D array containing Axes instances, even if it ends
1061+
up being 1x1.
10701062
10711063
subplot_kw : dict, default: {}
10721064
Dict with keywords passed to the

‎lib/matplotlib/pyplot.py

Lines changed: 90 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1038,115 +1038,119 @@ def subplot(*args, **kwargs):
10381038

10391039

10401040
def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
1041-
subplot_kw=None, gridspec_kw=None, **fig_kw):
1041+
subplot_kw=None, gridspec_kw=None, **fig_kw):
10421042
"""
1043-
Create a figure with a set of subplots already made.
1043+
Create a figure and a set of subplots
10441044
10451045
This utility wrapper makes it convenient to create common layouts of
10461046
subplots, including the enclosing figure object, in a single call.
10471047
1048-
Keyword arguments:
1049-
1050-
*nrows* : int
1051-
Number of rows of the subplot grid. Defaults to 1.
1052-
1053-
*ncols* : int
1054-
Number of columns of the subplot grid. Defaults to 1.
1055-
1056-
*sharex* : string or bool
1057-
If *True*, the X axis will be shared amongst all subplots. If
1058-
*True* and you have multiple rows, the x tick labels on all but
1059-
the last row of plots will have visible set to *False*
1060-
If a string must be one of "row", "col", "all", or "none".
1061-
"all" has the same effect as *True*, "none" has the same effect
1062-
as *False*.
1063-
If "row", each subplot row will share a X axis.
1064-
If "col", each subplot column will share a X axis and the x tick
1065-
labels on all but the last row will have visible set to *False*.
1066-
1067-
*sharey* : string or bool
1068-
If *True*, the Y axis will be shared amongst all subplots. If
1069-
*True* and you have multiple columns, the y tick labels on all but
1070-
the first column of plots will have visible set to *False*
1071-
If a string must be one of "row", "col", "all", or "none".
1072-
"all" has the same effect as *True*, "none" has the same effect
1073-
as *False*.
1074-
If "row", each subplot row will share a Y axis and the y tick
1075-
labels on all but the first column will have visible set to *False*.
1076-
If "col", each subplot column will share a Y axis.
1077-
1078-
*squeeze* : bool
1079-
If *True*, extra dimensions are squeezed out from the
1080-
returned axis object:
1081-
1082-
- if only one subplot is constructed (nrows=ncols=1), the
1083-
resulting single Axis object is returned as a scalar.
1084-
1085-
- for Nx1 or 1xN subplots, the returned object is a 1-d numpy
1086-
object array of Axis objects are returned as numpy 1-d
1087-
arrays.
1088-
1089-
- for NxM subplots with N>1 and M>1 are returned as a 2d
1090-
array.
1091-
1092-
If *False*, no squeezing at all is done: the returned axis
1093-
object is always a 2-d array containing Axis instances, even if it
1094-
ends up being 1x1.
1095-
1096-
*subplot_kw* : dict
1048+
Parameters
1049+
----------
1050+
nrows, ncols : int, optional, default: 1
1051+
Number of rows/columns of the subplot grid.
1052+
1053+
sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False
1054+
Controls sharing of properties among x (`sharex`) or y (`sharey`)
1055+
axes:
1056+
1057+
- True or 'all': x- or y-axis will be shared among all
1058+
subplots.
1059+
- False or 'none': each subplot x- or y-axis will be
1060+
independent.
1061+
- 'row': each subplot row will share an x- or y-axis.
1062+
- 'col': each subplot column will share an x- or y-axis.
1063+
1064+
When subplots have a shared x-axis along a column, only the x tick
1065+
labels of the bottom subplot are visible. Similarly, when subplots
1066+
have a shared y-axis along a row, only the y tick labels of the first
1067+
column subplot are visible.
1068+
1069+
squeeze : bool, optional, default: True
1070+
- If True, extra dimensions are squeezed out from the returned Axes
1071+
object:
1072+
1073+
- if only one subplot is constructed (nrows=ncols=1), the
1074+
resulting single Axes object is returned as a scalar.
1075+
- for Nx1 or 1xN subplots, the returned object is a 1D numpy
1076+
object array of Axes objects are returned as numpy 1D arrays.
1077+
- for NxM, subplots with N>1 and M>1 are returned as a 2D arrays.
1078+
1079+
- If False, no squeezing at all is done: the returned Axes object is
1080+
always a 2D array containing Axes instances, even if it ends up
1081+
being 1x1.
1082+
1083+
subplot_kw : dict, optional
10971084
Dict with keywords passed to the
1098-
:meth:`~matplotlib.figure.Figure.add_subplot` call used to
1099-
create each subplots.
1085+
:meth:`~matplotlib.figure.Figure.add_subplot` call used to create each
1086+
subplot.
11001087
1101-
*gridspec_kw* : dict
1088+
gridspec_kw : dict, optional
11021089
Dict with keywords passed to the
1103-
:class:`~matplotlib.gridspec.GridSpec` constructor used to create
1104-
the grid the subplots are placed on.
1090+
:class:`~matplotlib.gridspec.GridSpec` constructor used to create the
1091+
grid the subplots are placed on.
11051092
1106-
*fig_kw* : dict
1093+
fig_kw : dict, optional
11071094
Dict with keywords passed to the :func:`figure` call. Note that all
11081095
keywords not recognized above will be automatically included here.
11091096
1110-
Returns:
1111-
1112-
fig, ax : tuple
1097+
Returns
1098+
-------
1099+
fig : :class:`matplotlib.figure.Figure` object
11131100
1114-
- *fig* is the :class:`matplotlib.figure.Figure` object
1101+
ax : Axes object or array of Axes objects.
11151102
1116-
- *ax* can be either a single axis object or an array of axis
1117-
objects if more than one subplot was created. The dimensions
1118-
of the resulting array can be controlled with the squeeze
1103+
ax can be either a single :class:`matplotlib.axes.Axes` object or an
1104+
array of Axes objects if more than one subplot was created. The
1105+
dimensions of the resulting array can be controlled with the squeeze
11191106
keyword, see above.
11201107
1121-
Examples::
1108+
Examples
1109+
--------
1110+
First create some toy data:
1111+
1112+
>>> x = np.linspace(0, 2*np.pi, 400)
1113+
>>> y = np.sin(x**2)
11221114
1123-
x = np.linspace(0, 2*np.pi, 400)
1124-
y = np.sin(x**2)
1115+
Creates just a figure and only one subplot
11251116
1126-
# Just a figure and one subplot
1127-
f, ax = plt.subplots()
1128-
ax.plot(x, y)
1129-
ax.set_title('Simple plot')
1117+
>>> fig, ax = plt.subplots()
1118+
>>> ax.plot(x, y)
1119+
>>> ax.set_title('Simple plot')
11301120
1131-
# Two subplots, unpack the output array immediately
1132-
f, (ax1, ax2) = plt.subplots(1, 2, sharey=True)
1133-
ax1.plot(x, y)
1134-
ax1.set_title('Sharing Y axis')
1135-
ax2.scatter(x, y)
1121+
Creates two subplots and unpacks the output array immediately
11361122
1137-
# Four polar axes
1138-
plt.subplots(2, 2, subplot_kw=dict(polar=True))
1123+
>>> f, (ax1, ax2) = plt.subplots(1, 2, sharey=True)
1124+
>>> ax1.plot(x, y)
1125+
>>> ax1.set_title('Sharing Y axis')
1126+
>>> ax2.scatter(x, y)
11391127
1140-
# Share a X axis with each column of subplots
1141-
plt.subplots(2, 2, sharex='col')
1128+
Creates four polar axes, and accesses them through the returned array
11421129
1143-
# Share a Y axis with each row of subplots
1144-
plt.subplots(2, 2, sharey='row')
1130+
>>> fig, axes = plt.subplots(2, 2, subplot_kw=dict(polar=True))
1131+
>>> axes[0, 0].plot(x, y)
1132+
>>> axes[1, 1].scatter(x, y)
11451133
1146-
# Share a X and Y axis with all subplots
1147-
plt.subplots(2, 2, sharex='all', sharey='all')
1148-
# same as
1149-
plt.subplots(2, 2, sharex=True, sharey=True)
1134+
Share a X axis with each column of subplots
1135+
1136+
>>> plt.subplots(2, 2, sharex='col')
1137+
1138+
Share a Y axis with each row of subplots
1139+
1140+
>>> plt.subplots(2, 2, sharey='row')
1141+
1142+
Share both X and Y axes with all subplots
1143+
1144+
>>> plt.subplots(2, 2, sharex='all', sharey='all')
1145+
1146+
Note that this is the same as
1147+
1148+
>>> plt.subplots(2, 2, sharex=True, sharey=True)
1149+
1150+
See Also
1151+
--------
1152+
figure
1153+
subplot
11501154
"""
11511155
fig = figure(**fig_kw)
11521156
axs = fig.subplots(nrows=nrows, ncols=ncols, sharex=sharex, sharey=sharey,

0 commit comments

Comments
 (0)
0