Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

subplot docstring improvement (re #300) #953

Closed
wants to merge 8 commits into from

7 participants

@pelson
Collaborator

I have tried to improve the documentation of the subplot function, I don't expect this to be perfect, but I do think its an improvement.

This PR is in response to issue #300

@WeatherGod
Collaborator

"keep_super_axes" is new functionality and should be noted in the API Changes. Also, what is the motivation for this feature?

lib/matplotlib/pyplot.py
@@ -746,31 +763,36 @@ def subplot(*args, **kwargs):
for the subplot. This projection must have been previously
registered. See :mod:`matplotlib.projections`.
+ *keep_super_axes*:
+ A boolean flag indication whether the removal of axes which
+ fully overlap the newly created one should take place.
@mdboom Owner
mdboom added a note

This sentence is a bit awkward. How about:

"When True, remove axes which fully overlap the newly created axes. Default is False."

@pelson Collaborator
pelson added a note

Proof that the sentence was awkward...you got it the wrong way around.

"When False, remove axes which fully overlap the newly created axes. Default is False."
or
"When True, keep any axes which fully overlap the newly created axes. Default is False."
or
I remove the whole thing...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mdboom
Owner

The documentation changes look good. The keep_super_axes feature should probably have its own pull request and a note in the API changes, as @WeatherGod said. I think it would also be helpful to have @leejjoon comment on that feature , as one who has dealt a lot with axes management.

@pelson
Collaborator

what is the motivation for this feature?

Good question. I don't need it, but it is/was documented as saying:

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.::
 ...

I either had the choice of removing the statement completely, or implementing something (if users will never have a need for keep_super_axes, then we can remove it and no mention of "If you do not want this behavior..." is need at all)

lib/matplotlib/pyplot.py
((39 lines not shown))
+ .. note::
+
+ Creating a new subplot with a position which is fully consumed by a
+ pre-existing axes will trigger the larger axes to be deleted::
+
+ from pylab import *
+ # plot a line, implicitly creating a subplot(111)
+ 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
+ subplot(211)
+ plot(rand(12), rand(12))
+ subplot(212, axisbg='y') # creates 2nd subplot with yellow background
+
+ This functionality can be disabled by setting *keep_super_axes* to be
@pelson Collaborator
pelson added a note

I'm happy to remove the new keyword, but I do feel uncomfortable about not being able to make a simple statement about how to disable this behaviour. Maybe, given that mpl has been around so long, such functionality really isn't needed, in which case, I could simply remove this line...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@WeatherGod
Collaborator

At the very least, we are going to need this branch rebased.

@pelson
Collaborator

I rebased (looks like it needs doing again). If anybody is willing to pick it up, then assign it to yourself and put it in the 1.2.x milestone and I will rebase and polish. Otherwise, I think it is going to miss the freeze.

@mdboom
Owner

It would be nice to get the docstring part of this change in, even if the code part doesn't. I think docstring-only changes are generally ok during the freeze anyway.

@pelson
Collaborator

Ok. Fair plan.

@dmcdougall
Collaborator

Is it worth getting this into 1.2? As @mdboom points out, getting clearer docstrings in, in my opinion, will only help our users.

mdboom and others added some commits
@mdboom mdboom Fix itervalues -> values. As reported by Massimiliano Costacurta in m…
…ailing list thread "BUG: RuntimeError: dictionary changed size during iteration"
09ca7c2
@tacaswell tacaswell slight tweak to the documentation of `errorbar` to make it clear
that xerr and yerr are always relative to the data location.
a83790b
@tacaswell tacaswell white space fix 184b254
@efiring efiring Merge pull request #1743 from tacaswell/errorbar_doc_tweak
slight tweak to the documentation of `errorbar`
7e91aa7
@efiring efiring Merge pull request #1698 from mdboom/iteritems_bug
Fix bug updating WeakKeyDictionary during iteration
610b182
@drevicko drevicko Update examples/pylab_examples/histogram_demo_extended.py
Fixed a variable name typo
cdae0d5
@efiring efiring Merge pull request #1755 from drevicko/v1.2.x
Update examples/pylab_examples/histogram_demo_extended.py
43e0844
lib/matplotlib/pyplot.py
((30 lines not shown))
- 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.::
+ 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 but this is how the returned subplot has been positioned).
+
+ .. note::
+
+ Creating a new subplot with a position which is fully consumed by a
@efiring Owner
efiring added a note

