Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 6ad368b

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

File tree

Expand file treeCollapse file tree

2 files changed

+119
-123
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+119
-123
lines changed

‎lib/matplotlib/figure.py

Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+29-37Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+90-86Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.