Minor corrections to documentation

Author: rwpenney

examples/scales/asinh_demo.py

@@ -20,13 +20,13 @@
 
 .. math::
 
-    a \\rightarrow a_0 \\ln (a) + {\\cal O}(1)
+    a \\rightarrow a_0 \\, {\\rm sgn}(a) \\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.
+from *separate* linear and logarithmic transformations.
 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
@@ -35,14 +35,15 @@
 See `~.scale.AsinhScale`, `~.scale.SymmetricalLogScale`.
 """
 
-import numpy
+import numpy as np
 import matplotlib.pyplot as plt
 
 # Prepare sample values for variations on y=x graph:
-x = numpy.linspace(-3, 6, 100)
+x = np.linspace(-3, 6, 100)
 
 ########################################
-# Compare "symlog" and "asinh" behaviour on sample y=x graph:
+# Compare "symlog" and "asinh" behaviour on sample y=x graph,
+# where the discontinuous gradient in "symlog" near y=2 is obvious:
 fig1 = plt.figure()
 ax0, ax1 = fig1.subplots(1, 2, sharex=True)
 
@@ -73,19 +74,23 @@
 
 ########################################
 # Compare "symlog" and "asinh" scalings
-# on 2D Cauchy-distributed random numbers:
+# on 2D Cauchy-distributed random numbers,
+# where one may be able to see more subtle artifacts near y=2
+# due to the gradient-discontinuity in "symlog":
 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)
+r = 3 * np.tan(np.random.uniform(-np.pi / 2.01, np.pi / 2.01,
+                                 size=(5000,)))
+th = np.random.uniform(0, 2*np.pi, size=r.shape)
 
-ax.scatter(r * numpy.cos(th), r * numpy.sin(th), s=4, alpha=0.5)
+ax.scatter(r * np.cos(th), r * np.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.set_xlim(-50, 50)
+ax.set_ylim(-50, 50)
 ax.grid()
 
 

lib/matplotlib/scale.py

@@ -459,6 +459,7 @@ def get_transform(self):
 
 
 class AsinhTransform(Transform):
+    """Inverse hyperbolic-sine transformation used by `.AsinhScale`"""
     input_dims = output_dims = 1
 
     def __init__(self, linear_width):
@@ -473,6 +474,7 @@ def inverted(self):
 
 
 class InvertedAsinhTransform(Transform):
+    """Hyperbolic-sine transformation used by `.AsinhScale`"""
     input_dims = output_dims = 1
 
     def __init__(self, linear_width):
@@ -493,16 +495,16 @@ class AsinhScale(ScaleBase):
     For values close to zero, this is essentially a linear scale,
     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 discontinutities in the function gradient
-    in contrast to the "symlog" scale.
+    is smooth, and has no discontinuities 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`
+    :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)`.
+    :math:`a \\rightarrow a_0 \\, {\\rm sgn}(a) \\ln |a| + {\\cal O}(1)`.
     """
 
     name = 'asinh'
@@ -515,7 +517,7 @@ def __init__(self, axis, *, linear_width=1.0, **kwargs):
             The scale parameter (elsewhere referred to as :math:`a_0`)
             defining the extent of the quasi-linear region,
             and the coordinate values beyond which the transformation
-            becomes asympoticially logarithmic.
+            becomes asympotically logarithmic.
         """
         super().__init__(axis)
         if linear_width <= 0.0: