diff --git a/galleries/examples/scales/custom_scale.py b/galleries/examples/scales/custom_scale.py index 0023bbcfbcae..0eedb16ec5cf 100644 --- a/galleries/examples/scales/custom_scale.py +++ b/galleries/examples/scales/custom_scale.py @@ -5,13 +5,25 @@ Custom scale ============ -Create a custom scale, by implementing the scaling use for latitude data in a -Mercator Projection. +Custom scales can be created in two ways + +#. For simple cases, use `~.scale.FuncScale` and the ``'function'`` option of + `~.Axes.set_xscale` and `~.Axes.set_yscale`. See the last example in + :doc:`/gallery/scales/scales`. + +#. Create a custom scale class such as the one in this example, which implements + the scaling use for latitude data in a Mercator Projection. This more complicated + approach is useful when + + * You are making special use of the `.Transform` class, such as the special + handling of values beyond the threshold in ``MercatorLatitudeTransform`` + below. + + * You want to override the default locators and formatters for the axis + (``set_default_locators_and_formatters`` below). + + * You want to limit the range of the the axis (``limit_range_for_scale`` below). -Unless you are making special use of the `.Transform` class, you probably -don't need to use this verbose method, and instead can use `~.scale.FuncScale` -and the ``'function'`` option of `~.Axes.set_xscale` and `~.Axes.set_yscale`. -See the last example in :doc:`/gallery/scales/scales`. """ import numpy as np diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py index 56eeb0e4169b..714fb08f55be 100644 --- a/lib/matplotlib/axis.py +++ b/lib/matplotlib/axis.py @@ -777,26 +777,15 @@ def _set_axes_scale(self, value, **kwargs): Parameters ---------- - value : {"linear", "log", "symlog", "logit", ...} or `.ScaleBase` - The axis scale type to apply. + value : str or `.ScaleBase` + The axis scale type to apply. Valid string values are the names of scale + classes ("linear", "log", "function",...). These may be the names of any + of the :ref:`built-in scales` or of any custom scales + registered using `matplotlib.scale.register_scale`. **kwargs - Different keyword arguments are accepted, depending on the scale. - See the respective class keyword arguments: - - - `matplotlib.scale.LinearScale` - - `matplotlib.scale.LogScale` - - `matplotlib.scale.SymmetricalLogScale` - - `matplotlib.scale.LogitScale` - - `matplotlib.scale.FuncScale` - - `matplotlib.scale.AsinhScale` - - Notes - ----- - By default, Matplotlib supports the above-mentioned scales. - Additionally, custom scales may be registered using - `matplotlib.scale.register_scale`. These scales can then also - be used here. + If *value* is a string, keywords are passed to the instantiation method of + the respective class. """ name = self._get_axis_name() old_default_lims = (self.get_major_locator() diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py index a63294406b56..7630ba6e54b9 100644 --- a/lib/matplotlib/scale.py +++ b/lib/matplotlib/scale.py @@ -3,7 +3,9 @@ The mapping is implemented through `.Transform` subclasses. -The following scales are builtin: +The following scales are built-in: + +.. _builtin_scales: ============= ===================== ================================ ================================= Name Class Transform Inverted transform