Merge pull request matplotlib#24132 from greglucas/centered-norm

API: CenteredNorm changes

Author: tacaswell

doc/api/next_api_changes/behavior/24132-GL.rst

@@ -0,0 +1,29 @@
+``CenteredNorm`` halfrange is not modified when vcenter changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, the **halfrange** would expand in proportion to the
+amount that **vcenter** was moved away from either **vmin** or **vmax**.
+Now, the halfrange remains fixed when vcenter is changed, and **vmin** and
+**vmax** are updated based on the **vcenter** and **halfrange** values.
+
+For example, this is what the values were when changing vcenter previously.
+
+.. code-block::
+
+    norm = CenteredNorm(vcenter=0, halfrange=1)
+    # Move vcenter up by one
+    norm.vcenter = 1
+    # updates halfrange and vmax (vmin stays the same)
+    # norm.halfrange == 2, vmin == -1, vmax == 3
+
+and now, with that same example
+
+.. code-block::
+
+    norm = CenteredNorm(vcenter=0, halfrange=1)
+    norm.vcenter = 1
+    # updates vmin and vmax (halfrange stays the same)
+    # norm.halfrange == 1, vmin == 0, vmax == 2
+
+The **halfrange** can be set manually or ``norm.autoscale()``
+can be used to automatically set the limits after setting **vcenter**.

lib/matplotlib/colors.py

@@ -1517,28 +1517,44 @@ def __init__(self, vcenter=0, halfrange=None, clip=False):
         # calling the halfrange setter to set vmin and vmax
         self.halfrange = halfrange
 
-    def _set_vmin_vmax(self):
-        """
-        Set *vmin* and *vmax* based on *vcenter* and *halfrange*.
-        """
-        self.vmax = self._vcenter + self._halfrange
-        self.vmin = self._vcenter - self._halfrange
-
     def autoscale(self, A):
         """
         Set *halfrange* to ``max(abs(A-vcenter))``, then set *vmin* and *vmax*.
         """
         A = np.asanyarray(A)
-        self._halfrange = max(self._vcenter-A.min(),
-                              A.max()-self._vcenter)
-        self._set_vmin_vmax()
+        self.halfrange = max(self._vcenter-A.min(),
+                             A.max()-self._vcenter)
 
     def autoscale_None(self, A):
         """Set *vmin* and *vmax*."""
         A = np.asanyarray(A)
-        if self._halfrange is None and A.size:
+        if self.halfrange is None and A.size:
             self.autoscale(A)
 
+    @property
+    def vmin(self):
+        return self._vmin
+
+    @vmin.setter
+    def vmin(self, value):
+        value = _sanitize_extrema(value)
+        if value != self._vmin:
+            self._vmin = value
+            self._vmax = 2*self.vcenter - value
+            self._changed()
+
+    @property
+    def vmax(self):
+        return self._vmax
+
+    @vmax.setter
+    def vmax(self, value):
+        value = _sanitize_extrema(value)
+        if value != self._vmax:
+            self._vmax = value
+            self._vmin = 2*self.vcenter - value
+            self._changed()
+
     @property
     def vcenter(self):
         return self._vcenter
@@ -1547,32 +1563,24 @@ def vcenter(self):
     def vcenter(self, vcenter):
         if vcenter != self._vcenter:
             self._vcenter = vcenter
+            # Trigger an update of the vmin/vmax values through the setter
+            self.halfrange = self.halfrange
             self._changed()
-        if self.vmax is not None:
-            # recompute halfrange assuming vmin and vmax represent
-            # min and max of data
-            self._halfrange = max(self._vcenter-self.vmin,
-                                  self.vmax-self._vcenter)
-            self._set_vmin_vmax()
 
     @property
     def halfrange(self):
-        return self._halfrange
+        if self.vmin is None or self.vmax is None:
+            return None
+        return (self.vmax - self.vmin) / 2
 
     @halfrange.setter
     def halfrange(self, halfrange):
         if halfrange is None:
-            self._halfrange = None
             self.vmin = None
             self.vmax = None
         else:
-            self._halfrange = abs(halfrange)
-
-    def __call__(self, value, clip=None):
-        if self._halfrange is not None:
-            # enforce symmetry, reset vmin and vmax
-            self._set_vmin_vmax()
-        return super().__call__(value, clip=clip)
+            self.vmin = self.vcenter - abs(halfrange)
+            self.vmax = self.vcenter + abs(halfrange)
 
 
 def make_norm_from_scale(scale_cls, base_norm_cls=None, *, init=None):

lib/matplotlib/tests/test_colorbar.py

@@ -1060,6 +1060,17 @@ def test_negative_boundarynorm():
     np.testing.assert_allclose(cb.ax.get_yticks(), clevs)
 
 
+def test_centerednorm():
+    # Test default centered norm gets expanded with non-singular limits
+    # when plot data is all equal (autoscale halfrange == 0)
+    fig, ax = plt.subplots(figsize=(1, 3))
+
+    norm = mcolors.CenteredNorm()
+    mappable = ax.pcolormesh(np.zeros((3, 3)), norm=norm)
+    fig.colorbar(mappable)
+    assert (norm.vmin, norm.vmax) == (-0.1, 0.1)
+
+
 @image_comparison(['nonorm_colorbars.svg'], style='mpl20')
 def test_nonorm():
     plt.rcParams['svg.fonttype'] = 'none'

lib/matplotlib/tests/test_colors.py

@@ -485,11 +485,25 @@ def test_CenteredNorm():
     norm(np.linspace(-1.0, 0.0, 10))
     assert norm.vmax == 1.0
     assert norm.halfrange == 1.0
-    # set vcenter to 1, which should double halfrange
+    # set vcenter to 1, which should move the center but leave the
+    # halfrange unchanged
     norm.vcenter = 1
-    assert norm.vmin == -1.0
-    assert norm.vmax == 3.0
-    assert norm.halfrange == 2.0
+    assert norm.vmin == 0
+    assert norm.vmax == 2
+    assert norm.halfrange == 1
+
+    # Check setting vmin directly updates the halfrange and vmax, but
+    # leaves vcenter alone
+    norm.vmin = -1
+    assert norm.halfrange == 2
+    assert norm.vmax == 3
+    assert norm.vcenter == 1
+
+    # also check vmax updates
+    norm.vmax = 2
+    assert norm.halfrange == 1
+    assert norm.vmin == 0
+    assert norm.vcenter == 1
 
 
 @pytest.mark.parametrize("vmin,vmax", [[-1, 2], [3, 1]])