[MRG] Constrained_layout (geometry manager)

[jklymak]

PR Summary

This is my implementation of the geometry manager (See #1109).

This is heavily based on exploratory work by @Tillsten using the kiwi solver, and of course on tight_layout.

Latest what's new: https://5396-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/users/next_whats_new/constrained_layout.html

Latest tutorial: https://5398-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/intermediate/constrainedlayout_guide.html#sphx-glr-tutorials-intermediate-constrainedlayout-guide-py

Intro

tight_layout() is great for what it does, but it doesn't handle some cases generally. i.e. if we have two GridSpecFromSubplotSpec instances, they need to be positioned manually using tight_layout(). Colorbars for individual axes work fine, but colorbars for more than one axis doesn't work. Etc.

This PR implements "constrained_layout" via plt.figure(constrained_layout=True) for automatic re-drawing. Currently, it works for subplots and colorbars, legends, and suptitles. Nested gridspecs are respected. Spacing is provided both as a pad around axes and as a space between subplots.

The following code gives this plot:

    fig = plt.figure(constrained_layout=True)
    gs = gridspec.GridSpec(1, 2, fig=fig)
    gsl = gridspec.GridSpecFromSubplotSpec(2, 2, gs[0])
    gsr = gridspec.GridSpecFromSubplotSpec(1, 2, gs[1])
    axsl = []
    for gs in gsl:
        ax = fig.add_subplot(gs)
        axsl += [ax]
        example_plot(ax, fontsize=12)
    ax.set_xlabel('x-label\nMultiLine')
    axsr = []
    for gs in gsr:
        ax = fig.add_subplot(gs)
        axsr += [ax]
        pcm = example_pcolor(ax, fontsize=12)

    fig.colorbar(pcm, ax = axsr, pad=0.01, 
             location='bottom', ticks=ticker.MaxNLocator(nbins=5))

A few things to note in the above:

• all the subplots in the left side set of plots (gsl) have the same margins. They are a bit big because the bottom-right plot has a two-line x-label.
• the x-ticklabels for the rhs plot overrun, because constrained_layout doesn't do any management at the axis level.

Installation:

In addition to the normal matplotlib installation, you will need to involve kiwisolver: pip install kiwisolver now works.

API dfferences (so far)

In order to get this to work, there are a couple of API changes:

1. gridspec.GridSpec now has a fig keyword. If this isn't supplied then constrained_layout won't work.
2. figure now has a constrained_layout keyword. Currently, I don't have it checking for tight_layout, so they could both run at the same time. These upper level user-facing decisions probaby require input.
3. Internal calling issue: We don't want axes that have user-called ax.set_position() to participate in constrained_layout, presumably because the user was purposefully putting the axis where they put it. So, that means internally, we set the layoutbox properties of this axis to None. However, ax.set_position gets called internally (i.e. by colorbar and aspect) and for those we presumably want to keep constrained_layout as a possibility. So I made a ax._set_position() for internal calls, which the public ax.set_position() uses. Internal calls to set_position should use _set_position if the axis is to continue to participate in constrained_layout.

I think most of these changes are backwards compatible, in that if you don't want to use constrained_layout you don't need to change any calls. Backwards compatibility introduces some awkwardness, but is probably worth it.

Implementation:

Implementation is via a new package layoutbox.py. Basically a nested array of layoutboxe objects are set up, attached to the figure, the gridspec(s), the subplotspecs. An axes has two layoutboxes: one that contains the tight bounding box of the axes, and the second that contains the "position" of the axes (i.e the rectangle that is passed to ax.set_position()).

A linear constraint solver is used to decide dimensions. The trick here is that we define margins between an axes bounding box and its position. These margins, and the outer dimesnion of the plot (0,0,1,1) are what constrains the problem externally. Internally, the problem is constrained by relationships between the layoutboxes.

Tests:

These are in lib/matplotlib/tests/test_constrainedlayout.py.

PR Checklist

• Sort out padding in a non-figure unit
• Add legend to constrained objects
• Add kiwi to requirements: need a new release to make OK w/ 2.7. Current requirement works 3.6
• 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)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way
• Add suptitle to constrained objects
• sharex and sharey?
• Adjust spacing for colorbars; respect pad.
• Implement respect for wspace and hspace variables. Actually pretty easy.
• Check set_position axes
• Spacing between gridspecs
• gridspec width_ratios and height_ratios
• twinx, twiny? tight_layout puts axes title below twiny xlabel  #5474
• Extend to putting labels outside tick labels and titles outside of all?

