Improved handling of data ranges almost symmetrical about zero

rwpenney · rwpenney · commit 0ad43a52f2ad · 2021-10-21T16:57:46.000+01:00
diff --git a/examples/scales/asinh_demo.py b/examples/scales/asinh_demo.py
@@ -3,7 +3,8 @@
 Asinh Demo
 ============
 
-Illustration of the `asinh` axis scaling, which uses the transformation
+Illustration of the `asinh <.scale.AsinhScale>` axis scaling,
+which uses the transformation
 
 .. math::
 
@@ -22,12 +23,13 @@
 
     a \\rightarrow a_0 \\, {\\rm sgn}(a) \\ln |a| + {\\cal O}(1)
 
-As with the `symlog` scaling, this allows one to plot quantities
+As with the `symlog <.scale.SymmetricalLogScale>` scaling,
+this allows one to plot quantities
 that cover a very wide dynamic range that includes both positive
-and negative values. However, `symlog` involves a tranformation
+and negative values. However, ``symlog`` involves a transformation
 that has discontinuities in its gradient because it is built
 from *separate* linear and logarithmic transformations.
-The `asinh` scaling uses a transformation that is smooth
+The ``asinh`` scaling uses a transformation that is smooth
 for all (finite) values, which is both mathematically cleaner
 and should reduce visual artifacts associated with an abrupt
 transition between linear and logarithmic regions of the plot.
@@ -79,7 +81,7 @@
 # due to the gradient-discontinuity in "symlog":
 fig3 = plt.figure()
 ax = fig3.subplots(1, 1)
-r = 3 * np.tan(np.random.uniform(-np.pi / 2.01, np.pi / 2.01,
+r = 3 * np.tan(np.random.uniform(-np.pi / 2.02, np.pi / 2.02,
                                  size=(5000,)))
 th = np.random.uniform(0, 2*np.pi, size=r.shape)
 
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -496,7 +496,7 @@ class AsinhScale(ScaleBase):
     but for larger values (either positive or negative) it is asymptotically
     logarithmic. The transition between these linear and logarithmic regimes
     is smooth, and has no discontinuities in the function gradient
-    in contrast to the `symlog` scale.
+    in contrast to the `.SymmetricalLogScale` ("symlog") scale.
 
     Specifically, the transformation of an axis coordinate :math:`a` is
     :math:`a \\rightarrow a_0 \\sinh^{-1} (a / a_0)` where :math:`a_0`
diff --git a/lib/matplotlib/tests/test_ticker.py b/lib/matplotlib/tests/test_ticker.py
@@ -450,13 +450,21 @@ def test_init(self):
         assert lctr.numticks == 19
 
     def test_set_params(self):
-        lctr = mticker.AsinhLocator(linear_width=5, numticks=17)
+        lctr = mticker.AsinhLocator(linear_width=5,
+                                    numticks=17, symthresh=0.125)
         assert lctr.numticks == 17
+        assert lctr.symthresh == 0.125
+
         lctr.set_params(numticks=23)
         assert lctr.numticks == 23
         lctr.set_params(None)
         assert lctr.numticks == 23
 
+        lctr.set_params(symthresh=0.5)
+        assert lctr.symthresh == 0.5
+        lctr.set_params(symthresh=None)
+        assert lctr.symthresh == 0.5
+
     def test_linear_values(self):
         lctr = mticker.AsinhLocator(linear_width=100, numticks=11)
 
@@ -489,6 +497,28 @@ def test_fallback(self):
         assert_almost_equal(lctr.tick_values(100, 101),
                             np.arange(100, 101.01, 0.1))
 
+    def test_symmetrizing(self):
+        class DummyAxis:
+            bounds = (-1, 1)
+            @classmethod
+            def get_data_interval(cls): return cls.bounds
+
+        lctr = mticker.AsinhLocator(linear_width=1, numticks=3,
+                                    symthresh=0.25)
+        lctr.axis = DummyAxis
+
+        DummyAxis.bounds = (-1, 2)
+        assert_almost_equal(lctr(), [-1, 0, 2])
+
+        DummyAxis.bounds = (-1, 0.9)
+        assert_almost_equal(lctr(), [-1, 0, 1])
+
+        DummyAxis.bounds = (-0.85, 1.05)
+        assert_almost_equal(lctr(), [-1, 0, 1])
+
+        DummyAxis.bounds = (1, 1.1)
+        assert_almost_equal(lctr(), [1, 1.05, 1.1])
+
 
 class TestScalarFormatter:
     offset_data = [
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -2589,31 +2589,44 @@ class AsinhLocator(Locator):
     """
     An axis tick locator specialized for the inverse-sinh scale
 
-    This is very unlikely to have any use beyond the AsinhScale class.
+    This is very unlikely to have any use beyond
+    the `~.scale.AsinhScale` class.
     """
-    def __init__(self, linear_width, numticks=11):
+    def __init__(self, linear_width, numticks=11, symthresh=0.2):
         """
         Parameters
         ----------
         linear_width : float
             The scale parameter defining the extent
             of the quasi-linear region.
-        numticks : int, default: 12
+        numticks : int, default: 11
             The approximate number of major ticks that will fit
             along the entire axis
+        symthresh : float, default: 0.2
+            The fractional threshold beneath which data which covers
+            a range that is approximately symmetric about zero
+            will have ticks that are exactly symmetric.
         """
         super().__init__()
         self.linear_width = linear_width
         self.numticks = numticks
+        self.symthresh = symthresh
 
-    def set_params(self, numticks=None):
+    def set_params(self, numticks=None, symthresh=None):
         """Set parameters within this locator."""
         if numticks is not None:
             self.numticks = numticks
+        if symthresh is not None:
+            self.symthresh = symthresh
 
     def __call__(self):
         dmin, dmax = self.axis.get_data_interval()
-        return self.tick_values(dmin, dmax)
+        if (dmin * dmax) < 0 and abs(1 + dmax / dmin) < self.symthresh:
+            # Data-range appears to be almost symmetric, so round up:
+            bound = max(abs(dmin), abs(dmax))
+            return self.tick_values(-bound, bound)
+        else:
+            return self.tick_values(dmin, dmax)
 
     def tick_values(self, vmin, vmax):
         # Construct a set of "on-screen" locations
@@ -2622,9 +2635,9 @@ def tick_values(self, vmin, vmax):
                                                         / self.linear_width)
         ys = np.linspace(ymin, ymax, self.numticks)
         zero_dev = np.abs(ys / (ymax - ymin))
-        if (ymin * ymax) < 0 and min(zero_dev) > 1e-6:
+        if (ymin * ymax) < 0 and min(zero_dev) > 0:
             # Ensure that the zero tick-mark is included,
-            # if the axis stradles zero
+            # if the axis straddles zero
             ys = np.hstack([ys[(zero_dev > 0.5 / self.numticks)], 0.0])
 
         # Transform the "on-screen" grid to the data space:
