ENH: add `ax` kwarg to every pyplot function #9111

tacaswell · 2017-08-28T02:09:07Z

This allows passing ax=some_ax into all of the pyplot plotting
functions.

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)

anntzer · 2017-08-28T07:00:51Z

What's the benefit as opposed to just using the OO API, if you really want to specify the figure/axis?

tacaswell · 2017-08-28T13:02:59Z

This is the opening pass at something I have been thinking about for a while.

The very short version is that there is currently a major difference between 'built in' plotting (ax.foo(data, style)) and user / third-party plotting (foo(data, style, ax=ax)) and it would be better to reduce. As we do not want third-party tools to be monkey-patching methods on to Axes, we should rotate the main API to look more like functions to put everything on the same footing. The suggested API would then be

def my_plotter(*data, ax, **style):
   ...

This is bread-crumbs leading that direction.

anntzer · 2017-08-28T15:37:09Z

This actually looks like a reasonable argument (as much as I would like not to admit it...)

WeatherGod · 2017-08-28T16:57:14Z

Yeah, this is pretty much the same proposal from a few years ago that got sidelined to focus on getting the data kwarg into the v1.5 release, isn't it? I totally get the argument, I just don't know how well I like that coding style. Feels very basemap-ish. Whatever happened to the idea of plotting objects?

…

On Mon, Aug 28, 2017 at 11:37 AM, Antony Lee ***@***.***> wrote: This actually looks like a reasonable argument (as much as I would like not to admit it...) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#9111 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARy-N7mVbidz89QregvZ__Vt6Tz1ch1ks5sct6mgaJpZM4PEATz> .

dopplershift · 2017-08-28T18:21:51Z

In general I'm ok with the idea. I do think we should think about the idea of plotting objects in this context before proceeding, though.

anntzer · 2017-08-28T18:24:49Z

Also what's wrong with just using sca() in that case?
Or even

with plt.sca(ax): ...

which is probably going to be less repetitive that having to pass ax again and again.

dopplershift

If for no other reason than that this allows using the pyplot interface with an explicit axes, I'm 💯 on this.

tacaswell · 2017-08-28T19:58:02Z

I think that this and more complex objects are orthogonal. The objects are about making more complex plots easier to update and work with (ex errorbars) and this is about letting third-party code, or code that takes in not-arrays as input feel like first class citizens next to the 'official'.

I expect there to be plotting functions that take in very non-array things (like a partial sql query!).

It also provides a smoother path to leaving the fully implicit world to the full OO world.

tacaswell · 2017-08-31T02:29:56Z

This is actually pass 2 at this, see #4488

anntzer · 2017-08-31T03:34:39Z

lib/matplotlib/tests/test_pyplot.py

+def test_explict_ax():
+    fig, (ax1, ax2) = plt.subplots(2)
+    plt.plot(range(5))
+    plt.plot(range(5)[::-1], ax=ax1)


I would just test that len(ax1.lines) == 2 instead of doing an image comp.

test name has typo ("explicit")

There should be one line per axes (gca() is surprising! ax2 was created last so it is 'current')

you got me :-)
but still you should be able to just test how many lines there are on each axis.

anntzer · 2017-08-31T03:36:11Z

tools/boilerplate.py

@@ -316,12 +318,13 @@ def format_value(value):

            # A gensym-like facility in case some function takes an
            # argument named washold, ax, or ret
-            washold, ret, ax = 'washold', 'ret', 'ax'
+            washold, ret = 'washold', 'ret'


the comment above needs to be updated
side point: I think we should just throw an exception in this case -- the parameter name is part of the API so renaming it seems silly

anntzer · 2017-08-31T04:00:42Z

tools/boilerplate.py

            bad = set(args) | {varargs, varkw}
-            while washold in bad or ret in bad or ax in bad:
+            if 'ax' is set(args):


I was suggesting to do the same for washold and ret below.

efiring · 2017-08-31T16:52:08Z

Even if this turns out to be the way to go, bringing in such a major strategic change with so little discussion and review is not good. Suggestion: leave this out of 2.1, and make it the proposed centerpiece of 2.2, with a very short release cycle--say, Nov. 1 as the target.

tacaswell · 2017-08-31T16:59:10Z

It was worth a shot!

I am taking @efiring 's comment as a veto of this going in for 2.1.

Delaying to 2.2 in Nov would give us time to write some collateral around this change, flesh out some of the other implications, and retroactively write a MEP which is probably for the best

anntzer · 2017-08-31T18:34:46Z

Having though a bit about this, right now I belive my preferred take on such an API ("to make pyplot and external functions more symmetrical") would be

with plt.sca(ax): # or a new function
    plt.plot(...)
    seaborn.somemethod(...)
# when sca() is *exited* there is *no* current axes,
# so plt.gca() would return None and plt.plot would error

which seems better than having to pass the same ax again and again.

tacaswell · 2017-09-01T01:49:17Z