[has2k1]

I am interested in the specifics of how the legend will be constrained. Perhaps through an easily extensible mechanism that can be used to add other AnchoredOffsetBox objects around axes and around gridspecs.

Also a mechanism for adding arbitrary text around the axes or gridspecs. This would be hand in adding captions to plots.

[jklymak]

@has2k1 Thanks.

I want to make sure I understand the desired behavior. We are getting into use cases I haven't ever needed for my personal plotting needs, so this is where I need help with what people envision.

Are you hoping that if I call ax.legend(loc='center left', bbox_to_anchor=(1., 0.5)) then the layout manager will automatically make the axis object to accommodate the legend inside the subplotspec? But it should also accept ax.legend(loc='center left', bbox_to_anchor=(0.5, 0.5))?

I think thats doable, but I need to think about how that gets implemented. Right now I just implement nested layouts and adjacent layouts w a pad. Arbitrarily displaced in axes co-ordinates is doable, but not implemented yet. I don't see why a subplotspec can't contain more than one child that also have displacements relative to their widths.

I need to dig into offsetbox to see how to make it extensible to other offset boxes. Can you point me to an example of other uses beyond legend so I can test?

[jklymak]

share_x and share_y are a bit complicated.

tight_layout differentiates between space between the subplots and the space around all the subplots (i.e. h_space and left). Here I don't, I just have left_margin and right_margin and they are the same for all subplots. So constrained_layout doesn't cover the often-used case of just labelling the outside rows and columns (it works, but it introduces a lot of extra white space between subplots).

As far as I can see share_x and share_y are only accessible via figure.subplots(). So, this isn't a problem for general gridspec-derived axes added with figure.add_axes.

See offsetbox.VPacker and offsetbox.HPacker for ideas.

[has2k1]

Are you hoping that if I call ax.legend(loc='center left', bbox_to_anchor=(1., 0.5)) then the layout manager will automatically make the axis object to accommodate the legend inside the subplotspec?

Yes.

But it should also accept ax.legend(loc='center left', bbox_to_anchor=(0.5, 0.5))?

Yes again. But I fear it would make the code complicated as it would mix two layout mechanisms. There are already four parameters to AnchoredOffsetbox that control the location, namely;

• loc
• bbox_to_anchor
• bbox_transform
• borderpad

And so it seems like AnchoredOffsetbox was designed in an environment that lacked a layout manager. With a layout manager in place, perhaps a new ConstrainedOffsetbox can also serve as a container for other Offsetboxes. But this course of action would conflict with the first question above. i.e does the legend still use AnchoredOffsetbox and never be accommodated inside the subplotspec? Or can it be changed to use the ConstrainedOffsetbox, with appropriately deprecated parameters? I have no good answer.

Plotnine extensively [1] uses offsetboxes for the legends and it has very finicky parts. Here is a simplified version that demonstrates a custom legend system similar to the one in plotnine.

[1] here, here, here and here

[jklymak]

@has2k1 Thanks a lot for the examples. That helps.

I think it'll be possible to have AnchoredOffsetbox (or a modified version) behavior the way you'd like. I can tackle this once I get sharex and sharey to work.

[jklymak]

@has2k1 this now makes space for legends. Since it actually queries the underlying _legend_box, which is an AnchoredBox, this is easily extensible to other cases. However, given that anchoredBox objects usually seem to be buried as implementation detail in other classes, my guess is the best thing is to have the checks on those classes rather than AnchoredBox directly. i.e. Legend isn't an AnchoredBox, but it uses one for its layout.

See layoutbox.get_axall_tightbbox for the logic here.

