Skip to content

[Doc]: Contour functions: auto-generated levels #24121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
martok opened this issue Oct 7, 2022 · 5 comments
Closed

[Doc]: Contour functions: auto-generated levels #24121

martok opened this issue Oct 7, 2022 · 5 comments
Labels
Documentation
Milestone
v3.6.2

Comments

@martok
Copy link
Contributor

martok commented Oct 7, 2022 •
edited
Loading

Documentation Link

https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.contourf.html
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.tricontourf.html

Problem

This applies to tricontour/f and contour/f.

The documentation of the contour functions' levels parameter states:

            If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries
            to automatically choose no more than *n+1* "nice" contour levels
            between *vmin* and *vmax*.

This is not true, the levels are always chosen betwen Z.min() and Z.max(). There is no way for the user to influence this when using the integer parameter variant. See implementation in contour.py: ContourSet._autolev().
Especially deceptive because the text as written is very much what one would expect, but that functionality does not exist (and never has).

Suggested improvement

Change "between vmin and vmax" to something like "in the data range" or more explicit "between minimum and maximum values of Z"
@timhoffm
Copy link
Member

timhoffm commented Oct 7, 2022

Thanks @martok. Do you want to make a pull request?

@jklymak
Copy link
Member

jklymak commented Oct 8, 2022

I think we should check if the docs were right at some point in the past though. Its possible we accidentally changed behaviour sometime recently? I haven't had time to check...

@oscargus
Copy link
Member

oscargus commented Oct 8, 2022

The doc-string came in #16534 where it was modified from

            If an int *n*, use *n* data intervals; i.e. draw *n+1* contour
            lines. The level heights are automatically chosen.

so it may indeed be that vmin and vmax are guesses (although possibly educated ones).

@martok
Copy link
Contributor Author

martok commented Oct 8, 2022

I think we should check if the docs were right at some point in the past though. Its possible we accidentally changed behaviour sometime recently? I haven't had time to check...

And I've traced it back through blames all the way since it was introduced in 2004, _autolev or its predecessors have always done the same thing.
But there was no cause for confusion before it gained norm support and later the vmin/max parameters in f5c85d8.

so it may indeed be that vmin and vmax are guesses (although possibly educated ones).

I mean, they're good guesses. Since vmin and vmax configure the norm they act as a kind of "implied zlim" for all other heatmap-style functions. Just not this one.

@martok martok mentioned this issue Oct 8, 2022
Merged
2 tasks
@timhoffm
Copy link
Member

timhoffm commented Oct 9, 2022

Closed by #24130

@timhoffm timhoffm closed this as completed Oct 9, 2022
@oscargus oscargus added this to the v3.6.2 milestone Oct 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.6.2
Development

No branches or pull requests
4 participants
@martok @jklymak @timhoffm @oscargus