Skip to content

[ENH]: Figure.annotate #25998

Open
Open

Description

@anntzer

Problem

As shown by #22390 (use annotate() to draw arrows), #25905 (use annotate for subplot labeling), and #25993 (use annotate for rainbow text), annotate()/Annotation() has a really powerful API 1) to draw arrows and 2) to position itself.
To a large extent, this is useful not only for Axes-level artists but also for (Sub)Figure-level ones, so it would be nice to also have Figure.annotate() (and perhaps also plt.figannotate(), not that I really care), matching as much as possible the API of Axes.annotate. (Currently one can already manually create an Annotation and call Figure.add_artist to add it.)

I think the main (only?) things that Figure.annotate() cannot support are xycoords/textcoords="axes points"/"axes pixels"/"axes fraction"/"data", and thus the default value of xycoords should thus be "figure fraction" (matching Figure.text()) instead of "data".

Proposed solution

No response

Activity

  1. story645 commented on May 29, 2023

    @story645
    Member

    Could this replace ConnectionPatch in a lot of examples?

  2. jklymak commented on May 29, 2023

    @jklymak
    Member

    What are we annotating, if not axes elements? I'm leery about adding more figure-level methods as they tend to drift, so I'd like to better understand the proposal.

  3. anntzer commented on May 29, 2023

    @anntzer
    ContributorAuthor

    The naming is somewhat unfortunate, but that's more or less already the case with the proposal to make annotate() the "blessed" API to draw arrows: annotate() is really just a method to draw texts (and arrows) with support for advanced positioning semantics.

  4. story645 commented on May 29, 2023

    @story645
    Member

    annotate() is really just a method to draw texts (and arrows) with support for advanced positioning semantics

    I feel like this is what we debate every time we have the annotation/arrows discussion- annotate can also be thought of as method for doing advanced relative positioning of texts (and arrow) with support for passing through customization of texts and arrows, since we can point people to text and the not yet deprecated arrow for just texts and arrows and annotate is explicitly for the relative positioning.

    Which all to say is I think I have the same question as Jody, which is when exactly would this be used/what would it be used in place of?

  5. anntzer commented on May 29, 2023

    @anntzer
    ContributorAuthor

    A real example of use case would be the equivalent of #25905, namely put some text at a corner of a (sub)figure, offset by some multiple of the fontsize (e.g., instructions for an interactive figure like "select data points then press enter to trigger processing").
    Currently the usual approach is probably to do fig.text(.05, .05, "foo") and rely on the fact that positioning the text at 5%-5% of the figure is more or less OK (for bottom left), but that suffers from the same imperfections as ax.text(.05, .05, "foo", transform=ax.transAxes) (the positioning becomes awkward if the figure has an aspect ratio very far from 1, for example) which lead to the use of annotate() in #25905.


    Note that even as of now, in practice, one can also do fig.axes[0].annotate(..., figure=fig.transFigure), which in practice does what I want, except that this requires the figure to have at least an axes associated to it, and parents the annotation to that axes rather than to the figure, which may be semantically wrong.

  6. story645 commented on Aug 23, 2024

    @story645
    Member

    Which all to say is I think I have the same question as Jody, which is when exactly would this be used/what would it be used in place of?

    Answered my own question w/ #28753, which is that this is probably the easiest way to do colored fig titles and also nice for diagrams that span the whole figure.

    ETA: also this is what @anntzer said up top that I didn't catch the first time, sorry 🤦‍♀️

    Basically+1 from me for adding this

  7. linked a pull request that will close this issueENH: fig.annotate #28753on Jan 24, 2025
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

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions