diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 287dc64dc9af..76ef92d5ce10 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1025,48 +1025,40 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False, Parameters ---------- - nrows : int, default: 1 - Number of rows of the subplot grid. + nrows, ncols : int, default: 1 + Number of rows/cols of the subplot grid. - ncols : int, default: 1 - Number of 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`) + axes: - sharex : {"none", "all", "row", "col"} or bool, default: False - If *False*, or "none", each subplot has its own X axis. + - True or 'all': x- or y-axis will be shared among all + subplots. + - False or 'none': each subplot x- or y-axis will be + independent. + - 'row': each subplot row will share an x- or y-axis. + - 'col': each subplot column will share an x- or y-axis. - If *True*, or "all", all subplots will share an X axis, and the x - tick labels on all but the last row of plots will be invisible. - - If "col", each subplot column will share an X axis, and the x - tick labels on all but the last row of plots will be invisible. - - If "row", each subplot row will share an X axis. - - sharey : {"none", "all", "row", "col"} or bool, default: False - If *False*, or "none", each subplot has its own Y axis. - - If *True*, or "all", all subplots will share an Y axis, and the y - tick labels on all but the first column of plots will be invisible. - - If "row", each subplot row will share an Y axis, and the y tick - labels on all but the first column of plots will be invisible. - - If "col", each subplot column will share an Y axis. + When subplots have a shared x-axis along a column, only the x tick + labels of the bottom subplot are visible. Similarly, when + subplots have a shared y-axis along a row, only the y tick labels + of the first column subplot are visible. squeeze : bool, default: True - If *True*, extra dimensions are squeezed out from the returned axes - array: - - - if only one subplot is constructed (nrows=ncols=1), the resulting - single Axes object is returned as a scalar. - - - for Nx1 or 1xN subplots, the returned object is a 1-d numpy - object array of Axes objects are returned as numpy 1-d arrays. - - - for NxM subplots with N>1 and M>1 are returned as a 2d array. - - If *False*, no squeezing at all is done: the returned object is - always a 2-d array of Axes instances, even if it ends up being 1x1. + - If True, extra dimensions are squeezed out from the returned + axis object: + + - if only one subplot is constructed (nrows=ncols=1), the + resulting single Axes object is returned as a scalar. + - for Nx1 or 1xN subplots, the returned object is a 1D numpy + object array of Axes objects are returned as numpy 1D + arrays. + - for NxM, subplots with N>1 and M>1 are returned as a 2D + arrays. + + - If False, no squeezing at all is done: the returned Axes object + is always a 2D array containing Axes instances, even if it ends + up being 1x1. subplot_kw : dict, default: {} Dict with keywords passed to the diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 02056a030427..d2777086c502 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1038,115 +1038,119 @@ def subplot(*args, **kwargs): def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, - subplot_kw=None, gridspec_kw=None, **fig_kw): + subplot_kw=None, gridspec_kw=None, **fig_kw): """ - Create a figure with a set of subplots already made. + Create a figure and a set of subplots This utility wrapper makes it convenient to create common layouts of subplots, including the enclosing figure object, in a single call. - Keyword arguments: - - *nrows* : int - Number of rows of the subplot grid. Defaults to 1. - - *ncols* : int - Number of columns of the subplot grid. Defaults to 1. - - *sharex* : string or bool - If *True*, the X axis will be shared amongst all subplots. If - *True* and you have multiple rows, the x tick labels on all but - the last row of plots will have visible set to *False* - If a string must be one of "row", "col", "all", or "none". - "all" has the same effect as *True*, "none" has the same effect - as *False*. - If "row", each subplot row will share a X axis. - If "col", each subplot column will share a X axis and the x tick - labels on all but the last row will have visible set to *False*. - - *sharey* : string or bool - If *True*, the Y axis will be shared amongst all subplots. If - *True* and you have multiple columns, the y tick labels on all but - the first column of plots will have visible set to *False* - If a string must be one of "row", "col", "all", or "none". - "all" has the same effect as *True*, "none" has the same effect - as *False*. - If "row", each subplot row will share a Y axis and the y tick - labels on all but the first column will have visible set to *False*. - If "col", each subplot column will share a Y axis. - - *squeeze* : bool - If *True*, extra dimensions are squeezed out from the - returned axis object: - - - if only one subplot is constructed (nrows=ncols=1), the - resulting single Axis object is returned as a scalar. - - - for Nx1 or 1xN subplots, the returned object is a 1-d numpy - object array of Axis objects are returned as numpy 1-d - arrays. - - - for NxM subplots with N>1 and M>1 are returned as a 2d - array. - - If *False*, no squeezing at all is done: the returned axis - object is always a 2-d array containing Axis instances, even if it - ends up being 1x1. - - *subplot_kw* : dict + Parameters + ---------- + 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`) + axes: + + - True or 'all': x- or y-axis will be shared among all + subplots. + - False or 'none': each subplot x- or y-axis will be + independent. + - 'row': each subplot row will share an x- or y-axis. + - 'col': each subplot column will share an x- or y-axis. + + When subplots have a shared x-axis along a column, only the x tick + labels of the bottom subplot are visible. Similarly, when subplots + have a shared y-axis along a row, only the y tick labels of the first + column subplot are visible. + + squeeze : bool, optional, default: True + - If True, extra dimensions are squeezed out from the returned Axes + object: + + - if only one subplot is constructed (nrows=ncols=1), the + resulting single Axes object is returned as a scalar. + - for Nx1 or 1xN subplots, the returned object is a 1D numpy + object array of Axes objects are returned as numpy 1D arrays. + - for NxM, subplots with N>1 and M>1 are returned as a 2D arrays. + + - If False, no squeezing at all is done: the returned Axes object is + always a 2D array containing Axes instances, even if it ends up + being 1x1. + + subplot_kw : dict, optional Dict with keywords passed to the - :meth:`~matplotlib.figure.Figure.add_subplot` call used to - create each subplots. + :meth:`~matplotlib.figure.Figure.add_subplot` call used to create each + subplot. - *gridspec_kw* : dict + 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. + :class:`~matplotlib.gridspec.GridSpec` constructor used to create the + grid the subplots are placed on. - *fig_kw* : dict + fig_kw : dict, optional Dict with keywords passed to the :func:`figure` call. Note that all keywords not recognized above will be automatically included here. - Returns: - - fig, ax : tuple + Returns + ------- + fig : :class:`matplotlib.figure.Figure` object - - *fig* is the :class:`matplotlib.figure.Figure` object + ax : Axes object or array of Axes objects. - - *ax* can be either a single axis object or an array of axis - objects if more than one subplot was created. The dimensions - of the resulting array can be controlled with the squeeze + ax can be either a single :class:`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. - Examples:: + Examples + -------- + First create some toy data: + + >>> x = np.linspace(0, 2*np.pi, 400) + >>> y = np.sin(x**2) - x = np.linspace(0, 2*np.pi, 400) - y = np.sin(x**2) + Creates just a figure and only one subplot - # Just a figure and one subplot - f, ax = plt.subplots() - ax.plot(x, y) - ax.set_title('Simple plot') + >>> fig, ax = plt.subplots() + >>> ax.plot(x, y) + >>> ax.set_title('Simple plot') - # Two subplots, unpack the output array immediately - f, (ax1, ax2) = plt.subplots(1, 2, sharey=True) - ax1.plot(x, y) - ax1.set_title('Sharing Y axis') - ax2.scatter(x, y) + Creates two subplots and unpacks the output array immediately - # Four polar axes - plt.subplots(2, 2, subplot_kw=dict(polar=True)) + >>> f, (ax1, ax2) = plt.subplots(1, 2, sharey=True) + >>> ax1.plot(x, y) + >>> ax1.set_title('Sharing Y axis') + >>> ax2.scatter(x, y) - # Share a X axis with each column of subplots - plt.subplots(2, 2, sharex='col') + Creates four polar axes, and accesses them through the returned array - # Share a Y axis with each row of subplots - plt.subplots(2, 2, sharey='row') + >>> fig, axes = plt.subplots(2, 2, subplot_kw=dict(polar=True)) + >>> axes[0, 0].plot(x, y) + >>> axes[1, 1].scatter(x, y) - # Share a X and Y axis with all subplots - plt.subplots(2, 2, sharex='all', sharey='all') - # same as - plt.subplots(2, 2, sharex=True, sharey=True) + Share a X axis with each column of subplots + + >>> plt.subplots(2, 2, sharex='col') + + Share a Y axis with each row of subplots + + >>> plt.subplots(2, 2, sharey='row') + + Share both X and Y axes with all subplots + + >>> plt.subplots(2, 2, sharex='all', sharey='all') + + Note that this is the same as + + >>> plt.subplots(2, 2, sharex=True, sharey=True) + + See Also + -------- + figure + subplot """ fig = figure(**fig_kw) axs = fig.subplots(nrows=nrows, ncols=ncols, sharex=sharex, sharey=sharey,