From 44c1dd4c81ac3350dc6776e6ee1a3f848d48e42c Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Thu, 22 Jan 2026 18:41:36 +0530 Subject: [PATCH 1/9] Doc: Clarify default levels behavior in contour/contourf Explicitly state that the default levels corresponds to n=7 and clarifies that int input targets n+1 levels but may produce n+2. --- lib/matplotlib/contour.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index dfc39ed664f9..501e4c906806 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1485,13 +1485,17 @@ def _initialize_x_y(self, z): levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - - If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries - to automatically choose no more than *n+1* "nice" contour levels - between minimum and maximum numeric values of *Z*. - + + If an int *n*, use `~matplotlib.ticker.MaxNLocator` to automatically + choose approximately *n+1* "nice" contour levels between the minimum + and maximum values of *Z*. Note that the actual number may be up to + *n+2* depending on the data range. + If array-like, draw contour lines at the specified levels. The values must be in increasing order. + + If not specified, behaves as if ``levels=7`` was passed, typically + producing approximately 8 contour levels. Returns ------- From e64f5eb21e1b15bdc3c3daf39148e98795435964 Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Thu, 22 Jan 2026 18:49:42 +0530 Subject: [PATCH 2/9] Precommit fix --- lib/matplotlib/contour.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 501e4c906806..71a0ab01138e 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1485,16 +1485,17 @@ def _initialize_x_y(self, z): levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - - If an int *n*, use `~matplotlib.ticker.MaxNLocator` to automatically - choose approximately *n+1* "nice" contour levels between the minimum - and maximum values of *Z*. Note that the actual number may be up to - *n+2* depending on the data range. - + + If an int *n*, use `~.ticker.MaxNLocator`, which tries to + automatically choose approximately *n+1* "nice" contour levels + between minimum and maximum numeric values of Z. Note that this + locator optimizes for "nice" intervals, so the actual number of + levels may be up to *n+2* depending on the data range. + If array-like, draw contour lines at the specified levels. The values must be in increasing order. - - If not specified, behaves as if ``levels=7`` was passed, typically + + If not specified, the default corresponds to *n=7*, typically producing approximately 8 contour levels. Returns From d81ca524175686be68b70477cfe56a76cdf9c3db Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Tue, 27 Jan 2026 13:41:33 +0530 Subject: [PATCH 3/9] Update contour.py --- lib/matplotlib/contour.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 71a0ab01138e..cb1f6b145145 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1486,17 +1486,18 @@ def _initialize_x_y(self, z): levels : int or array-like, optional Determines the number and positions of the contour lines / regions. - If an int *n*, use `~.ticker.MaxNLocator`, which tries to + If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to automatically choose approximately *n+1* "nice" contour levels - between minimum and maximum numeric values of Z. Note that this - locator optimizes for "nice" intervals, so the actual number of - levels may be up to *n+2* depending on the data range. + between the minimum and maximum numeric values of *Z*. Note that the + actual number may be up to *n+2* depending on the data range. If array-like, draw contour lines at the specified levels. The values must be in increasing order. - - If not specified, the default corresponds to *n=7*, typically - producing approximately 8 contour levels. + + If not given, a reasonable default is automatically chosen. For linear + scales, this corresponds to *n*=7, typically producing approximately + 8 contour levels. For logarithmic scales, `~matplotlib.ticker.LogLocator` + is used instead. Returns ------- From 397629ed8726d1610996de9f73ef79c6ebab2300 Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Tue, 27 Jan 2026 14:13:54 +0530 Subject: [PATCH 4/9] Update contour.py --- lib/matplotlib/contour.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index cb1f6b145145..0e93f87a245d 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1493,7 +1493,7 @@ def _initialize_x_y(self, z): If array-like, draw contour lines at the specified levels. The values must be in increasing order. - + If not given, a reasonable default is automatically chosen. For linear scales, this corresponds to *n*=7, typically producing approximately 8 contour levels. For logarithmic scales, `~matplotlib.ticker.LogLocator` From 787c773010ae4f8a6cfcb4116e4e3b757dc3e0eb Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Tue, 27 Jan 2026 19:17:51 +0530 Subject: [PATCH 5/9] Update contour.py --- lib/matplotlib/contour.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 0e93f87a245d..182c0c46e649 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1487,17 +1487,16 @@ def _initialize_x_y(self, z): Determines the number and positions of the contour lines / regions. If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to - automatically choose approximately *n+1* "nice" contour levels - between the minimum and maximum numeric values of *Z*. Note that the - actual number may be up to *n+2* depending on the data range. + automatically choose no more than *n+2* "nice" contour levels + between the minimum and maximum numeric values of *Z*. If array-like, draw contour lines at the specified levels. The values must be in increasing order. If not given, a reasonable default is automatically chosen. For linear - scales, this corresponds to *n*=7, typically producing approximately - 8 contour levels. For logarithmic scales, `~matplotlib.ticker.LogLocator` - is used instead. + scales, `~matplotlib.ticker.MaxNLocator` is used with *nbins*=8, + producing up to 9 "nice" contour levels. For logarithmic scales, + `~matplotlib.ticker.LogLocator` is used instead. Returns ------- From 1cd62559dc9a3c72a16f5371a0ad61bb32a09577 Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Sun, 1 Feb 2026 17:05:02 +0530 Subject: [PATCH 6/9] DOC: Clarify contour levels parameter as boundaries to fix ambiguity The previous documentation stated that `MaxNLocator` chooses "no more than n+1" levels, which was mathematically incorrect for the default case (n=7 produces 9 levels). Additionally, the distinction between `contour` (lines) and `contourf` (filled regions) created confusion, as `contourf` produces one fewer region than the number of lines (unless `extend` is used). This update redefines `levels` strictly as "contour boundaries." This terminology: 1. Is accurate for both functions (lines are at boundaries, regions are between them). 2. Remains correct regardless of the `extend` parameter. 3. Explicitly documents the default behavior for n=7. --- lib/matplotlib/contour.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 182c0c46e649..3873415ccf47 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1487,15 +1487,17 @@ def _initialize_x_y(self, z): Determines the number and positions of the contour lines / regions. If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to - automatically choose no more than *n+2* "nice" contour levels - between the minimum and maximum numeric values of *Z*. + automatically choose no more than *n+2* "nice" contour level boundaries + between the minimum and maximum numeric values of *Z*. These boundaries + define where lines are drawn (for `contour`) or where filled regions + are separated (for `contourf`). If array-like, draw contour lines at the specified levels. The values must be in increasing order. - If not given, a reasonable default is automatically chosen. For linear - scales, `~matplotlib.ticker.MaxNLocator` is used with *nbins*=8, - producing up to 9 "nice" contour levels. For logarithmic scales, + If not specified, a reasonable default is automatically chosen. For + linear scales, this corresponds to *n=7* (using `~.ticker.MaxNLocator(8)`), + producing up to 9 "nice" contour boundaries. For logarithmic scales, `~matplotlib.ticker.LogLocator` is used instead. Returns From d528659b621e2844191351da95c0b77acdfac423 Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Sun, 1 Feb 2026 18:05:59 +0530 Subject: [PATCH 7/9] Update contour.py --- lib/matplotlib/contour.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 3873415ccf47..9a1e6c4170ed 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1496,7 +1496,7 @@ def _initialize_x_y(self, z): The values must be in increasing order. If not specified, a reasonable default is automatically chosen. For - linear scales, this corresponds to *n=7* (using `~.ticker.MaxNLocator(8)`), + linear scales, this corresponds to *n=7* (using `~.ticker.MaxNLocator` with *nbins=8*), producing up to 9 "nice" contour boundaries. For logarithmic scales, `~matplotlib.ticker.LogLocator` is used instead. From 80fc2de26a1d03f3b469980e6dcf80480ad40192 Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Sun, 1 Feb 2026 18:38:23 +0530 Subject: [PATCH 8/9] Update contour.py --- lib/matplotlib/contour.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 9a1e6c4170ed..eda584e853ff 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1496,9 +1496,9 @@ def _initialize_x_y(self, z): The values must be in increasing order. If not specified, a reasonable default is automatically chosen. For - linear scales, this corresponds to *n=7* (using `~.ticker.MaxNLocator` with *nbins=8*), - producing up to 9 "nice" contour boundaries. For logarithmic scales, - `~matplotlib.ticker.LogLocator` is used instead. + linear scales, this corresponds to *n=7* (using `~.ticker.MaxNLocator` + with *nbins=8*), producing up to 9 "nice" contour boundaries. For + logarithmic scales, `~matplotlib.ticker.LogLocator` is used instead. Returns ------- From 5ff02f0dfd57cd1aedf447ac78d49da312a8bb6b Mon Sep 17 00:00:00 2001 From: Sanchit Rishi Date: Mon, 2 Feb 2026 13:37:16 +0530 Subject: [PATCH 9/9] Update lib/matplotlib/contour.py Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- lib/matplotlib/contour.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index eda584e853ff..0cf49514acc7 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1496,9 +1496,8 @@ def _initialize_x_y(self, z): The values must be in increasing order. If not specified, a reasonable default is automatically chosen. For - linear scales, this corresponds to *n=7* (using `~.ticker.MaxNLocator` - with *nbins=8*), producing up to 9 "nice" contour boundaries. For - logarithmic scales, `~matplotlib.ticker.LogLocator` is used instead. + linear scales, this corresponds to *levels=7*. For logarithmic + scales, `~matplotlib.ticker.LogLocator` is used instead. Returns -------