Repository navigation
[Doc]: Contour functions: auto-generated levels #24121
Description
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"
Activity
timhoffm commented on Oct 7, 2022
Thanks @martok. Do you want to make a pull request?
jklymak commented on 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 commented on 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 commented on Oct 8, 2022
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.
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.
timhoffm commented on Oct 9, 2022
Closed by #24130