Improved documentation of asinh transformation and parameter naming

Author: rwpenney

examples/scales/asinh_demo.py

@@ -25,16 +25,34 @@
 ax1.set_title(r'$sinh^{-1}$')
 
 
-# Compare "asinh" graphs with different scale parameter "a0":
+# Compare "asinh" graphs with different scale parameter "linear_width":
 fig2 = plt.figure()
 axs = fig2.subplots(1, 3, sharex=True)
 for ax, a0 in zip(axs, (0.2, 1.0, 5.0)):
-    ax.set_title('a0={:.3g}'.format(a0))
+    ax.set_title('linear_width={:.3g}'.format(a0))
     ax.plot(x, x, label='y=x')
     ax.plot(x, 10*x, label='y=10x')
     ax.plot(x, 100*x, label='y=100x')
-    ax.set_yscale('asinh', a0=a0)
+    ax.set_yscale('asinh', linear_width=a0)
     ax.grid()
     ax.legend(loc='best', fontsize='small')
 
+
+# Compare "symlog" and "asinh" scalings
+# on 2D Cauchy-distributed random numbers:
+fig3 = plt.figure()
+ax = fig3.subplots(1, 1)
+r = numpy.tan(numpy.random.uniform(-numpy.pi / 2.02, numpy.pi / 2.02,
+                                   size=(5000,)))
+th = numpy.random.uniform(0, 2*numpy.pi, size=r.shape)
+
+ax.scatter(r * numpy.cos(th), r * numpy.sin(th), s=4, alpha=0.5)
+ax.set_xscale('asinh')
+ax.set_yscale('symlog')
+ax.set_xlabel('asinh')
+ax.set_ylabel('symlog')
+ax.set_title('2D Cauchy random deviates')
+ax.grid()
+
+
 plt.show()

lib/matplotlib/scale.py

@@ -467,75 +467,85 @@ class AsinhScale(ScaleBase):
     logarithmic. The transition between these linear and logarithmic regimes
     is smooth, and has no discontinutities in the function gradient
     in contrast to the "symlog" scale.
+
+    Specifically, the transformation of an axis coordinate :math:`a` is
+    is :math:`a \\rightarrow a_0 \sinh^{-1} (a / a_0)` where :math:`a_0`
+    is the effective width of the linear region of the transformation.
+    In that region, the transformation is
+    :math:`a \\rightarrow a + {\cal O}(a^3)`.
+    For large values of :math:`a` the transformation behaves as
+    :math:`a \\rightarrow a_0 \ln (a) + {\cal O}(1)`.
     """
 
     name = 'asinh'
 
-    def __init__(self, axis, *, a0=1.0, **kwargs):
+    def __init__(self, axis, *, linear_width=1.0, **kwargs):
         """
         Parameters
         ----------
-        a0 : float, default: 1
-            The scale parameter defining the extent of the quasi-linear region.
+        linear_width : float, default: 1
+            The scale parameter defining the extent of the quasi-linear region,
+            and the coordinate values beyond which the transformation
+            becomes asympoticially logarithmic.
         """
         super().__init__(axis)
-        if a0 <= 0.0:
+        if linear_width <= 0.0:
             raise ValueError("Scale parameter 'a0' must be strictly positive")
-        self.a0 = a0
+        self.linear_width = linear_width
 
     def get_transform(self):
-        return self.AsinhTransform(self.a0)
+        return self.AsinhTransform(self.linear_width)
 
     def set_default_locators_and_formatters(self, axis):
-        axis.set(major_locator=AsinhScale.AsinhLocator(self.a0),
+        axis.set(major_locator=AsinhScale.AsinhLocator(self.linear_width),
                  major_formatter='{x:.3g}')
 
     class AsinhTransform(Transform):
         input_dims = output_dims = 1
 
-        def __init__(self, a0):
+        def __init__(self, linear_width):
             super().__init__()
-            self.a0 = a0
+            self.linear_width = linear_width
 
         def transform_non_affine(self, a):
-            return self.a0 * np.arcsinh(a / self.a0)
+            return self.linear_width * np.arcsinh(a / self.linear_width)
 
         def inverted(self):
-            return AsinhScale.InvertedAsinhTransform(self.a0)
+            return AsinhScale.InvertedAsinhTransform(self.linear_width)
 
     class InvertedAsinhTransform(Transform):
         input_dims = output_dims = 1
 
-        def __init__(self, a0):
+        def __init__(self, linear_width):
             super().__init__()
-            self.a0 = a0
+            self.linear_width = linear_width
 
         def transform_non_affine(self, a):
-            return self.a0 * np.sinh(a / self.a0)
+            return self.linear_width * np.sinh(a / self.linear_width)
 
         def inverted(self):
-            return AsinhScale.AsinhTransform(self.a0)
+            return AsinhScale.AsinhTransform(self.linear_width)
 
     class AsinhLocator(Locator):
         """
         An axis tick locator specialized for the arcsinh scale
 
         This is very unlikely to have any use beyond the AsinhScale class.
         """
-        def __init__(self, a0, apx_tick_count=12):
+        def __init__(self, linear_width, numticks=12):
             """
             Parameters
             ----------
-            a0 : float
+            linear_width : float
                 The scale parameter defining the extent
                 of the quasi-linear region.
-            apx_tick_count : int, default: 12
+            numticks : int, default: 12
                 The approximate number of major ticks that will fit
                 along the entire axis
             """
             super().__init__()
-            self.a0 = a0
-            self.apx_tick_count = apx_tick_count
+            self.linear_width = linear_width
+            self.numticks = numticks
 
         def __call__(self):
             dmin, dmax = self.axis.get_data_interval()
@@ -544,15 +554,15 @@ def __call__(self):
         def tick_values(self, vmin, vmax):
             # Construct a set of "on-screen" locations
             # that are uniformly spaced:
-            ymin, ymax = self.a0 * np.arcsinh(np.array([vmin, vmax]) / self.a0)
-            ys = np.linspace(ymin, ymax, self.apx_tick_count)
+            ymin, ymax = self.linear_width * np.arcsinh(np.array([vmin, vmax]) / self.linear_width)
+            ys = np.linspace(ymin, ymax, self.numticks)
             if (ymin * ymax) < 0:
                 # Ensure that the zero tick-mark is included,
                 # if the axis stradles zero
                 ys = np.hstack([ys, 0.0])
 
             # Transform the "on-screen" grid to the data space:
-            xs = self.a0 * np.sinh(ys / self.a0)
+            xs = self.linear_width * np.sinh(ys / self.linear_width)
             zero_xs = (xs == 0)
 
             # Round the data-space values to be intuitive decimal numbers:

lib/matplotlib/tests/test_scale.py

@@ -219,3 +219,8 @@ def test_scale_deepcopy():
     sc2 = copy.deepcopy(sc)
     assert str(sc.get_transform()) == str(sc2.get_transform())
     assert sc._transform is not sc2._transform
+
+
+def test_asinh_transforms():
+    # FIXME - more here soon
+    pass