matplotlib
diff --git a/‎doc/users/whats_new/new_formatters.rst
Lines changed: 30 additions & 0 deletions b/‎doc/users/whats_new/new_formatters.rst
Lines changed: 30 additions & 0 deletions
diff --git a/‎doc/users/whats_new/percent_formatter.rst
Lines changed: 0 additions & 6 deletions b/‎doc/users/whats_new/percent_formatter.rst
Lines changed: 0 additions & 6 deletions
diff --git a/‎examples/ticks_and_spines/tick_transform_formatter.py
Lines changed: 130 additions & 0 deletions b/‎examples/ticks_and_spines/tick_transform_formatter.py
Lines changed: 130 additions & 0 deletions
diff --git a/‎lib/matplotlib/tests/test_ticker.py
Lines changed: 96 additions & 25 deletions b/‎lib/matplotlib/tests/test_ticker.py
Lines changed: 96 additions & 25 deletions
@@ -0,0 +1,30 @@
+Four 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 yeild 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.
+
@@ -0,0 +1,130 @@
+"""
+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=None, in_end=None, out_start=None, out_end=None):
+        """
+        Sets up the transformation such that `in_start` gets mapped to
+        `out_start` and `in_end` gets mapped to `out_end`. The following
+        shortcuts apply when only some of the inputs are specified:
+
+          - none: no-op
+          - in_start: translation to zero
+          - out_start: translation from zero
+          - in_end: scaling to one (divide input by in_end) 
+          - out_end: scaling from one (multiply input by in_end)
+          - in_start, out_start: translation
+          - in_end, out_end: scaling (in_start and out_start zero)
+          - in_start, out_end: in_end=out_end, out_start=0
+          - in_end, out_start: in_start=0, out_end=in_end
+
+        Based on the following rules:
+
+          - start missing: set start to zero
+          - both ends are missing: set ranges to 1.0
+          - one end is missing: set it to the other end
+        """
+        self._in_offset = 0.0 if in_start is None else in_start
+        self._out_offset = 0.0 if out_start is None else out_start
+
+        if in_end is None:
+            if out_end is None:
+                self._in_scale = 1.0
+            else:
+                self._in_scale = out_end - self._in_offset
+        else:
+            self._in_scale = in_end - self._in_offset
+
+        if out_end is None:
+            if in_end is None:
+                self._out_scale = 1.0
+            else:
+                self._out_scale = in_end - self._out_offset
+        else:
+            self._out_scale = out_end - self._out_offset
+
+    def __call__(self, x):
+        """
+        Transforms the input value `x` according to the rule set up in
+        `__init__`.
+        """
+        return ((x - self._in_offset) * self._out_scale / self._in_scale +
+                     self._out_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 = plt.figure()
+fig.subplots_adjust(hspace=0.3)
+
+ax1 = fig.add_subplot(211)
+ax2 = fig.add_subplot(212, sharex=ax1, sharey=ax1)
+
+ax1.plot(temp_C, counts, drawstyle='steps-mid')
+ax2.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_formatter(
+        TransformFormatter(LinearTransform(in_start=-273.15, in_end=0,
+                                           out_end=491.67),
+                           StrMethodFormatter('{x:0.2f}')))
+ax2.xaxis.set_major_locator(ax1.xaxis.get_major_locator())
+
+# 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}')))
+
+fig.suptitle('Temperature vs Counts')
+ax1.set_xlabel('Temp (\u00B0C)')
+ax1.set_ylabel('Samples (Hex)')
+ax2.set_xlabel('Temp (\u00B0R)')
+ax2.set_ylabel('Samples (Hex)')
+
+plt.show()
+
@@ -504,37 +504,108 @@ def test_formatstrformatter():
     assert '002-01' == tmp_form(2, 1)
 
 
-percentformatter_test_cases = (
-    # Check explicitly set decimals over different intervals and values
-    (100, 0, '%', 120, 100, '120%'),
-    (100, 0, '%', 100, 90, '100%'),
-    (100, 0, '%', 90, 50, '90%'),
-    (100, 0, '%', 1.7, 40, '2%'),
-    (100, 1, '%', 90.0, 100, '90.0%'),
-    (100, 1, '%', 80.1, 90, '80.1%'),
-    (100, 1, '%', 70.23, 50, '70.2%'),
-    # 60.554 instead of 60.55: see https://bugs.python.org/issue5118
-    (100, 1, '%', 60.554, 40, '60.6%'),
-    # Check auto decimals over different intervals and values
-    (100, None, '%', 95, 1, '95.00%'),
-    (1.0, None, '%', 3, 6, '300%'),
-    (17.0, None, '%', 1, 8.5, '6%'),
-    (17.0, None, '%', 1, 8.4, '5.9%'),
-    (5, None, '%', -100, 0.000001, '-2000.00000%'),
-    # Check percent symbol
-    (1.0, 2, None, 1.2, 100, '120.00'),
-    (75, 3, '', 50, 100, '66.667'),
-    (42, None, '^^Foobar$$', 21, 12, '50.0^^Foobar$$'),
-)
-
-
 @pytest.mark.parametrize('xmax, decimals, symbol, x, display_range, expected',
-                         percentformatter_test_cases)
+    [
+        # Check explicitly set decimals over different intervals and values
+        (100, 0, '%', 120, 100, '120%'),
+        (100, 0, '%', 100, 90, '100%'),
+        (100, 0, '%', 90, 50, '90%'),
+        (100, 0, '%', 1.7, 40, '2%'),
+        (100, 1, '%', 90.0, 100, '90.0%'),
+        (100, 1, '%', 80.1, 90, '80.1%'),
+        (100, 1, '%', 70.23, 50, '70.2%'),
+        # 60.554 instead of 60.55: see https://bugs.python.org/issue5118
+        (100, 1, '%', 60.554, 40, '60.6%'),
+        # Check auto decimals over different intervals and values
+        (100, None, '%', 95, 1, '95.00%'),
+        (1.0, None, '%', 3, 6, '300%'),
+        (17.0, None, '%', 1, 8.5, '6%'),
+        (17.0, None, '%', 1, 8.4, '5.9%'),
+        (5, None, '%', -100, 0.000001, '-2000.00000%'),
+        # Check percent symbol
+        (1.0, 2, None, 1.2, 100, '120.00'),
+        (75, 3, '', 50, 100, '66.667'),
+        (42, None, '^^Foobar$$', 21, 12, '50.0^^Foobar$$'),
+     ])
 def test_percentformatter(xmax, decimals, symbol, x, display_range, expected):
     formatter = mticker.PercentFormatter(xmax, decimals, symbol)
     assert formatter.format_pct(x, display_range) == expected
 
 
+def test_TransformFormatter():
+    """
+    Verifies that the linear transformations are being done correctly.
+    """
+    def transform(x):
+        return -x
+
+    # Make a formatter using the default underlying formatter,
+    # which is a Formatter instance, not just a generic callable 
+    fmt = mticker.TransformFormatter(transform)
+
+    # Public (non-method) attributes
+    assert fmt.transform is transform
+    assert isinstance(fmt.formatter, mticker.ScalarFormatter)
+
+    # .create_dummy_axis
+    assert fmt.axis is None
+    fmt.create_dummy_axis()
+    assert fmt.axis is not None
+    assert fmt.axis is fmt.formatter.axis
+
+    # .set_axis
+    prev_axis = fmt.axis
+    fmt.set_axis(mticker._DummyAxis())
+    assert fmt.axis is fmt.formatter.axis
+    assert fmt.axis is not prev_axis
+
+    # .set_view_interval
+    fmt.set_view_interval(100, 200)
+    assert np.array_equal(fmt.axis.get_view_interval(), [100, 200])
+
+    # .set_data_interval
+    fmt.set_data_interval(50, 60)
+    assert np.array_equal(fmt.axis.get_data_interval(), [50, 60])
+
+    # .set_bounds
+    bounds = [-7, 7]
+    fmt.set_bounds(*bounds)
+    assert np.array_equal(fmt.axis.get_view_interval(), bounds)
+    assert np.array_equal(fmt.axis.get_data_interval(), bounds)
+
+    # .format_data, .format_data_short
+    assert fmt.format_data(100.0) == '\u22121e2'
+    assert fmt.format_data_short(-200.0) == '{:<12g}'.format(200)
+
+    # .get_offset
+    assert fmt.get_offset() == fmt.formatter.get_offset()
+
+    # .set_locs
+    locs = [1.0, 2.0, 3.0]
+    transformed_locs = [-1.0, -2.0, -3.0]
+    fmt.set_locs(locs)
+    assert fmt.locs is locs
+    assert fmt.formatter.locs == transformed_locs
+
+    # .fix_minus
+    val = '-19.0'
+    assert fmt.fix_minus(val) == '\u221219.0'
+    assert fmt.fix_minus(val) == fmt.formatter.fix_minus(val)
+
+    # .__call__ needs to be tested after `set_locs` has been called at
+    # least once.
+    assert fmt(5.0) == '\u22125'
+
+    # .set_formatter
+    prev_axis = fmt.axis
+    fmt.set_formatter(mticker.PercentFormatter())
+    assert isinstance(fmt.formatter, mticker.PercentFormatter)
+    assert fmt.axis is prev_axis
+    assert fmt.formatter.axis is fmt.axis
+    assert fmt.locs is locs
+    assert fmt.formatter.locs == transformed_locs
+
+
 def test_EngFormatter_formatting():
     """
     Create two instances of EngFormatter with default parameters, with and