From da9829f5b59c809d55912bd94c64312c93806704 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 13:49:20 -0700 Subject: [PATCH 1/6] DOC improved subplots' docstring - the dostring is now in numpydoc format. - added an extra line in the examples to showcase accessing the axes returned array closes #7230 --- lib/matplotlib/pyplot.py | 180 +++++++++++++++++++++------------------ 1 file changed, 95 insertions(+), 85 deletions(-) diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 02056a030427..1b60a7cdf3b6 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1038,115 +1038,125 @@ 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. 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 : int, optional, default: 1 + Number of rows of the subplot grid. + + ncols : int, optional, default: 1 + Number of columns of the subplot grid. + + sharex : bool or string, optional, default: False + - If True, the X axis will be shared amongst all subplots. Note that + if nrows > 1 then the x tick labels won't be displayed on any of + plots but the ones on the bottom row. + - If False, no axis will be shared amongst subplots. + - 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. Note that if + nrows > 1 then the x tick labels won't be displayed on any of + the plots but the ones on the bottom row. + + sharey : bool or string, optional, default: False + - If True, the Y axis will be shared amongst all subplots. Note that + if ncols > 1 then the y tick labels won't be displayed on any of + plots but the ones on first column. + - If False, no y-axis will be shared amongst subplots. + - 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. + - If "col", each subplot column will share a y-axis. Note that if + ncols > 1 then the y tick labels won't be displayed on any of + the plots but the ones on the first column. + + squeeze : bool, optional, default: True + - 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 arrays. + + - 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, 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: + Returns + ------- + fig : :class:`matplotlib.figure.Figure` object - fig, ax : tuple + ax : axis or array of axis 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 keyword, see above. - - *fig* is the :class:`matplotlib.figure.Figure` object + Examples + -------- + First create some toy data: - - *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 - keyword, see above. + >>> x = np.linspace(0, 2*np.pi, 400) + >>> y = np.sin(x**2) - Examples:: + Creates just a figure and only one subplot. + + >>> fig, ax = plt.subplots() + >>> ax.plot(x, y) + >>> ax.set_title('Simple plot') + + Creates two subplots and unpacks 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 four polar axes, and accesses them through the returned array + + >>> 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 axis with each column of subplots - x = np.linspace(0, 2*np.pi, 400) - y = np.sin(x**2) + >>> plt.subplots(2, 2, sharex='col') - # Just a figure and one subplot - f, ax = plt.subplots() - ax.plot(x, y) - ax.set_title('Simple plot') + Share a Y axis with each row of subplots - # 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) + >>> plt.subplots(2, 2, sharey='row') - # Four polar axes - plt.subplots(2, 2, subplot_kw=dict(polar=True)) + Share a X and Y axis with all subplots - # Share a X axis with each column of subplots - plt.subplots(2, 2, sharex='col') + >>> plt.subplots(2, 2, sharex='all', sharey='all') - # Share a Y axis with each row of subplots - plt.subplots(2, 2, sharey='row') + Note that this is the same as - # 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) + >>> plt.subplots(2, 2, sharex=True, sharey=True) """ fig = figure(**fig_kw) axs = fig.subplots(nrows=nrows, ncols=ncols, sharex=sharex, sharey=sharey, From 54d422a1ad2e177fe4a46e98fc5c755e0edb26c5 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 20:57:05 -0700 Subject: [PATCH 2/6] FIX comments --- lib/matplotlib/pyplot.py | 45 +++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 1b60a7cdf3b6..d6226f729eab 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1040,7 +1040,7 @@ def subplot(*args, **kwargs): def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, 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. @@ -1054,30 +1054,30 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, Number of columns of the subplot grid. sharex : bool or string, optional, default: False - - If True, the X axis will be shared amongst all subplots. Note that - if nrows > 1 then the x tick labels won't be displayed on any of - plots but the ones on the bottom row. + - If True, the X axis will be shared amongst all subplots. - If False, no axis will be shared amongst subplots. - 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. Note that if - nrows > 1 then the x tick labels won't be displayed on any of - the plots but the ones on the bottom row. + - If "col", each subplot column will share a X axis. + + Note that if the x-axis is shared across rows (sharex=True or + sharex="col") and nrows > 1 then the x tick labels won't be displayed + on any of plots but the ones on the bottom row. sharey : bool or string, optional, default: False - - If True, the Y axis will be shared amongst all subplots. Note that - if ncols > 1 then the y tick labels won't be displayed on any of - plots but the ones on first column. + - If True, the Y axis will be shared amongst all subplots. - If False, no y-axis will be shared amongst subplots. - 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. - - If "col", each subplot column will share a y-axis. Note that if - ncols > 1 then the y tick labels won't be displayed on any of - the plots but the ones on the first column. + - If "col", each subplot column will share a y-axis + + Note that if the y-axis is shared across columns (sharey=False or + sharey="col") and ncols > 1 then the y tick labels won't be displayed + on any of the plots but the ones on the first column. squeeze : bool, optional, default: True - If True, extra dimensions are squeezed out from the returned axis @@ -1111,10 +1111,12 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, ------- fig : :class:`matplotlib.figure.Figure` object - ax : axis or array of axis 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 keyword, see above. + ax : Axes object or array of Axes objects. + + 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 -------- @@ -1123,7 +1125,7 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, >>> x = np.linspace(0, 2*np.pi, 400) >>> y = np.sin(x**2) - Creates just a figure and only one subplot. + Creates just a figure and only one subplot >>> fig, ax = plt.subplots() >>> ax.plot(x, y) @@ -1150,13 +1152,18 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, >>> plt.subplots(2, 2, sharey='row') - Share a X and Y axis with all subplots + 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, From 2c98c6da92f4b19394920653706134e4cfd3f793 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 7 Oct 2016 21:04:56 -0700 Subject: [PATCH 3/6] ENH better wording in the subplots docstring --- lib/matplotlib/pyplot.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index d6226f729eab..ae774ffe2e79 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1054,20 +1054,20 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, Number of columns of the subplot grid. sharex : bool or string, optional, default: False - - If True, the X axis will be shared amongst all subplots. + - If True, the x-axis will be shared amongst all subplots. - If False, no axis will be shared amongst subplots. - 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. + - If "row", each subplot row will share a x-axis. + - If "col", each subplot column will share a x-axis. Note that if the x-axis is shared across rows (sharex=True or - sharex="col") and nrows > 1 then the x tick labels won't be displayed - on any of plots but the ones on the bottom row. + sharex="col"), then the x tick labels will only be display on subplots + of the bottom row. sharey : bool or string, optional, default: False - - If True, the Y axis will be shared amongst all subplots. + - If True, the y-axis will be shared amongst all subplots. - If False, no y-axis will be shared amongst subplots. - If a string must be one of "row", "col", "all", or "none". - "all" has the same effect as True. @@ -1076,8 +1076,8 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, - If "col", each subplot column will share a y-axis Note that if the y-axis is shared across columns (sharey=False or - sharey="col") and ncols > 1 then the y tick labels won't be displayed - on any of the plots but the ones on the first column. + sharey="col"), 1 then the y tick labels will only be displayed on + subplots of the first column. squeeze : bool, optional, default: True - If True, extra dimensions are squeezed out from the returned axis From 20cd16a4f0fb9e2655c89b6bb8173e390ead3db6 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Mon, 10 Oct 2016 21:50:06 -0700 Subject: [PATCH 4/6] DOC figure and pyplot's subplot docstring are now identical --- lib/matplotlib/figure.py | 74 +++++++++++++++++++++------------------- lib/matplotlib/pyplot.py | 11 +++--- 2 files changed, 42 insertions(+), 43 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 287dc64dc9af..84275346e29b 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1025,48 +1025,50 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False, Parameters ---------- - nrows : int, default: 1 - Number of rows of the subplot grid. - - ncols : int, default: 1 - Number of columns of the subplot grid. + nrows, ncols : int, default: 1 + Number of rows/cols of the subplot grid. sharex : {"none", "all", "row", "col"} or bool, default: False - If *False*, or "none", each subplot has its own X 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. + - If True, the x-axis will be shared amongst all subplots. + - If False, no axis will be shared amongst subplots. + - 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. + + Note that if the x-axis is shared across rows (sharex=True or + sharex="col"), then the x tick labels will only be display on + subplots of the bottom row. 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. + - If True, the y-axis will be shared amongst all subplots. + - If False, no y-axis will be shared amongst subplots. + - 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. + - If "col", each subplot column will share a y-axis + + Note that if the y-axis is shared across columns (sharey=False or + sharey="col"), 1 then the y tick labels will only be displayed on + subplots of the first column. 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 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 + arrays. + + - 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, default: {} Dict with keywords passed to the diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index ae774ffe2e79..0f37137a04cb 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1047,13 +1047,10 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, Parameters ---------- - nrows : int, optional, default: 1 - Number of rows of the subplot grid. + nrows, ncols : int, optional, default: 1 + Number of rows/columns of the subplot grid. - ncols : int, optional, default: 1 - Number of columns of the subplot grid. - - sharex : bool or string, optional, default: False + sharex : {"none", "all", "row", "col"} or bool, default: False - If True, the x-axis will be shared amongst all subplots. - If False, no axis will be shared amongst subplots. - If a string must be one of "row", "col", "all", or "none". @@ -1066,7 +1063,7 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, sharex="col"), then the x tick labels will only be display on subplots of the bottom row. - sharey : bool or string, optional, default: False + sharey : {"none", "all", "row", "col"} or bool, default: False - If True, the y-axis will be shared amongst all subplots. - If False, no y-axis will be shared amongst subplots. - If a string must be one of "row", "col", "all", or "none". From a1e728206664d5202730d0700e6612b487665c4a Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Tue, 11 Oct 2016 13:08:33 -0700 Subject: [PATCH 5/6] DOC FIX axis -> x-axis in subplots --- lib/matplotlib/figure.py | 24 ++++++++++++------------ lib/matplotlib/pyplot.py | 26 +++++++++++++------------- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 84275346e29b..de97b5da1db8 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1030,12 +1030,12 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False, sharex : {"none", "all", "row", "col"} or bool, default: False - If True, the x-axis will be shared amongst all subplots. - - If False, no axis will be shared amongst subplots. + - If False, no x-axis will be shared amongst subplots. - 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. + - If "row", each subplot row will share an x-axis. + - If "col", each subplot column will share an x-axis. Note that if the x-axis is shared across rows (sharex=True or sharex="col"), then the x tick labels will only be display on @@ -1048,10 +1048,10 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False, - "all" has the same effect as True. - "none" has the same effect as False. - If "row", each subplot row will share a y-axis. - - If "col", each subplot column will share a y-axis + - If "col", each subplot column will share an y-axis - Note that if the y-axis is shared across columns (sharey=False or - sharey="col"), 1 then the y tick labels will only be displayed on + Note that if the y-axis is shared across columns (sharey=True or + sharey="col"), then the y tick labels will only be displayed on subplots of the first column. squeeze : bool, default: True @@ -1059,15 +1059,15 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False, 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 + 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 + - 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 axis object - is always a 2-d array containing Axis instances, even if it ends + - 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: {} diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 0f37137a04cb..d3048761e9b2 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1052,12 +1052,12 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, sharex : {"none", "all", "row", "col"} or bool, default: False - If True, the x-axis will be shared amongst all subplots. - - If False, no axis will be shared amongst subplots. + - If False, no x-axis will be shared amongst subplots. - 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. + - If "row", each subplot row will share an x-axis. + - If "col", each subplot column will share an x-axis. Note that if the x-axis is shared across rows (sharex=True or sharex="col"), then the x tick labels will only be display on subplots @@ -1070,24 +1070,24 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, - "all" has the same effect as True. - "none" has the same effect as False. - If "row", each subplot row will share a y-axis. - - If "col", each subplot column will share a y-axis + - If "col", each subplot column will share an y-axis - Note that if the y-axis is shared across columns (sharey=False or - sharey="col"), 1 then the y tick labels will only be displayed on + Note that if the y-axis is shared across columns (sharey=True or + sharey="col"), then the y tick labels will only be displayed on subplots of the first column. squeeze : bool, optional, default: True - - If True, extra dimensions are squeezed out from the returned axis + - If True, extra dimensions are squeezed out from the returned Axes 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 arrays. + 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 axis object is - always a 2-d array containing Axis instances, even if it ends up + - 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 From cf09849ae7637b9aaa4e6fbdbbeb729198a66bd3 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 12 Oct 2016 09:54:03 -0700 Subject: [PATCH 6/6] DOC merged sharex/y in subplots docstrings --- lib/matplotlib/figure.py | 40 +++++++++++++++------------------------- lib/matplotlib/pyplot.py | 40 +++++++++++++++------------------------- 2 files changed, 30 insertions(+), 50 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index de97b5da1db8..76ef92d5ce10 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1028,31 +1028,21 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False, nrows, ncols : int, default: 1 Number of rows/cols of the subplot grid. - sharex : {"none", "all", "row", "col"} or bool, default: False - - If True, the x-axis will be shared amongst all subplots. - - If False, no x-axis will be shared amongst subplots. - - 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 an x-axis. - - If "col", each subplot column will share an x-axis. - - Note that if the x-axis is shared across rows (sharex=True or - sharex="col"), then the x tick labels will only be display on - subplots of the bottom row. - - sharey : {"none", "all", "row", "col"} or bool, default: False - - If True, the y-axis will be shared amongst all subplots. - - If False, no y-axis will be shared amongst subplots. - - 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. - - If "col", each subplot column will share an y-axis - - Note that if the y-axis is shared across columns (sharey=True or - sharey="col"), then the y tick labels will only be displayed on - subplots of the first column. + 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, default: True - If True, extra dimensions are squeezed out from the returned diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index d3048761e9b2..d2777086c502 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1050,31 +1050,21 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, nrows, ncols : int, optional, default: 1 Number of rows/columns of the subplot grid. - sharex : {"none", "all", "row", "col"} or bool, default: False - - If True, the x-axis will be shared amongst all subplots. - - If False, no x-axis will be shared amongst subplots. - - 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 an x-axis. - - If "col", each subplot column will share an x-axis. - - Note that if the x-axis is shared across rows (sharex=True or - sharex="col"), then the x tick labels will only be display on subplots - of the bottom row. - - sharey : {"none", "all", "row", "col"} or bool, default: False - - If True, the y-axis will be shared amongst all subplots. - - If False, no y-axis will be shared amongst subplots. - - 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. - - If "col", each subplot column will share an y-axis - - Note that if the y-axis is shared across columns (sharey=True or - sharey="col"), then the y tick labels will only be displayed on - subplots of the first column. + 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