"fully consumed by" -> "entirely inside"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@efiring
Owner

@pelson, I think that if you apply the docstring changes only, so you are changing only pyplot.py, then they can be merged quickly and the PR backlog will be reduced by one. I would suggest targeting master. (I suggested one wording change inline.)

As for a follow-up PR, I'm not sure what to do about "keep_super_axes". I don't like the kwarg name, and I don't like the existing mis-feature (auto-deletion of an existing containing Axes). It adds much more complexity, and documentation requirement, than it could possibly be worth. Adding the ability to defeat it with a kwarg is the usual cumbersome way of moving to deprecate and remove it. I think I would support adding the kwarg only if this is its goal, so that it will eventually go away. I don't know what to call it. Maybe "remove_enclosing", with default starting as True, changing to False, and then vanishing, to the cheers of the crowd.

@pelson
Collaborator

I've done the work, but I've based it against v1.2.x - I don't have enough github foo to change the target of this PR (I'm not sure that is even possible with v3 of github's api), so will close and create a new PR.

@pelson pelson closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jan 23, 2013
  1. @mdboom

    Fix itervalues -> values. As reported by Massimiliano Costacurta in m…

    mdboom authored
    …ailing list thread "BUG: RuntimeError: dictionary changed size during iteration"
Commits on Feb 11, 2013
  1. @tacaswell

    slight tweak to the documentation of `errorbar` to make it clear

    tacaswell authored
    that xerr and yerr are always relative to the data location.
  2. @tacaswell

    white space fix

    tacaswell authored
Commits on Feb 17, 2013
  1. @efiring

    Merge pull request #1743 from tacaswell/errorbar_doc_tweak

    efiring authored
    slight tweak to the documentation of `errorbar`
  2. @efiring

    Merge pull request #1698 from mdboom/iteritems_bug

    efiring authored
    Fix bug updating WeakKeyDictionary during iteration
  3. @drevicko

    Update examples/pylab_examples/histogram_demo_extended.py

    drevicko authored
    Fixed a variable name typo
Commits on Feb 18, 2013
  1. @efiring

    Merge pull request #1755 from drevicko/v1.2.x

    efiring authored
    Update examples/pylab_examples/histogram_demo_extended.py
  2. @pelson
This page is out of date. Refresh to see the latest.
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  examples/pylab_examples/histogram_demo_extended.py
@@ -111,7 +111,7 @@
w1 = np.ones_like(x1)
w1[:len(x1)/2] = 0.5
w2 = np.ones_like(x2)
-w0[:len(x2)/2] = 0.5
+w2[:len(x2)/2] = 0.5
View
9 lib/matplotlib/axes.py
@@ -5320,11 +5320,12 @@ def errorbar(self, x, y, yerr=None, xerr=None,
Optional keyword arguments:
*xerr*/*yerr*: [ scalar | N, Nx1, or 2xN array-like ]
- If a scalar number, len(N) array-like object, or an Nx1 array-like
- object, errorbars are drawn +/- value.
+ If a scalar number, len(N) array-like object, or an Nx1
+ array-like object, errorbars are drawn at +/-value relative
+ to the data.
- If a sequence of shape 2xN, errorbars are drawn at -row1 and
- +row2
+ If a sequence of shape 2xN, errorbars are drawn at -row1
+ and +row2 relative to the data.
*fmt*: '-'
The plot format symbol. If *fmt* is *None*, only the
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
View
2  lib/matplotlib/transforms.py
@@ -150,7 +150,7 @@ def _invalidate_internal(self, value, invalidating_node):
if self.pass_through or status_changed:
self._invalid = value
- for parent in self._parents.itervalues():
+ for parent in self._parents.values():
parent._invalidate_internal(value=value,
invalidating_node=self)
Something went wrong with that request. Please try again.