Improved overview documentation

Author: rwpenney

doc/users/next_whats_new/asinh_scale.rst

@@ -5,5 +5,29 @@ The new ``asinh`` axis scale offers an alternative to ``symlog`` that
 smoothly transitions between the quasi-linear and asymptotically logarithmic
 regions of the scale. This is based on an arcsinh transformation that
 allows plotting both positive and negative values than span many orders
-of magnitude. A scale parameter ``a0`` is provided to allow the user
+of magnitude. A scale parameter is provided to allow the user
 to tune the width of the linear region of the scale.
+
+.. plot::
+
+    from matplotlib import pyplot as plt
+    import numpy
+
+    fig, (ax0, ax1) = plt.subplots(1, 2, sharex=True)
+    x = numpy.linspace(-3, 6, 100)
+
+    ax0.plot(x, x)
+    ax0.set_yscale('symlog')
+    ax0.grid()
+    ax0.set_title('symlog')
+
+    ax1.plot(x, x)
+    ax1.set_yscale('asinh')
+    ax1.grid()
+    ax1.set_title(r'$sinh^{-1}$')
+
+    for p in (-2, 2):
+      for ax in (ax0, ax1):
+        c = plt.Circle((p, p), radius=0.5, fill=False,
+                       color='red', alpha=0.8, lw=3)
+        ax.add_patch(c)

examples/scales/asinh_demo.py

@@ -2,6 +2,37 @@
 ============
 Asinh Demo
 ============
+
+Illustration of the `asinh` axis scaling, which uses the transformation
+
+.. math::
+
+    a \\rightarrow a_0 \\sinh^{-1} (a / a_0)
+
+For coordinate values close to zero (i.e. much smaller than
+the "linear width" :math:`a_0`), this leaves values essentially unchanged:
+
+.. math::
+
+    a \\rightarrow a + {\\cal O}(a^3)
+
+but for larger values (i.e. :math:`|a| \gg a_0`, this is asymptotically
+
+.. math::
+
+    a \\rightarrow a_0 \\ln (a) + {\\cal O}(1)
+
+As with the `symlog` 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
+that has discontinuities in its gradient because it is built
+from *separate* linear and logarithmic transformation.
+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.
+
+See `~.scale.AsinhScale`, `~.scale.SymmetricalLogScale`.
 """
 
 import numpy
@@ -10,6 +41,7 @@
 # Prepare sample values for variations on y=x graph:
 x = numpy.linspace(-3, 6, 100)
 
+########################################
 # Compare "symlog" and "asinh" behaviour on sample y=x graph:
 fig1 = plt.figure()
 ax0, ax1 = fig1.subplots(1, 2, sharex=True)
@@ -22,12 +54,13 @@
 ax1.plot(x, x)
 ax1.set_yscale('asinh')
 ax1.grid()
-ax1.set_title(r'$sinh^{-1}$')
+ax1.set_title('asinh')
 
 
+########################################
 # Compare "asinh" graphs with different scale parameter "linear_width":
 fig2 = plt.figure()
-axs = fig2.subplots(1, 3, sharex=True)
+axs = fig2.subplots(1, 3, sharex=True, constrained_layout=True)
 for ax, a0 in zip(axs, (0.2, 1.0, 5.0)):
     ax.set_title('linear_width={:.3g}'.format(a0))
     ax.plot(x, x, label='y=x')
@@ -38,6 +71,7 @@
     ax.legend(loc='best', fontsize='small')
 
 
+########################################
 # Compare "symlog" and "asinh" scalings
 # on 2D Cauchy-distributed random numbers:
 fig3 = plt.figure()

lib/matplotlib/scale.py

@@ -497,12 +497,12 @@ class AsinhScale(ScaleBase):
     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 :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)`.
+    :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)`.
+    :math:`a \\rightarrow a_0 \\ln (a) + {\\cal O}(1)`.
     """
 
     name = 'asinh'

lib/matplotlib/ticker.py

@@ -2640,7 +2640,10 @@ def tick_values(self, vmin, vmax):
         )
         qs = decades * np.round(xs / decades)
 
-        return np.array(sorted(set(qs)))
+        if len(qs) > self.numticks // 2:
+            return np.array(sorted(set(qs)))
+        else:
+            return np.linspace(vmin, vmax, self.numticks)
 
 
 class LogitLocator(MaxNLocator):