legend is a bit flakey as positions get set at the draw sequence, so for perversely large legends a resize is needed to make the legend fit properly. However, I think the method often yields a decent result.

[has2k1]

I think this would be more specific in sniffing out the legend type stuff.

possible_legends = ax.artists + [ax.legend_] if ax.legend_ else []
for child in possible_legends:
    if isinstance(child, (Legend, AnchoredOffsetbox)):
        ...

However, overall this is a neat little function that can bundle up all types of adornments to the axes (at the risk of complicating it).

[has2k1]

legend is a bit flakey as positions get set at the draw sequence, so for perversely large legends a resize is needed to make the legend fit properly. However, I think the method often yields a decent result.

I have encountered a related issue when creating an Animation class for plotnine. It may complicate animations, but on the whole specified figure sizes that are just rough estimates final sizes are a worthy price for a good layout. After all, tight_layout() has been an offender already.

[jklymak]

@has2k1 Note that OffsetBox children are already included in axes.get_tightbbox:

for child in self.get_children():
            if isinstance(child, OffsetBox) and child.get_visible():
                bb.append(child.get_window_extent(renderer))

It almost seems that Legend should be added to axes.get_tightbbox as a possible child that would expand the bbox.

See issue: #9130

[jklymak]

Removed [WIP]. I think this works, but I'm sure there are edge cases I haven't found.

[jklymak]

kiwisolver is now on pypi:: pip install kiwisolver installs 1.0.0 and works here. I'm not 100% sure how to incorporate it into the matplotlib setup.py as a dependency.

[jklymak]

@has2k1 Just to follow up on your legend examples above. Your first two examples work fine w/o any fiddling.

The third example, where you want a global legend doesn't work, and indeed makes the layout collapse in on itself. I'm not sure how to handle this, as you specify the anchored box in figure co-ordinates, but anchor it to one of your subplots, ax1. The constrained_layout then uses the whole area taken up by ax1 and the legend to determine the area the layout needs. That leaves no room for the other subplots, and the whole thing fails.

Right now I have "global" colorbars stacked to the right of the gridspec that contains the relevant subplot specs (or to the left, bottom etc). This is hard coded into colorbars.py. Similarly suptitle is stacked over the parent gridspec inside the figure container. However, it seems to me that something more generic might be a future enhancement. Maybe something like gs = GridSpec(2, 2), gs.stack_right(newartist, align='v_center'). This would take some thought, however, because what if I want to stack something else to the right of newartist?

[jklymak]

test_pickle fails because kiwisolver objects can't be pickled, and they are now attached to all the other objects.

[has2k1]

The way the plot in the third example is constructed need not be how it should be done. In fact, using figure coordinates is part of the problem.

Maybe something like gs = GridSpec(2, 2), gs.stack_right(newartist, align='v_center'). This would take some thought, however, because what if I want to stack something else to the right of newartist?
This is what I have had in mind too. The ability to stacking text and offsetboxes to the sides of the axes and the gridspec(s).

I have looked a little at what you currently have in place with the goal of making it extendable. i.e. For the
SubplotSpec, GridSpec and Figure layoutboxes, define regions to contain additional items (text & offsetboxes) for stacking.

           [top]
         ----------
        |          |
 [left] |          | [right]
        |          |
        |          |
         ----------
          [bottom]

[jklymak]

I have looked a little at what you currently have in place with the goal of making it extendable. i.e. For the SubplotSpec, GridSpec and Figure layoutboxes, define regions to contain additional items (text & offsetboxes) for stacking.

For SubplotSpec its pretty much done because it works on the difference between the spine position and the axes tightbbox, which includes AnchoredBoxes.

However, we'd need an API for the GridSpec level. So far, I've mostly just worked with the existing API. Actually implementing the stacking is pretty trivial: see suptitle or colorbar. I think adding an external API to layoutbox is a reasonable way to go. I think you'd want something like

• figlayout.gridspec_stack_right(gs, newartist)
• figlayout.gridspec_stack_bottom(gs, newartist), etc
  However, one could also imagine adding such an API to gridspec where it really belongs.