However this means inside of every function there must be a call to plt.gca(). The other long term goal is to get away from the shared global state of pyplot (so everything GC's reasonable, etc).

Having no current figure/ax is a non-starter. pyplot (and all of it's shared global state) exists as convince methods for people sitting in an interactive shell and I do not think we will ever be able to remove it, just make it possible for people to use without it.

Having a context manager that resets the current axes to what it was before would be a reasonable thing though.

XXX(..., ax=ax) is not that much more onerous than ax.XXX(...)

NelleV

In terms of code, this looks good, but the PR introduces a backward incompatible change.

On the documentation front, a lot of the docstrings need to be updated to reflect the addition of an optional keyword argument. I'm happy to push the missing documentation.

I'm also concerned about the unit tests. While indeed, this has been tested on one of the pyplot function, I think we should maybe write smoke tests coverage all pyplot functions concerned by this change.

NelleV · 2018-07-12T17:44:33Z

lib/matplotlib/pyplot.py

@@ -928,7 +970,7 @@ def delaxes(*args):
    if not len(args):
        ax = gca()
    else:
-        ax = args[0]
+        ax, = args


This will fail if args has more arguments than one. If args is can only be one optional argument, why not change *args into an actual optional keyword argument? That would make the code more readible, and more easily documentable than currently.

Note that because of this line we are currently introducing a backward compatible change with this PR.

NelleV · 2018-07-12T17:47:15Z

lib/matplotlib/pyplot.py

@@ -1328,19 +1374,20 @@ def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None):
        coordinate that the whole subplots area (including
        labels) will fit into. Default is (0, 0, 1, 1).
    """
-
-    fig = gcf()
+    if fig is None:


The docstring needs to be update to reflect the addition of an optional keyword argument.

NelleV · 2018-07-12T17:48:36Z

lib/matplotlib/pyplot.py

    fig.tight_layout(pad=pad, h_pad=h_pad, w_pad=w_pad, rect=rect)


-def box(on=None):
+def box(on=None, ax=None):


The docstring needs to be update to reflect the addition of an optional keyword argument.

NelleV · 2018-07-12T17:49:06Z

lib/matplotlib/pyplot.py

@@ -1376,6 +1423,9 @@ def title(s, *args, **kwargs):
    loc : {'center', 'left', 'right'}, str, optional
        Which title to set, defaults to 'center'

+    ax : matplotlib.axes.Axes, optional


NelleV · 2018-07-12T17:50:09Z

lib/matplotlib/pyplot.py

@@ -1389,7 +1439,7 @@ def title(s, *args, **kwargs):
        properties.

    """
-    return gca().set_title(s, *args, **kwargs)
+    return _pop_or_gca(kwargs).set_title(s, *args, **kwargs)


The docstring needs to be update to reflect the addition of an optional keyword argument.

tacaswell · 2022-12-04T18:46:54Z

rebased to keep the dream alive.

github-actions · 2023-04-16T01:56:53Z

Since this Pull Request has not been updated in 60 days, it has been marked "inactive." This does not mean that it will be closed, though it may be moved to a "Draft" state. This helps maintainers prioritize their reviewing efforts. You can pick the PR back up anytime - please ping us if you need a review or guidance to move the PR forward! If you do not plan on continuing the work, please let us know so that we can either find someone to take the PR over, or close it.

timhoffm · 2023-04-16T09:17:23Z

As a side-note: The place where the ax keyword is most present is the pandas plot API. Unfortunately, they have a different semantic (“if not given, create a new axes” vs. pyplot: “if not given, use the current axes - only if there is no current axes, create a new one).
Not necessarily a blocker, but we have to be aware that this will be a source of confusion.

I've marked this as keep and needs comment/discussion because it really something to investigate, but the correct approach is not yet clear.

This allows passing `ax=some_ax` or `fig=some_fig` into all of the pyplot plotting functions.

tacaswell · 2023-07-03T20:21:21Z

I could not quickly figure out how to convince the generated annotations to not use the fully qualified class names.

Bit confused why it was not hitting these before.

tacaswell · 2023-07-03T20:47:26Z

mypy is still also a bit unhappy (it does not like forwarding returns through unconditionally...I guess the fix would be to make the generating code smart enough to drop the return if the wrapped function claims to only ever return None.

tacaswell added this to the 2.1 (next point release) milestone Aug 28, 2017

tacaswell force-pushed the ENH_ax_into_pyplot branch from e95b2b8 to 4d4662e Compare August 28, 2017 02:17

dopplershift approved these changes Aug 28, 2017

View reviewed changes

tacaswell added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Aug 28, 2017

tacaswell force-pushed the ENH_ax_into_pyplot branch from 54215b7 to 1bbbed8 Compare August 31, 2017 02:17

tacaswell force-pushed the ENH_ax_into_pyplot branch 2 times, most recently from b08714c to f26efd9 Compare August 31, 2017 03:06

anntzer reviewed Aug 31, 2017

View reviewed changes

tacaswell force-pushed the ENH_ax_into_pyplot branch from 198eb48 to ccabef7 Compare August 31, 2017 03:56

anntzer reviewed Aug 31, 2017

View reviewed changes

tacaswell modified the milestones: 2.2 (next next feature release), 2.1 (next point release) Aug 31, 2017

dstansby removed the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Oct 14, 2017

tacaswell modified the milestones: needs sorting, v3.1 Jul 7, 2018

tacaswell added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Jul 7, 2018

NelleV reviewed Jul 12, 2018

View reviewed changes

tacaswell modified the milestones: v3.3.0, v3.4.0 May 13, 2020

jklymak marked this pull request as draft August 24, 2020 14:19

QuLogic modified the milestones: v3.4.0, v3.5.0 Jan 21, 2021

tacaswell modified the milestones: v3.5.0, 3.6.0 Jul 8, 2021

timhoffm modified the milestones: v3.6.0, unassigned Apr 30, 2022

story645 modified the milestones: unassigned, needs sorting Oct 6, 2022

github-actions bot added the status: needs rebase label Oct 18, 2022

tacaswell force-pushed the ENH_ax_into_pyplot branch from 98c8f53 to 2cb8655 Compare December 4, 2022 18:46

github-actions bot removed the status: needs rebase label Dec 4, 2022

github-actions bot added the status: needs rebase label Dec 23, 2022

github-actions bot added the status: inactive Marked by the “Stale” Github Action label Apr 16, 2023

timhoffm added status: needs comment/discussion needs consensus on next step keep Items to be ignored by the “Stale” Github Action and removed status: inactive Marked by the “Stale” Github Action labels Apr 16, 2023

ENH: add ax or fig kwarg to every pyplot function

e0178fb

This allows passing `ax=some_ax` or `fig=some_fig` into all of the pyplot plotting functions.

tacaswell force-pushed the ENH_ax_into_pyplot branch from 2fc6e64 to e0178fb Compare July 3, 2023 20:20

github-actions bot removed the status: needs rebase label Jul 3, 2023

tacaswell mentioned this pull request Jul 3, 2023

Idea: unite xlim and set_xlim to same function #15938

Closed

STY: attempt to placate mypy

2c7f076

Bit confused why it was not hitting these before.

github-actions bot added the status: needs rebase label Jul 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENH: add `ax` kwarg to every pyplot function #9111

ENH: add `ax` kwarg to every pyplot function #9111

tacaswell commented Aug 28, 2017

anntzer commented Aug 28, 2017

tacaswell commented Aug 28, 2017

anntzer commented Aug 28, 2017

WeatherGod commented Aug 28, 2017 via email

dopplershift commented Aug 28, 2017

anntzer commented Aug 28, 2017

dopplershift left a comment

tacaswell commented Aug 28, 2017

tacaswell commented Aug 31, 2017

anntzer Aug 31, 2017

tacaswell Aug 31, 2017

anntzer Aug 31, 2017

tacaswell Aug 31, 2017

anntzer Aug 31, 2017 •

edited

Loading

anntzer Aug 31, 2017

efiring commented Aug 31, 2017

tacaswell commented Aug 31, 2017

anntzer commented Aug 31, 2017

tacaswell commented Sep 1, 2017

NelleV left a comment

NelleV Jul 12, 2018

NelleV Jul 12, 2018

NelleV Jul 12, 2018

NelleV Jul 12, 2018

NelleV Jul 12, 2018

tacaswell commented Dec 4, 2022

github-actions bot commented Apr 16, 2023

timhoffm commented Apr 16, 2023 •

edited

Loading

tacaswell commented Jul 3, 2023

tacaswell commented Jul 3, 2023

ENH: add ax kwarg to every pyplot function #9111

Are you sure you want to change the base?

ENH: add ax kwarg to every pyplot function #9111

Conversation

tacaswell commented Aug 28, 2017

PR Checklist

anntzer commented Aug 28, 2017

tacaswell commented Aug 28, 2017

anntzer commented Aug 28, 2017

WeatherGod commented Aug 28, 2017 via email

dopplershift commented Aug 28, 2017

anntzer commented Aug 28, 2017

dopplershift left a comment

Choose a reason for hiding this comment

tacaswell commented Aug 28, 2017

tacaswell commented Aug 31, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer Aug 31, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

efiring commented Aug 31, 2017

tacaswell commented Aug 31, 2017

anntzer commented Aug 31, 2017

tacaswell commented Sep 1, 2017

NelleV left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Dec 4, 2022

github-actions bot commented Apr 16, 2023

timhoffm commented Apr 16, 2023 • edited Loading

tacaswell commented Jul 3, 2023

tacaswell commented Jul 3, 2023

ENH: add `ax` kwarg to every pyplot function #9111

ENH: add `ax` kwarg to every pyplot function #9111

anntzer Aug 31, 2017 •

edited

Loading

timhoffm commented Apr 16, 2023 •

edited

Loading