Skip to content

Loading…

Improved the subplot function documentation and fixed the autogeneration from boilerplate. #1760

Merged
merged 1 commit into from

2 participants

@pelson
Matplotlib Developers member

Replaces #953 & closes #300

@efiring efiring merged commit 106541d into matplotlib:v1.2.x

1 check failed

Details default The Travis build could not complete due to an error
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 18, 2013
  1. @pelson
Showing with 40 additions and 24 deletions.
  1. +5 −4 boilerplate.py
  2. +1 −1 lib/matplotlib/pylab.py
  3. +34 −19 lib/matplotlib/pyplot.py
View
9 boilerplate.py
@@ -47,7 +47,7 @@ def %(func)s(%(argspec)s):
%(ax)s = gca()
# allow callers to override the hold state by passing hold=True|False
%(washold)s = %(ax)s.ishold()
- %(sethold)s
+%(sethold)s
if hold is not None:
%(ax)s.hold(hold)
try:
@@ -55,7 +55,7 @@ def %(func)s(%(argspec)s):
draw_if_interactive()
finally:
%(ax)s.hold(%(washold)s)
- %(mappable)s
+%(mappable)s
return %(ret)s
"""
@@ -199,7 +199,7 @@ def format_value(value):
# For some commands, an additional line is needed to set the
# color map
if func in cmappable:
- mappable = cmappable[func] % locals()
+ mappable = ' ' + cmappable[func] % locals()
else:
mappable = ''
@@ -232,7 +232,7 @@ def format_value(value):
# argument in front of it since it would gobble one of the
# arguments the user means to pass via *args)
if varargs:
- sethold = "hold = %(varkw)s.pop('hold', None)" % locals()
+ sethold = " hold = %(varkw)s.pop('hold', None)" % locals()
elif fmt is PLOT_TEMPLATE:
args.append('hold')
defaults = defaults + (None,)
@@ -306,6 +306,7 @@ def build_pyplot():
pyplot.write('\n')
pyplot.writelines(boilerplate_gen())
+ pyplot.write('\n')
if __name__ == '__main__':
View
2 lib/matplotlib/pylab.py
@@ -83,7 +83,7 @@
specgram - a spectrogram plot
spy - plot sparsity pattern using markers or image
stem - make a stem plot
- subplot - make a subplot (numrows, numcols, axesnum)
+ subplot - make a subplot (nrows, ncols, plot_number)
subplots_adjust - change the params controlling the subplot positions of current figure
subplot_tool - launch the subplot configuration tool
suptitle - add a figure title
View
53 lib/matplotlib/pyplot.py
@@ -711,32 +711,47 @@ def gca(**kwargs):
def subplot(*args, **kwargs):
"""
- Create a new axes (subplot).
+ Return a subplot axes positioned by the given grid definition.
- Creating axes with::
+ Typical call signature::
- subplot(numRows, numCols, plotNum)
+ subplot(nrows, ncols, plot_number)
- where *plotNum* = 1 is the first plot number and increasing *plotNums*
- fill rows first. max(*plotNum*) == *numRows* * *numCols*
+ Where *nrows* and *ncols* are used to notionally split the figure
+ into ``nrows * ncols`` sub-axes, and *plot_number* is used to identify
+ the particular subplot that this function is to create within the notional
+ grid. *plot_number* starts at 1, increments across rows first and has a
+ maximum of ``nrows * ncols``.
- You can leave out the commas if *numRows* <= *numCols* <=
- *plotNum* < 10, as in::
+ In the case when *nrows*, *ncols* and *plot_number* are all less than 10,
+ a convenience exists, such that the a 3 digit number can be given instead,
+ where the hundreds represent *nrows*, the tens represent *ncols* and the
+ units represent *plot_number*. For instance::
- subplot(211) # 2 rows, 1 column, first (upper) plot
+ subplot(211)
- ``subplot(111)`` is the default axis.
+ produces a subaxes in a figure which represents the top plot (i.e. the
+ first) in a 2 row by 1 column notional grid (no grid actually exists,
+ but conceptually this is how the returned subplot has been positioned).
- New subplots that overlap old will delete the old axes. If you do
- not want this behavior, use
- :meth:`~matplotlib.figure.Figure.add_subplot` or the
- :func:`~matplotlib.pyplot.axes` command. Eg.::
+ .. note::
- from pylab import *
- plot([1,2,3]) # implicitly creates subplot(111)
- subplot(211) # overlaps, subplot(111) is killed
- plot(rand(12), rand(12))
- subplot(212, axisbg='y') # creates 2nd subplot with yellow background
+ Creating a new subplot with a position which is entirely inside a
+ pre-existing axes will trigger the larger axes to be deleted::
+
+ import matplotlib.pyplot as plt
+ # plot a line, implicitly creating a subplot(111)
+ plt.plot([1,2,3])
+ # now create a subplot which represents the top plot of a grid
+ # with 2 rows and 1 column. Since this subplot will overlap the
+ # first, the plot (and its axes) previously created, will be removed
+ plt.subplot(211)
+ plt.plot(range(12))
+ plt.subplot(212, axisbg='y') # creates 2nd subplot with yellow background
+
+ If you do not want this behavior, use the
+ :meth:`~matplotlib.figure.Figure.add_subplot` method or the
+ :func:`~matplotlib.pyplot.axes` function instead.
Keyword arguments:
@@ -2997,7 +3012,7 @@ def stackplot(x, *args, **kwargs):
draw_if_interactive()
finally:
ax.hold(washold)
-
+
return ret
# This function was autogenerated by boilerplate.py. Do not edit as
Something went wrong with that request. Please try again.