matplotlib · madphysicist · Nov 17, 2016 · Feb 27, 2017 · story645 · Jan 29, 2017
diff --git a/doc/users/whats_new/new_formatters.rst b/doc/users/whats_new/new_formatters.rst
@@ -0,0 +1,29 @@
+Two new Formatters added to `matplotlib.ticker`
+-----------------------------------------------
+
+Two new formatters have been added for displaying some specialized
+tick labels:
+
+  - :class:`matplotlib.ticker.PercentFormatter`
+  - :class:`matplotlib.ticker.TransformFormatter`
+
+
+:class:`matplotlib.ticker.PercentFormatter`
+```````````````````````````````````````````
+
+This new formatter has some nice features like being able to convert
+from arbitrary data scales to percents, a customizable percent symbol
+and either automatic or manual control over the decimal points.
+
+
+:class:`matplotlib.ticker.TransformFormatter`
+```````````````````````````````````````````````
+
+A more generic version of :class:`matplotlib.ticker.FuncFormatter` that
+allows the tick values to be transformed before being passed to an
+underlying formatter. The transformation can yield results of arbitrary
+type, so for example, using `int` as the transformation will allow
+:class:`matplotlib.ticker.StrMethodFormatter` to use integer format
+strings. If the underlying formatter is an instance of
+:class:`matplotlib.ticker.Formatter`, it will be configured correctly
+through this class.
diff --git a/doc/users/whats_new/percent_formatter.rst b/doc/users/whats_new/percent_formatter.rst
diff --git a/examples/ticks_and_spines/tick-formatters.py b/examples/ticks_and_spines/tick-formatters.py
@@ -19,25 +19,23 @@ def setup(ax):
     ax.set_xlim(0, 5)
     ax.set_ylim(0, 1)
     ax.patch.set_alpha(0.0)
+    ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
+    ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 
 
 plt.figure(figsize=(8, 6))
-n = 7
+n = 8
 
 # Null formatter
 ax = plt.subplot(n, 1, 1)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
-ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 ax.xaxis.set_major_formatter(ticker.NullFormatter())
 ax.xaxis.set_minor_formatter(ticker.NullFormatter())
 ax.text(0.0, 0.1, "NullFormatter()", fontsize=16, transform=ax.transAxes)
 
 # Fixed formatter
 ax = plt.subplot(n, 1, 2)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.MultipleLocator(1.0))
-ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 majors = ["", "0", "1", "2", "3", "4", "5"]
 ax.xaxis.set_major_formatter(ticker.FixedFormatter(majors))
 minors = [""] + ["%.2f" % (x-int(x)) if (x-int(x))
@@ -54,8 +52,6 @@ def major_formatter(x, pos):
 
 ax = plt.subplot(n, 1, 3)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
-ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 ax.xaxis.set_major_formatter(ticker.FuncFormatter(major_formatter))
 ax.text(0.0, 0.1, 'FuncFormatter(lambda x, pos: "[%.2f]" % x)',
         fontsize=15, transform=ax.transAxes)
@@ -64,40 +60,39 @@ def major_formatter(x, pos):
 # FormatStr formatter
 ax = plt.subplot(n, 1, 4)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
-ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 ax.xaxis.set_major_formatter(ticker.FormatStrFormatter(">%d<"))
 ax.text(0.0, 0.1, "FormatStrFormatter('>%d<')",
         fontsize=15, transform=ax.transAxes)
 
 # Scalar formatter
 ax = plt.subplot(n, 1, 5)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.AutoLocator())
-ax.xaxis.set_minor_locator(ticker.AutoMinorLocator())
 ax.xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True))
 ax.text(0.0, 0.1, "ScalarFormatter()", fontsize=15, transform=ax.transAxes)
 
 # StrMethod formatter
 ax = plt.subplot(n, 1, 6)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
-ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 ax.xaxis.set_major_formatter(ticker.StrMethodFormatter("{x}"))
 ax.text(0.0, 0.1, "StrMethodFormatter('{x}')",
         fontsize=15, transform=ax.transAxes)
 
 # Percent formatter
 ax = plt.subplot(n, 1, 7)
 setup(ax)
-ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
-ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))
 ax.xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5))
 ax.text(0.0, 0.1, "PercentFormatter(xmax=5)",
         fontsize=15, transform=ax.transAxes)
 
-# Push the top of the top axes outside the figure because we only show the
-# bottom spine.
+# TransformFormatter
+ax = plt.subplot(n, 1, 8)
+setup(ax)
+ax.xaxis.set_major_formatter(ticker.TransformFormatter(lambda x: 7 - 2 * x))
+ax.text(0.0, 0.1, "TransformFormatter(lambda x: 7 - 2 * x)",
+        fontsize=15, transform=ax.transAxes)
+
+# Push the top of the top axes outside the figure because we only show
+# the bottom spine.
 plt.subplots_adjust(left=0.05, right=0.95, bottom=0.05, top=1.05)
 
 plt.show()
diff --git a/examples/ticks_and_spines/tick_transform_formatter.py b/examples/ticks_and_spines/tick_transform_formatter.py
@@ -0,0 +1,108 @@
+"""
+Demo of the `matplotlib.ticker.TransformFormatter` class.
+
+This code demonstrates two features:
+
+  1. A linear transformation of the input values. A callable class for
+     doing the transformation is presented as a recipe here. The data
+     type of the inputs does not change.
+  2. A transformation of the input type. The example here allows
+     `matplotlib.ticker.StrMethodFormatter` to handle integer formats
+     ('b', 'o', 'd', 'n', 'x', 'X'), which will normally raise an error
+     if used directly. This transformation is associated with a
+     `matplotlib.ticker.MaxNLocator` which has `integer` set to True to
+     ensure that the inputs are indeed integers.
+
+The same histogram is plotted in two sub-plots with a shared x-axis.
+Each axis shows a different temperature scale: one in degrees Celsius,
+one in degrees Rankine (the Fahrenheit analogue of Kelvins). This is one
+of the few examples of recognized scientific units that have both a
+scale and an offset relative to each other.
+"""
+
+import numpy as np
+from matplotlib import pyplot as plt
+from matplotlib.axis import Ticker
+from matplotlib.ticker import (
+    TransformFormatter, StrMethodFormatter, MaxNLocator
+)
+
+
+class LinearTransform:
+    """
+    A callable class that transforms input values to output according to
+    a linear transformation.
+    """
+
+    def __init__(self, in_start=0.0, in_end=None, out_start=0.0, out_end=None):
+        """
+        Sets up the transformation such that `in_start` gets mapped to
+        `out_start` and `in_end` gets mapped to `out_end`.
+
+        Configuration arguments set up the mapping and do not impose
+        any restriction on the subsequent arguments to `__call__`. None
+        of the configuration arguments are required.
+
+        A missing `in_start` or `out_start` defaults to zero. A missing
+        `in_end` and `out_end` default to `in_start + 1.0` and
+        `out_start + 1.0`, respectively.
+
+        A simple scaling transformation can be created by only
+        supplying the end arguments. A translation can be obtained by
+        only supplying the start arguments.
+        """
+        in_scale = 1.0 if in_end is None else in_end - in_start
+        out_scale = 1.0 if out_end is None else out_end - out_start
+
+        self._scale = out_scale / in_scale
+        self._offset = out_start - self._scale * in_start
+
+    def __call__(self, x):
+        """
+        Transforms the input value `x` according to the rule set up in
+        `__init__`.
+        """
+        return x * self._scale + self._offset
+
+# X-data
+temp_C = np.arange(-5.0, 5.1, 0.25)
+# Y-data
+counts = 15.0 * np.exp(-temp_C**2 / 25)
+# Add some noise
+counts += np.random.normal(scale=4.0, size=counts.shape)
+if counts.min() < 0:
+    counts += counts.min()
+
+fig, ax1 = plt.subplots()
+ax2 = fig.add_subplot(111, sharex=ax1, sharey=ax1, frameon=False)
+
+ax1.plot(temp_C, counts, drawstyle='steps-mid')
+
+ax1.xaxis.set_major_formatter(StrMethodFormatter('{x:0.2f}'))
+
+# This step is necessary to allow the shared x-axes to have different
+# Formatter and Locator objects.
+ax2.xaxis.major = Ticker()
+# 0C -> 491.67R (definition), -273.15C (0K)->0R (-491.67F)(definition)
+ax2.xaxis.set_major_locator(ax1.xaxis.get_major_locator())
+ax2.xaxis.set_major_formatter(
+        TransformFormatter(LinearTransform(in_start=-273.15, in_end=0,
+                                           out_end=491.67),
+                           StrMethodFormatter('{x:0.2f}')))
+
+# The y-axes share their locators and formatters, so only one needs to
+# be set
+ax1.yaxis.set_major_locator(MaxNLocator(integer=True))
+# Setting the transfrom to `int` will only alter the type, not the
+# actual value of the ticks
+ax1.yaxis.set_major_formatter(
+        TransformFormatter(int, StrMethodFormatter('{x:02X}')))
+
+ax1.set_xlabel('Temperature (\N{DEGREE SIGN}C)')
+ax1.set_ylabel('Samples (Hex)')
+ax2.set_xlabel('Temperature (\N{DEGREE SIGN}R)')
+
+ax1.xaxis.tick_top()
+ax1.xaxis.set_label_position('top')
+
+plt.show()