Skip to content

[MNT]: Define Axes.clear semantics #28851

Open

Description

@timhoffm

Summary

Axes.clear() / Axes.cla() are only documented as "Clear the Axes". What exactly "clear" means is neither documented nor well defined. We reset some stuff and keep other.

This leads to a number of issues:

There has been some inital work in #23839, but the topic is not completely solved.

Proposed fix

We need to define what clear means.

First on an abstract level: This could be a starting point:

  • All data-like content should be removed (actual data, labels, etc.)
  • Scales and limits should be reset
  • Layout should stay (axes position, twinning)
  • Formatting: t.b.d.

When the high-level definition is agreed upon, we need to define what that means for concrete cases.
e.g. it's clear that we remove label content. Should label positions also be reset (e.g. if somebody has moved the xlabel to top)? - This may also depend on the anticipated use case: One wants to reuse the Axes for a new plot. How similar is it to the old plot. Does it only get new data and labels or could it be a completely different plot?

Activity

  1. anntzer commented on Sep 24, 2024

    @anntzer
    Contributor

    Also related to #12819 / #23503 ("Should clearing a shared axes reset its scale?")


    In fact, thinking about this again, I suspect that "having a consistent behavior when only one of a shared axes is cleared" would more or less impose some choices:

    • clearing should not reset the scale (because the shared axes should keep its scale).
    • clearing should not reset the limits (because the shared axes should keep its limits).

    However! this causes other problems, namely that after clearing, the cached data limits become completely wrong. I would guess the "proper" fix there would be the "lazy datalims" idea floated at #28101 (comment).

  2. timhoffm commented on Jul 21, 2025

    @timhoffm
    MemberAuthor

    I think there's a fundamental contradiction for clearing on of a shared axes:

    1. Sharing should not be removed, as that's part of the layout.
    2. Scale and limits should generally be reset for axes.

    We cannot satisfy both. The synchonization with the shared axes prevents restting scale and limits. While we can work around this with "lazy datalims" for limits. The issue persists for the scale. Just keeping the scale is also not great because two shared Axes would mutually block resetting the scale; i.e. even when clearing all Axes, we cannot reset the scale. All possible solutions would require substantial changes to the architecture.


    Edit: Maybe the right way to go about this is making it possible to un-share and re-share axes. Then, un-share > clear > re-share has well-defined semantics.

  3. timhoffm commented on Mar 26, 2026

    @timhoffm
    MemberAuthor

    Semi-OT: from #28268 clearing should not remove twinning of axes (and for that matter sharing related to these)

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