[ENH]: subfigure_mosaic

[jennjwang]

Copied from matplotlib#25949

Problem

Recently I had a case of layouting subfigures where I could have benefitted from a subfigure_mosaic function, similar to subplot_mosaic.

Proposed solution

Provide subfigure_mosaic.
Bonus points if the implementation shares as much as possible with subplot_mosaic (I suspect we can just factor out everything and pass the "child-adding method" (fig.add_subplot or fig.add_subfigure) as a parameter to the internal implementation?).

[jennjwang]

Copied from matplotlib/matplotlib comment by @tacaswell

I think this is a good first issue (limited API discussion as "match subplot_mosaic" is going to be the answer) and only affects a very limited part of the codebase.

Labeling this as medium difficluty because the subplot_mosaic code is a bit complex (it supports infinite nesting of layouts via recursion) and some of the internal variables are not super clearly named (I named them).

The source is:

https://github.com/matplotlib/matplotlib/blob/82cfed34e2a54fcf450716deb6932af0c151395e/lib/matplotlib/figure.py#L1821-L2128

On a cursory skim, I think that https://github.com/matplotlib/matplotlib/blob/82cfed34e2a54fcf450716deb6932af0c151395e/lib/matplotlib/figure.py#L2081-L2087 is the only Axes-specific thing and parameterizin _do_layout to take make_the_sub_thing as an input would work.

One maybe interesting question is that for nested layouts to we want to have sub-figures of sub-figures or flatten all of the sub-figures to be children of the Figure they are called on? I think the return has to be flat so I would lean towards the implementation also being flat (with the nesting in the spec being a details of the layout not an expression of actual nesting) and if the user does really want sub-figure of sub-figure they can call subfigure_moasic in a loop to build up exactly the tree they want.

Tasks:

• understand how subplot_mosaic currently works
• refactor the layout logic into a private method
• pass the "make the thing" method through _do_layout
• add new FigureBase method subfigure_mosaic
• tests (lots of tests....should be able to adapt the subplot_mosaic tests)
• whats new entry (suspect that this is something people will be excited about so we want to highlight it)

software estimate are notoriously hard, but I would guess 4-20 hours with a bulk of the time being in writing tests and docs.

[jennjwang]

Copied from matplotlib/matplotlib comment by @anntzer

One maybe interesting question is that for nested layouts to we want to have sub-figures of sub-figures or flatten all of the sub-figures to be children of the Figure they are called on? I think the return has to be flat

Flat would seem normal to me.

[jennjwang]

Copied from matplotlib/matplotlib comment by @brandall25

Hi @tacaswell, I have some questions about the tasks you laid out.

When you say "refactor the layout logic into a private method", do you want that to be a private method of FigureBase that both subplot_mosaic and subfigure_mosaic can use?

Also, I'm a bit confused by the make_the_sub_thing parameter. Would this be add_subplot for subplot_mosaic and maybe add_subfigure for subfigure_mosaic?

Thanks!

[jennjwang]

Copied from matplotlib/matplotlib comment by @tacaswell

When you say "refactor the layout logic into a private method", do you want that to be a private method of FigureBase that both subplot_mosaic and subfigure_mosaic can use?

yes, or a class method, top level (private) function if it does not need any state. The main goal is to not have two copies of this somewhat long subtle code in the code base.

Would this be add_subplot for subplot_mosaic and maybe add_subfigure for subfigure_mosaic?

Yes, exactly that. The logic is "I need to add a sub-version of " which we can specify via dependency injection.

[tacaswell]

Hi! I'm a bit confused what is going on here, did you mean to open an issue on your fork of Matplotlib?

matplotlib#26061 and matplotlib#28508 are PRs attempting to implement it. If you want to pick up this work I suggest starting from 26061

[jennjwang]

Hi @tacaswell, so sorry for the confusion! My friends and I are testing whether AI use helps or hurts our productivity, so we picked a few beginner-friendly issues to try out from the original issue. Hope that's okay! we'll make sure any functional code gets merged back into the main branch