Skip to content

[Doc]: Better document Axes.transData and other transXYZ attributes #25220

Closed

Description

@timhoffm

Documentation Link

No response

Problem

It's documented in the tutorial https://matplotlib.org/stable/tutorials/advanced/transforms_tutorial.html#data-coordinates, but not very discoverable:

Problem: transData and the likes are only attributes set in a [private function]/(

self.transData = self.transScale + (self.transLimits + self.transAxes)
)
As such, they do not have a docstring and do not appear in the API documentation.

Suggested improvement

Action: Find out, how to make this available in the API docs at https://github.com/matplotlib/matplotlib/blob/main/doc/api/axes_api.rst

Worth checking:

Alternative: Turn the trans* attributes into properties. They can be documented properly and have the advantage of being read-only. This is a slight performance cost, but should be negligible compared to any action involving the transforms.

Activity

  1. tacaswell commented on Feb 15, 2023

    @tacaswell
    Member

    I think using a pattern like in #25187 to document class attributes (defaulting to None) might work as well?

  2. timhoffm commented on Feb 15, 2023

    @timhoffm
    MemberAuthor

    That pattern would work but feels a bit contrived. The class attributes are None and exist only for the purpose of documentation. Upon instance initialization they are immediately shadowed by instance attributes.

    I'm leaning towards turning these into properties, because they are read-only.

  3. mwaskom commented on Feb 17, 2023

    @mwaskom

    Better docs for the transforms would be great but fwiw I’m fairly certain the insights page counts all searches and then labels them with the most recent search, rather than showing the count for a specific query.

  4. AnanasClassic commented on Mar 30, 2023

    @AnanasClassic

    I would like to take up this issue

  5. ksunden commented on May 19, 2023

    @ksunden
    Member

    Properties probably make sense, especially if we want setting to be private behavior...

    In the alternative, I do think that if we want to go the "class attribute" route, I'm not super happy with = None, as that introduces a different type that is not actually valid for any instance. Pep 526 allows a pure declaration (without initialization, but you have to put the type hint in... This is slightly odd in a setting where the actual type hints are in a parallel file, but it should work:

    class AxesBase(...):
        ...
        transData: Transform
        """Docstring"""
        ...

    This is a declaration that transData will exist and have type Transform, but I don't have an initial value yet (it will still actually give AttributeError if accessed before it is initialized)
    I do think that all of the transXYZ transforms from that method should be documented, not only transData, as well.

  6. AnanasClassic commented on May 19, 2023

    @AnanasClassic

    maybe it is acceptable to initialize transData some default Transform-object ?

  7. AnanasClassic commented on May 19, 2023

    @AnanasClassic

    I think in order to document all the attributes, we need to create a new issue

  8. changed the title [-][Doc]: Better document Axes.transData[/-] [+][Doc]: Better document Axes.transData and other transXYZ attributes[/+] on May 19, 2023
  9. tacaswell commented on May 19, 2023

    @tacaswell
    Member

    I have updated this issue to cover all the transfrom attributes.

  10. AnanasClassic commented on May 21, 2023

    @AnanasClassic

    Do you have any ideas how to document this?
    I think I can write something like

    @property
    def get_trans_data(self):
        """docstring"""
        return self.transData
    

    But I'm afraid that in this case the clarity of the documentation will suffer

    Or I can initialize transXYZ with default values (I don't quite understand what values to initialize them with)

  11. timhoffm commented on May 21, 2023

    @timhoffm
    MemberAuthor

    You should make the current attribute private self._transData and use the original name as a read-only accessor

    @property
    def transData(self):
        “””docstring”””
        return self._transData
    
  12. github-actions commented on Jul 6, 2026

    @github-actions

    This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

  13. timhoffm commented on Jul 6, 2026

    @timhoffm
    MemberAuthor

    Minimal documentation should be added docs to type annotations in AxesBase, like we do for dataLim and spines (note: viewLim is different as it's not an attribute but actually a lazily computed quantity via a property; but for simple attributes we don't want to property overhead just for docs purpose).

    I will take care of this.

  14. self-assigned this
    on Jul 6, 2026
  15. added a commit that references this issue on Jul 9, 2026
    b8c7626
  16. added this to the v3.11.1 milestone on Jul 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions