DOC: add documentation

jklymak · jklymak · commit ba7fbb0cce8a · 2018-11-17T13:49:16.000-08:00
diff --git a/examples/scales/custom_scale.py b/examples/scales/custom_scale.py
@@ -5,6 +5,12 @@
 
 Create a custom scale, by implementing the scaling use for latitude data in a
 Mercator Projection.
+
+Unless you are maiking special use of the `~.Transform` class, you probably
+don't need to use this verbose method, but rather instead can use
+`~.matplotlib.scale.ArbitraryScale` and the ``'arbitrary'`` option of
+`~.matplotlib.axes.Axes.set_xscale` and `~.matplotlib.axes.Axes.set_yscale`.
+See the last example in :doc:`/gallery/scales/scales`. 
 """
 
 import numpy as np
diff --git a/examples/scales/scales.py b/examples/scales/scales.py
@@ -4,10 +4,13 @@
 ======
 
 Illustrate the scale transformations applied to axes, e.g. log, symlog, logit.
+
+The last two examples are examples of using the ``'arbitrary'`` scale by
+supplying forward and inverse functions for the scale transformation.
 """
 import numpy as np
 import matplotlib.pyplot as plt
-from matplotlib.ticker import NullFormatter
+from matplotlib.ticker import NullFormatter, FixedLocator
 
 # Fixing random state for reproducibility
 np.random.seed(19680801)
@@ -19,8 +22,8 @@
 x = np.arange(len(y))
 
 # plot with various axes scales
-fig, axs = plt.subplots(2, 2, sharex=True)
-fig.subplots_adjust(left=0.08, right=0.98, wspace=0.3)
+fig, axs = plt.subplots(3, 2, figsize=(6, 8),
+                        constrained_layout=True)
 
 # linear
 ax = axs[0, 0]
@@ -53,5 +56,73 @@
 ax.grid(True)
 ax.yaxis.set_minor_formatter(NullFormatter())
 
+# Arbitrary x**(1/2)
+def forward(x):
+    return x**(1/2)
+
+
+def inverse(x):
+    return x**2
+
+
+ax = axs[2, 0]
+ax.plot(x, y)
+ax.set_yscale('arbitrary', functions=(forward, inverse))
+ax.set_title('arbitrary: $x^{1/2}$')
+ax.grid(True)
+ax.yaxis.set_major_locator(FixedLocator(np.arange(0, 1, 0.2)**2))
+ax.yaxis.set_major_locator(FixedLocator(np.arange(0, 1, 0.2)))
+
+
+# Arbitrary Mercator transform
+def forward(a):
+    a = np.deg2rad(a)
+    # mask values too close to +/- 90, which are ill-defined.
+    masked = np.ma.masked_where((a <= -np.pi/2 + 0.02) |
+                                (a >= np.pi/2 - 0.02), a)
+    if masked.mask.any():
+        return np.rad2deg(
+                np.ma.log(np.abs(np.ma.tan(masked) + 1.0 / np.ma.cos(masked))))
+    else:
+        return np.rad2deg(np.log(np.abs(np.tan(a) + 1.0 / np.cos(a))))
+
+
+def inverse(a):
+    a = np.deg2rad(a)
+    return np.rad2deg(np.arctan(np.sinh(a)))
+
+ax = axs[2, 1]
+
+t = np.arange(-170.0, 170.0, 0.1)
+s = t / 2.
+
+ax.plot(t, s, '-', lw=2)
+
+ax.set_yscale('arbitrary', functions=(forward, inverse))
+ax.set_title('arbitrary: Mercator')
+ax.grid(True)
+ax.set_xlim([-180, 180])
+ax.yaxis.set_minor_formatter(NullFormatter())
+ax.yaxis.set_major_locator(FixedLocator(np.arange(-90, 90, 30)))
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+import matplotlib
+matplotlib.axes.Axes.set_yscale
+matplotlib.axes.Axes.set_xscale
+matplotlib.axis.set_major_locator
+matplotlib.scale.Logit
+matplotlib.scale.LogScale
+matplotlib.scale.LinearScale
+matplotlib.scale.SymmetricalLogScale
+matplotlib.scale.ArbitraryScale
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -138,6 +138,29 @@ def __init__(self, axis, functions, *,
          functions: (forward, inverse)
             two-tuple of the forward and inverse functions for the scale.
 
+         major_locator: `~matplotlib.ticker.Locator`
+            optional, allows passing major locator for the axis.  Defaults to
+            `~matplotlib.ticker.AutoLocator`
+
+         minor_locator: `~matplotlib.ticker.Locator`
+            optional, allows passing major locator for the axis.  Defaults to
+            `~matplotlib.ticker.NullLocator`
+
+         major_formatter: `~matplotlib.ticker.Formatter`
+            optional, allows passing major formatter for the axis.  Defaults to
+            `~matplotlib.ticker.ScalarFormatter`
+
+         minor_formatter: `~matplotlib.ticker.Formatter`
+            optional, allows passing maino formatter for the axis.  Defaults to
+            `~matplotlib.ticker.NullFormatter`
+
+        Examples
+        --------
+
+         :doc:`/gallery/scales/scales`
+
+
+
          """
 
          forward, inverse = functions
diff --git a/lib/matplotlib/tests/test_scale.py b/lib/matplotlib/tests/test_scale.py
@@ -155,12 +155,14 @@ def test_invalid_log_lims():
 def inverse(x):
     return x**2
 
+
 def forward(x):
     good = x >= 0
     y = np.full_like(x, np.NaN)
     y[good] = x[good]**(1/2)
     return y
 
+
 @image_comparison(baseline_images=['arbitrary_scales'], remove_text=True,
                   extensions=['png'], style='mpl20')
 def test_arbitrary_scale():
@@ -170,11 +172,11 @@ def test_arbitrary_scale():
 
     ax.plot(x, x)
     ax.set_xscale('arbitrary', functions=(forward, inverse))
-    ax.set_xlim(1,1000)
+    ax.set_xlim(1, 1000)
 
 
-@image_comparison(baseline_images=['arbitrary_scales_passloc'], remove_text=True,
-                  extensions=['png'], style='mpl20')
+@image_comparison(baseline_images=['arbitrary_scales_passloc'],
+                  remove_text=True, extensions=['png'], style='mpl20')
 def test_arbitrary_scale_passloc():
     fig, ax = plt.subplots()
 
@@ -184,4 +186,4 @@ def test_arbitrary_scale_passloc():
     ax.set_xscale('arbitrary', functions=(forward, inverse),
             major_locator=mticker.LogLocator(),
             minor_locator=mticker.LogLocator(subs=[2, 3, 4, 5, 6, 7, 8, 9]))
-    ax.set_xlim(1,1000)
+    ax.set_xlim(1, 1000)
