Skip to content

[Doc]: get_figure may return a SubFigure #28170

Closed

Description

@rcomer

Documentation Link

https://matplotlib.org/devdocs/api/_as_gen/matplotlib.artist.Artist.get_figure.html#matplotlib.artist.Artist.get_figure

Problem

I'm not sure whether this is a documentation issue or a bug. The docstring for get_figure states that it returns a Figure, which I think implies the parent figure. If our artist is on a subfigure, it will return that. Note that SubFigure does not inherit from Figure.

In [1]: import matplotlib.pyplot as plt

In [2]: fig = plt.figure()

In [3]: sfig = fig.subfigures()

In [4]: ax = sfig.subplots()

In [5]: ax.get_figure()
Out[5]: <matplotlib.figure.SubFigure at 0x7dc0ddf4a870>

Suggested improvement

Either

  • modify the docstring to clarify you might get the SubFigure (and point to how you can get the parent Figure if you want it)
    or
  • fix the method so it returns the parent Figure

Activity

  1. rcomer commented on May 4, 2024

    @rcomer
    MemberAuthor

    SubFigure.get_figure does return a Figure, even if the subfigures are nested.

    In [6]: sfig2 = sfig.subfigures()
    
    In [7]: sfig2.get_figure()
    Out[7]: <Figure size 640x480 with 1 Axes>
  2. timhoffm commented on May 4, 2024

    @timhoffm
    Member

    This seems inconsistent and likely we haven't thought about it when subfigures were introduced.

    Intuitively, I'd recommend the following behavior: get_figure() returns the closest (sub)figure. If we were to go all the way up, it's not possible to get to the next level only.

    That would imply:

    • Change documentation/typing of Artist.get_figure
    • Change behavior of Subfigure.get_figure to return the containing (sub)figure. - Note that get_figure only returns self.figure, so self.figure should be changed for nested subfigures. I consider it a bug that this is not the containing subfigure. @jklymak do you agree?
  3. jklymak commented on May 4, 2024

    @jklymak
    Member

    Hmm that seems inconsistent at least so one way or another is a bug

    It seems that a subfigure wants to know its parent rather than its root?

    Ooops sorry crosspost w above. I'd have to look at the code a bit.

  4. jklymak commented on May 5, 2024

    @jklymak
    Member

    This seems inconsistent and likely we haven't thought about it when subfigures were introduced.

    Intuitively, I'd recommend the following behavior: get_figure() returns the closest (sub)figure. If we were to go all the way up, it's not possible to get to the next level only.

    That would imply:

    • Change documentation/typing of Artist.get_figure
    • Change behavior of Subfigure.get_figure to return the containing (sub)figure. - Note that get_figure only returns self.figure, so self.figure should be changed for nested subfigures. I consider it a bug that this is not the containing subfigure. @jklymak do you agree?

    Hmmm, I fear it's not so simple. I explicitly set self.figure = parent.figure which therefore resolves to the root figure, and I think that is because artists have things like self.figure.stale and self.figure.suppressComposite which would somehow have to magically thread themselves through.

    So I wonder if the correct course of action is to override get_figure to return the parent figure, but keep self.figure as-is. In hindsight, it should have been private, I think?

  5. timhoffm commented on May 5, 2024

    @timhoffm
    Member

    So I wonder if the correct course of action is to override get_figure to return the parent figure, but keep self.figure as-is. In hindsight, it should have been private, I think?

    It's bad enough that we have a mixture of attributes and getters, having both with slightly different semantics is even worse. I propse to

    • expand get_figure() with a parmeter to select between the direct parent and the top-level figure, choosing the appropriate default. - The default should become the same for artists and subfigures, which means an API change for one of them.
    • create whatever internal state is necessary to support the behavior (likely self._parent_figure)
    • keep self.figure with the current semantics, but discourate (deprecate?) it's use in favor of get_figure() - if needed turn it into a property.
  6. jklymak commented on May 5, 2024

    @jklymak
    Member

    The above seems good to me.
    Something like:

    get_figure(root=False)
    
    root : bool
        If False return the (Sub)Figure this artist is on.  If True, return the root Figure if there is a nested tree of SubFigures.
    
  7. tacaswell commented on May 6, 2024

    @tacaswell
    Member

    Ah, this also make sense as to why the subfigure_mosaic has problems with getting the nesting right.

    Strongly agree we need a version that gets the parent rather than the root.

  8. anntzer commented on Jun 26, 2024

    @anntzer
    Contributor

    keep self.figure with the current semantics, but discourate (deprecate?) it's use in favor of get_figure() - if needed turn it into a property.

    FWIW deprecating .figure would be extremely disruptive for me -- I use this API all the time, typically because I only keep track of axes, and go back to the figure as needed via ax.figure...

  9. added this to the v3.10.0 milestone on Jul 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions