DEV: Added three new Formatters to mpl.ticker

madphysicist · madphysicist · commit e3eb134b2686 · 2016-11-17T17:19:53.000-05:00
- BinaryIntFormatter
- HexIntFormatter
- LinearScaleFormatter

Also, changed the annotation in PercentFormatter tests slightly (non-functional change).
diff --git a/doc/users/whats_new/new_formatters.rst b/doc/users/whats_new/new_formatters.rst
@@ -0,0 +1,44 @@
+Four new Formatters added to `matplotlib.ticker`
+-----------------------------------------------
+
+Four new formatters have been added for displaying some specialized
+tick labels:
+
+  - :class:`matplotlib.ticker.PercentFormatter`
+  - :class:`matplotlib.ticker.LinearScaleFormatter`
+  - :class:`matplotlib.ticker.BinaryIntFormatter`
+  - :class:`matplotlib.ticker.HexIntFormatter`
+
+
+: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.LinearScaleFormatter`
+```````````````````````````````````````````````
+
+This is a wrapper around any other formatter of the user's choice.
+However, instead of passing in the actual tick values, it performs a
+linear transformation on them first.
+
+
+:class:`matplotlib.ticker.BinaryIntFormatter`
+`````````````````````````````````````````````
+
+Displays ticks as binary numbers with a given precision. This formatter
+is intended to be used with :class:`matplotlib.ticker.MaxNLocator` with
+the ``integer`` parameter set to ``True``.
+
+
+:class:`matplotlib.ticker.HexIntFormatter`
+``````````````````````````````````````````
+
+Displays ticks as hexadecimal numbers with a given precision. This
+formatter is intended to be used with
+:class:`matplotlib.ticker.MaxNLocator` with the ``integer`` parameter
+set to ``True``.
+
diff --git a/doc/users/whats_new/percent_formatter.rst b/doc/users/whats_new/percent_formatter.rst
diff --git a/lib/matplotlib/tests/test_ticker.py b/lib/matplotlib/tests/test_ticker.py
@@ -504,37 +504,123 @@ 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
 
 
+@pytest.mark.parametrize('n, unsigned, value, expected', [
+    # Positive, <8 bits
+    (8, False, 25, '00011001'),
+    (8, True, 25, '00011001'),
+    # Positive, >8 bits
+    (8, False, 257, '100000001'),
+    (8, True, 257, '100000001'),
+    # Positive float truncation
+    (8, False, 25.3, '00011001'),
+    (8, True, 25.3, '00011001'),
+    (8, False, 257.99, '100000001'),
+    (8, True, 257.99, '100000001'),
+    # Negative <8 bits
+    (8, False, -25, '-00011001'),
+    (8, True, -25, '11100111'),
+    # Negative >8 bits
+    (8, False, -257, '-100000001'),
+    (8, True, -257, '11111111'),
+    # Negative float truncation
+    (8, False, -25.3, '-00011001'),
+    (8, True, -25.3, '11100111'),
+    (8, False, -257.99, '-100000001'),
+    (8, True, -257.99, '111111111'),
+])
+def test_BinaryIntFormatter(n, unsigned, value, expected):
+    """
+    Verifies that numbers get converted to binary correctly, and that
+    floating point numbers get truncated.
+    """
+    fmt = mticker.BinaryIntFormatter(n, unsigned)
+    assert fmt(value) == expected
+
+
+@pytest.mark.parametrize('n, unsigned, value, expected',[
+    # Positive, <4 digits
+    (4, False, 37, '0025'),
+    (4, True, 37, '0025'),
+    # Positive, >4 digits
+    (4, False, 341041, '53431'),
+    (4, True, 341041, '53431'),
+    # Positive float truncation
+    (4, False, 37.8, '0025'),
+    (4, True, 37.8, '0025'),
+    (4, False, 341041.45, '53431'),
+    (4, True, 341041.45, '53431'),
+    # Negative <4 digits
+    (4, False, -37, '-0025'),
+    (4, True, -37, 'FFDB'),
+    # Negative >4 digits
+    (4, False, -341041, '-0025'),
+    (4, True, -341041, 'CBCF'),
+    # Negative float truncation
+    (4, False, -37.8, '-0025'),
+    (4, True, -37.8, 'FFDB'),
+    (4, False, -341041.45, '-53431'),
+    (4, True, -341041.45, 'CBCF'),
+])
+def test_HexIntFormatter(n, unsigned, value, expected):
+    """
+    Verifies that numbers get converted to hex correctly, and that
+    floating point numbers get truncated.
+    """
+    fmt = mticker.HexIntFormatter(n, unsigned)
+    assert fmt(value) == expected
+
+
+def test_LinearScaleFormatter():
+    """
+    Verifies that the linear transformations are being done correctly.
+    """
+    # Make a formatter that truncates to two decimal places always
+    base = lambda x, pos=None: '{:0.2f}'.format(x)
+
+    inputs = np.arange(-2.5, 13, 2.5)
+    outputs = ['{:0.2f}'.format(x) for x in np.arange(7.0)]
+
+    # Check a simple case
+    fmt = mticker.LinearScaleFormatter(10, (1, 5), formatter=base)
+    for i, o in zip(inputs, outputs):
+        print(i, fmt(i), o)
+        assert fmt(i) == o
+
+    # Check a reverse mapping
+    fmt = mticker.LinearScaleFormatter(10, (5, 1), formatter=base)
+    for i, o in zip(inputs, reversed(outputs)):
+        print(i, fmt(i), o)
+        assert fmt(i) == o
+
+
 def test_EngFormatter_formatting():
     """
     Create two instances of EngFormatter with default parameters, with and
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -154,6 +154,15 @@
 :class:`PercentFormatter`
     Format labels as a percentage
 
+:class:`BinaryIntFormatter`
+    Format labels as binary integers.
+
+:class:`HexIntFormatter`
+    Format labels as hexadecimal integers.
+
+:class:`LinearScaleFormatter`
+    Wrap another formatter to display transformed values.
+
 You can derive your own formatter from the Formatter base class by
 simply overriding the ``__call__`` method.  The formatter class has
 access to the axis view and data limits.
@@ -195,8 +204,9 @@
            'LogFormatterExponent', 'LogFormatterMathtext',
            'IndexFormatter', 'LogFormatterSciNotation',
            'LogitFormatter', 'EngFormatter', 'PercentFormatter',
-           'Locator', 'IndexLocator', 'FixedLocator', 'NullLocator',
-           'LinearLocator', 'LogLocator', 'AutoLocator',
+           'LinearScaleFormatter', 'BinaryIntFormatter',
+           'HexIntFormatter', 'Locator', 'IndexLocator', 'FixedLocator',
+           'NullLocator', 'LinearLocator', 'LogLocator', 'AutoLocator',
            'MultipleLocator', 'MaxNLocator', 'AutoMinorLocator',
            'SymmetricalLogLocator', 'LogitLocator')
 
@@ -1292,6 +1302,136 @@ def convert_to_pct(self, x):
         return 100.0 * (x / self.xmax)
 
 
+class BinaryIntFormatter(Formatter):
+    """
+    Formats the input as an ``n``-bit binary number, where ``n`` is
+    specified in the constructor.
+
+    ``n`` just specifies the minimum width to which numbers will be
+    padded with leading zeros. Numbers containing more than ``n`` bits
+    are allowed.
+
+    ``unsigned`` determines if negative numbers are printed with a minus sign
+    or if their binary representation is truncated to ``n`` bits and treated
+    as a positive number.
+
+    The input will be truncated to an integer, so this `Formatter` is best used
+    with a `MaxNLocator` with ``integer=True``.
+    """
+    def __init__(self, n, unsigned=False):
+        self.n = n
+        self.unsigned = unsigned
+
+    def format(self, x):
+        n = self.n
+        if x < 0:
+            if self.unsigned:
+                x = x & ((1 << n) - 1)
+            else:
+                n = self.n + 1
+        return '{x:0{n}b}'.format(x=0, n=n)
+
+    def __call__(self, x, pos=None):
+        return self.format(x)
+
+
+class HexIntFormatter(Formatter):
+    """
+    Formats the input as an ``n``-digit hexadecimal number, where ``n``
+    is specified in the constructor.
+
+    ``n`` just specifies the minimum width to which numbers will be
+    padded with leading zeros. Numbers containing more than ``n`` digits
+    are allowed.
+
+    ``unsigned`` determines if negative numbers are printed with a minus sign
+    or if their binary representation is truncated to ``n`` hex digits and
+    treated as a positive number.
+
+    The input will be truncated to an integer, so this `Formatter` is best
+    used with a `MaxNLocator` with ``integer=True``.
+    """
+    def __init__(self, n, unsigned=False):
+        self.n = n
+        self.unsigned = unsigned
+
+    def format(self, x):
+        n = self.n
+        if x < 0:
+            if self.unsigned:
+                x = x & ((1 << (4 * n)) - 1)
+            else:
+                n = self.n + 1
+        return '{x:0{n}X}'.format(x=0, n=n)
+
+    def __call__(self, x, pos=None):
+        return self.format(x)
+
+
+class LinearScaleFormatter(Formatter):
+    """
+    Displays labels that are scaled and offset versions of the actual
+    axis values.
+
+    This formatter can use any other formatter to actually render the
+    ticks.
+
+    inRef: number or 2-element iterable
+        Bounds on the input range to match to the output range. These
+        numbers do not actually restrict the input in any way. They are
+        just reference points. If the range is a scalar, it will be
+        interpreted as ``(0, inRef)``.
+    outRef: number or 2-element iterable
+        Bounds on the output range to match to the input range. These
+        numbers do not actually restrict the output in any way. They are
+        just reference points. If the range is a scalar, it will be
+        interpreted as ``(0, outRef)``.
+    formatter: matplotlib.ticker.Formatter
+        The instance to delegate the actual formatting of the
+        transformed value to.
+    """
+    def __init__(self, inRef=1.0, outRef=1.0, formatter=ScalarFormatter()):
+        def unpack(ref, name):
+            if np.iterable(ref):
+                ref = tuple(ref)
+                if len(ref) != 2:
+                    raise ValueError('Expected 2-element iterable for `{}`, '
+                                     'got {}.'.format(name, len(ref)))
+                return ref
+            return 0, ref
+
+        # All these values are retained for debugging/extension.
+        # Only the minima are used explicitly.
+        self.iMin, self.iMax = unpack(inRef, 'in')
+        self.oMin, self.oMax = unpack(outRef, 'out')
+        self.formatter = formatter
+
+        # Precomputing the values that are used in addition to the minima
+        self.iRange = self.iMax - self.iMin
+        self.oRange = self.oMax - self.oMin
+
+    def transform(self, x):
+        """
+        Transforms a value from the input scale to the output scale.
+        """
+        return  (x - self.iMin) / self.iRange * self.oRange + self.oMin
+
+    def __call__(self, x, pos=None):
+        return self.formatter(self.transform(x), pos)
+
+    def set_axis(self, ax):
+        self.formatter.set_axis(ax)
+
+    def get_offset(self):
+        return self.formatter.get_offset()
+
+    def set_locs(self, locs):
+        self.formatter.set_locs([self.transform(x) for x in locs])
+
+    def fix_minus(self, s):
+        return self.formatter.fix_minus(s)
+
+
 class Locator(TickHelper):
     """
     Determine the tick locations;