Edit: ...and do these artists then get layoutbox properties?

[jklymak]

@has2k1 How about this for an API:

Right now we can do ax.add_artist(anchored_box). I'd proposed we add a method to GridSpec so we can call: gs.add_anchoredbox(anchored_box) That would entail the GridSpec having a bbox, but that doesn't seem to onerous. I'm a little fuzzy on what bbox_transform will be required to make this relative to the gridspec box, but I think its doable.

That seems the most flexible, and consitent with an API folks will already know.

[has2k1]

Yes an API of the the form gs.add_anchoredbox(anchored_box) is simple and straight forward. I agree with the fuzziness around some of the parameters of the anchored_box. The solution may be a new offsetbox (the 2nd point)

A GridSpec that properly encloses an offsetbox of some kind will make composing/arranging multiple plots a lot easier. Packages that use MPL will get a lot more interesting, in fact this feature would rely on it.

[has2k1]

I am trying to get up to speed with what you have so far, but despite the plentiful comments I hit a road block on the do_constrained_layout function.

[jklymak]

@has2k1 Fair enough. I'll try and improve the comments. There may even be obsolete comments in there...

[has2k1]

I was hoping I could add comments from a third party perspective immediately after I understood what was going on.

[jklymak]

@has2k1 That would be fabulous. I just pushed a commit that improved a bit of the doc, and removed the obsolete document bits. Let me know if you have questions, or I can point you towards tests that show how the different parts work. It was all more subtle than I originally thought it would be.

[jklymak]

docs-python27 fails with a unicode error in kiwisolver. This is now fixed in nucleic/kiwi#40 kiwisolver/master, so this test should run.

The pickle test is always going to fail for matplotlib instances that attach kiwisolver variables because they can't be pickled. Does anyone use pickling with matpotlib? I admit I liked using pickle until I found out that its not compatible from py2.7 to py3.6 and I had to translate a bunch of old pickles.

I need to change the architecture to only attach kiwisolver variables if constrained_layout == True, and then just say that constrained_layout won't work with pickeled plots. Unless someone knows how to serialize kiwisolver variables.

[anntzer]

Haven't followed the discussion at all, but re: pickling, you can perhaps remove the kiwisolver instance at pickle time (we already to that e.g. in Figure.__getstate__ (or grep for __getstate__ through the codebase to see how this is done).

[tacaswell]

Does anyone use pickling with matpotlib?

Yes, a surprising number of people. When we break this we find out rapidly.

[jklymak]

Got it. Interesting interaction - I haven't played with interactive plotting much yet, except to change plot window size. This is clearly a bug in the set_aspect interaction. Hopefully not a big deal to fix...

[efiring]

I found another interactive glitch. Make a minimal plot:

fig, ax = plt.subplots(constrained_layout=True)
ax.set_xlabel('X label', fontsize=20)
ax.plot([0, 1])

Now click the zoom/pan button and fiddle with the view limits. Then click the home button. Now the constraint management is no longer in effect: reducing the window height by dragging up the bottom chops off the bottom of the legend.

[jklymak]

@efiring - thanks a lot - try the latest commit.

The second issue was some missed calls to ax.set_position that needed to be changed to ax._set_postion. Calling the former turns constrainedlayout off.

The first issue was that I was setting both positions when I set the position in constrained layout. Setting only the original is the way to go, and allows set_aspect to still do its thing.

[efiring]

Partial review. Nothing major.

[efiring]

should be fig.subplots. Is that the only one? If there are others, the "i.e." should be "e.g.".

[jklymak]

I can never remember the difference between i.e. and e.g. The failure of not teaching latin in high school any more...

[efiring]

Delete the "plt.figure".

[efiring]

Should these have leading underscores? Or are they intended to be part of the public API?

[jklymak]

Well, a) when I started, I didn't even know about _privatestuff, so this naming was in ignorance. b) afterwards, I kind of thought that there may be occasion the knowledgable user would want access to these. However, I think I agree that we don't want this to be public because it could change, so I'll set accordingly.

[efiring]

-> "externally"

[efiring]

Is there a reason for using setters instead of directly assigning to the attributes? This is related to my question about whether the attributes are part of the API.

[efiring]

The string could start on the line with the opening parenthesis.

[efiring]

I don't see gridspecfig being used in this function. And fig is not defined there, either. And the comment suggests that maybe this function should be deprecated, unless someone knows what the use case is.

[jklymak]

I'll remove the gridspecfig stuff. No idea about whether the fcn should be deprecated or not...

[anntzer]

no need to call %() yourself

[efiring]

Somehow the "do" grates on my aesthetic senses. Maybe "use" or "enable" or "active"? Regardless, the matplotlibrc.template also needs to be updated, since it presently has only "figure.constrainedlayout".
Also, since the kwarg is "constrained_layout", and that form (with underscore) seems prevalent (and readable), maybe the rcParam family name should match it. Unless we can think of something shorter... It's too bad "autolayout" is already used.

[jklymak]

• made the layoutbox objects private attributes of the various axes/figure/gridspec/subplotspec classes...

[jklymak]

squash + rebase

[has2k1]

The comments are minor issues mainly about style and and clarity.

One issue I have not commented on anywhere is the name generation for the layoutboxes. It may be clearer to have the names generated in one function maybe Layoutbox.make_name. The function would have an input type of layoutbox e.g 'subplotspec' then return a unique name. And if you store the type (or whatever suitable name) as a property. You can check on it with child.type == 'subplotspec'; this would limit the instances of +seq_id() and the splitting on dots as they are largely a distraction when reading the code.

The other nitpick is just an irritant, the dots after the numbers i.e 0., 1.. I'm not used to seeing them in python code.

[has2k1]

except KeyError

[has2k1]

You can use del state['_poslayoutbox']

[jklymak]

Is there an advantage? The other state calls are to pop().

[has2k1]

Other than the intention of the statement being clear. A pop() is effectively

def pop(self, key):
    value = self[key]
    del self[key]
    return value

[has2k1]

It does not look like gss uses any set properties.

[jklymak]

It saves me from checking if the gridspec is already in the list.

[has2k1]

Ahh I see, axes do not have a 1:1 relationship with gridspecs. Subtle way to handle it.

[has2k1]

For clarity I think hiding the naming conventions behind functions like is_subplotspec(child) and is_gridspec(child) would help.

[has2k1]

I think this whole block can be contained in the set_constrained_layout method.

[has2k1]

No need for padd parameter, you can use do set_constrained_layout_pads(**constrained).

[has2k1]

self.set_constrained_layout_pads(**constrained)

[jklymak]

Yeah, I didn't know about this construct until recently. I think its a bit obscure that you can specify kwarg dictionaries this way, but perhaps you are correct that we should just make this simpler and use only this form from the start.

[has2k1]

I think changing the signature of the method to set_constrained_layout_pads(self, w_pad=None, h_pad=None, ...), would make the logic below clearer.

[jklymak]

OK, I didn't quite get to setting those explicitly, because I wanted to have a for-loop over the possible kwargs, but I simplified as you suggested.

[has2k1]

Use del and except KeyError:

[jklymak]

.... except I kept state.pop just for consistency. If there is a good reason to del, I can easily change.

[jklymak]

The other nitpick is just an irritant, the dots after the numbers i.e 0., 1.. I'm not used to seeing them in python code.

I think if you don't do that in some languages you force integer arithmetic, which can be very unfortunate. i.e. 3./10. neq 3./10 Nice that doesn't happen in python, I'll try and find most instances and clean up.

[jklymak]

Thanks for the review @has2k1 I think I addressed most of your suggestions. Let me know about the pop/del thing.

[jklymak]

Rebase...

[tacaswell]

I'm going to make an executive decision and merge this

• It adds a major feature we have been talking about for years
• need to get lots of users to see where it breaks 😈
• is strictly opt-in
• mostly new code, unlikely to break anything

Thanks @jklymak and everyone who put effort into reviewing this (particularly @has2k1 , @anntzer and @efiring )!

[jklymak]

Thanks a lot everyone! Now here comes the bug reports... 🦆