From: <fer...@us...> - 2010-03-20 08:57:45
|
Revision: 8201 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8201&view=rev Author: fer_perez Date: 2010-03-20 08:57:37 +0000 (Sat, 20 Mar 2010) Log Message: ----------- Renamed fig_subplot to suplots(), now returns numpy array with axes. Modified Paths: -------------- trunk/matplotlib/CHANGELOG trunk/matplotlib/examples/pylab_examples/fig_subplot_demo.py trunk/matplotlib/lib/matplotlib/pyplot.py Modified: trunk/matplotlib/CHANGELOG =================================================================== --- trunk/matplotlib/CHANGELOG 2010-03-20 00:29:19 UTC (rev 8200) +++ trunk/matplotlib/CHANGELOG 2010-03-20 08:57:37 UTC (rev 8201) @@ -1,3 +1,7 @@ +2010-03-20 Changed plt.fig_subplot() to plt.subplots() after discussion on + list, and changed its API to return axes as a numpy object array + (with control of dimensions via squeeze keyword). FP. + 2010-03-13 Manually brought in commits from branch ------------------------------------------------------------------------ Modified: trunk/matplotlib/examples/pylab_examples/fig_subplot_demo.py =================================================================== --- trunk/matplotlib/examples/pylab_examples/fig_subplot_demo.py 2010-03-20 00:29:19 UTC (rev 8200) +++ trunk/matplotlib/examples/pylab_examples/fig_subplot_demo.py 2010-03-20 08:57:37 UTC (rev 8201) @@ -1,32 +1,39 @@ +"""Examples illustrating the use of plt.subplots(). + +This function creates a figure and a grid of subplots with a single call, while +providing reasonable control over how the individual plots are created. For +very refined tuning of subplot creation, you can still use add_subplot() +directly on a new figure. """ -""" + import matplotlib.pyplot as plt import numpy as np +# Simple data to display in various forms x = np.linspace(0, 2*np.pi, 400) y = np.sin(x**2) plt.close('all') # Just a figure and one subplot -f, ax = plt.fig_subplot() +f, ax = plt.subplots() ax.plot(x, y) ax.set_title('Simple plot') -# Two subplots, grab the whole fig_axes list -fax = plt.fig_subplot(2, sharex=True) -fax[1].plot(x, y) -fax[1].set_title('Sharing X axis') -fax[2].scatter(x, y) +# Two subplots, the axes array is 1-d +f, axarr = plt.subplots(2, sharex=True) +axarr[0].plot(x, y) +axarr[0].set_title('Sharing X axis') +axarr[1].scatter(x, y) -# Two subplots, unpack the output immediately -f, ax1, ax2 = plt.fig_subplot(1, 2, sharey=True) +# Two subplots, unpack the axes 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) # Three subplots sharing both x/y axes -f, ax1, ax2, ax3 = plt.fig_subplot(3, sharex=True, sharey=True) +f, (ax1, ax2, ax3) = plt.subplots(3, sharex=True, sharey=True) ax1.plot(x, y) ax1.set_title('Sharing both axes') ax2.scatter(x, y) @@ -36,7 +43,21 @@ f.subplots_adjust(hspace=0) plt.setp([a.get_xticklabels() for a in f.axes[:-1]], visible=False) +# Four axes, returned as a 2-d array +f, axarr = plt.subplots(2, 2) +axarr[0,0].plot(x, y) +axarr[0,0].set_title('Axis [0,0]') +axarr[0,1].scatter(x, y) +axarr[0,1].set_title('Axis [0,1]') +axarr[1,0].plot(x, y**2) +axarr[1,0].set_title('Axis [1,0]') +axarr[1,1].scatter(x, y**2) +axarr[1,1].set_title('Axis [1,1]') +# Fine-tune figure; hide x ticks for top plots and y ticks for right plots +plt.setp([a.get_xticklabels() for a in axarr[0,:]], visible=False) +plt.setp([a.get_yticklabels() for a in axarr[:,1]], visible=False) + # Four polar axes -plt.fig_subplot(2, 2, subplot_kw=dict(polar=True)) +plt.subplots(2, 2, subplot_kw=dict(polar=True)) plt.show() Modified: trunk/matplotlib/lib/matplotlib/pyplot.py =================================================================== --- trunk/matplotlib/lib/matplotlib/pyplot.py 2010-03-20 00:29:19 UTC (rev 8200) +++ trunk/matplotlib/lib/matplotlib/pyplot.py 2010-03-20 08:57:37 UTC (rev 8201) @@ -79,7 +79,6 @@ new_figure_manager, draw_if_interactive, show = pylab_setup() - def findobj(o=None, match=None): if o is None: o = gcf() @@ -649,7 +648,7 @@ return a -def fig_subplot(nrows=1, ncols=1, sharex=False, sharey=False, +def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, subplot_kw=None, **fig_kw): """Create a figure with a set of subplots already made. @@ -661,7 +660,7 @@ nrows : int Number of rows of the subplot grid. Defaults to 1. - nrows : int + ncols : int Number of columns of the subplot grid. Defaults to 1. sharex : bool @@ -670,6 +669,18 @@ sharex : bool If True, the Y axis will be shared amongst all subplots. + 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 contaning Axis instances, even if it ends up being 1x1. + subplot_kw : dict Dict with keywords passed to the add_subplot() call used to create each subplots. @@ -680,28 +691,30 @@ Returns: - fig_axes : list - A list containing [fig, ax1, ax2, ...], where fig is the Matplotlib - Figure object and the rest are the axes. - + fig, ax : tuple + - fig is the Matplotlib Figure object + - ax can be either a single axis object or an array of axis objects if + more than one supblot was created. The dimensions of the resulting array + can be controlled with the squeeze keyword, see above. + **Examples:** x = np.linspace(0, 2*np.pi, 400) y = np.sin(x**2) # Just a figure and one subplot - f, ax = plt.fig_subplot() + f, ax = plt.subplots() ax.plot(x, y) ax.set_title('Simple plot') - # Two subplots, unpack the output immediately - f, ax1, ax2 = plt.fig_subplot(1, 2, sharey=True) + # 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) # Four polar axes - plt.fig_subplot(2, 2, subplot_kw=dict(polar=True)) + plt.subplots(2, 2, subplot_kw=dict(polar=True)) """ if subplot_kw is None: @@ -709,20 +722,37 @@ fig = figure(**fig_kw) + # Create empty object array to hold all axes. It's easiest to make it 1-d + # so we can just append subplots upon creation, and then + nplots = nrows*ncols + axarr = np.empty(nplots, dtype=object) + # Create first subplot separately, so we can share it if requested - ax1 = fig.add_subplot(nrows, ncols, 1, **subplot_kw) + ax0 = fig.add_subplot(nrows, ncols, 1, **subplot_kw) if sharex: - subplot_kw['sharex'] = ax1 + subplot_kw['sharex'] = ax0 if sharey: - subplot_kw['sharey'] = ax1 + subplot_kw['sharey'] = ax0 + axarr[0] = ax0 + + # Note off-by-one counting because add_subplot uses the matlab 1-based + # convention. + for i in range(1, nplots): + axarr[i] = fig.add_subplot(nrows, ncols, i+1, **subplot_kw) - # Valid indices for axes start at 1, since fig is at 0: - axes = [ fig.add_subplot(nrows, ncols, i, **subplot_kw) - for i in range(2, nrows*ncols+1)] + if squeeze: + # Reshape the array to have the final desired dimension (nrow,ncol), + # though discarding unneeded dimensions that equal 1. If we only have + # one subplot, just return it instead of a 1-element array. + if nplots==1: + return fig, axarr[0] + else: + return fig, axarr.reshape(nrows, ncols).squeeze() + else: + # returned axis array will be always 2-d, even if nrows=ncols=1 + return fig, axarr.reshape(nrows, ncols) - return [fig, ax1] + axes - def twinx(ax=None): """ Make a second axes overlay *ax* (or the current axes if *ax* is This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |