Automatically create tick formatters for str and callable inputs.

toddrjen · toddrjen · commit b1bdd7453dcd · 2020-03-16T23:15:48.000-04:00
diff --git a/doc/users/next_whats_new/2020-03-06-auto-tick-formatters.rst b/doc/users/next_whats_new/2020-03-06-auto-tick-formatters.rst
@@ -0,0 +1,7 @@
+Allow tick formatters to be set with str or function inputs
+------------------------------------------------------------------------
+`~.Axis.set_major_formatter` and `~.Axis.set_minor_formatter`
+now accept `str` or function inputs in addition to `~.ticker.Formatter`
+instances. For a `str` a `~.ticker.StrMethodFormatter` is automatically
+created and used. For a function a `~.ticker.FuncFormatter` is automatically
+created and used.
diff --git a/examples/ticks_and_spines/tick-formatters.py b/examples/ticks_and_spines/tick-formatters.py
@@ -34,7 +34,7 @@ def setup(ax, title):
             fontsize=14, fontname='Monospace', color='tab:blue')
 
 
-fig, axs = plt.subplots(7, 1, figsize=(8, 6))
+fig, axs = plt.subplots(9, 1, figsize=(8, 8))
 
 # Null formatter
 setup(axs[0], title="NullFormatter()")
@@ -59,21 +59,30 @@ def major_formatter(x, pos):
 setup(axs[2], title='FuncFormatter(lambda x, pos: "[%.2f]" % x)')
 axs[2].xaxis.set_major_formatter(major_formatter)
 
-# FormatStr formatter
-setup(axs[3], title="FormatStrFormatter('#%d')")
-axs[3].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d"))
+# FuncFormatter can be automatically created directly with a function input
+# without needing to manually create the formatter
+setup(axs[3], title="lambda x, pos: str(x-5)")
+axs[3].xaxis.set_major_formatter(lambda x, pos: str(x-5))
+
+# StrMethod formatter
+setup(axs[4], title="StrMethodFormatter('{x:.3f}')")
+axs[4].xaxis.set_major_formatter(ticker.StrMethodFormatter("{x:.3f}"))
+
+# StrMethodFormatter can also be created directly with a string input.
+setup(axs[5], title="'{x} km'")
+axs[5].xaxis.set_major_formatter('{x} km')
 
 # Scalar formatter
-setup(axs[4], title="ScalarFormatter()")
-axs[4].xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True))
+setup(axs[6], title="ScalarFormatter()")
+axs[6].xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True))
 
-# StrMethod formatter
-setup(axs[5], title="StrMethodFormatter('{x:.3f}')")
-axs[5].xaxis.set_major_formatter(ticker.StrMethodFormatter("{x:.3f}"))
+# FormatStr formatter
+setup(axs[7], title="FormatStrFormatter('#%d')")
+axs[7].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d"))
 
 # Percent formatter
-setup(axs[6], title="PercentFormatter(xmax=5)")
-axs[6].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5))
+setup(axs[8], title="PercentFormatter(xmax=5)")
+axs[8].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5))
 
 plt.tight_layout()
 plt.show()
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1529,37 +1529,93 @@ def set_major_formatter(self, formatter):
         """
         Set the formatter of the major ticker.
 
+        In addition to a `~matplotlib.ticker.Formatter` instance,
+        this also accepts a `str` or function.
+
+        For a `str` a `~matplotlib.ticker.StrMethodFormatter` is used.
+        The field used for the value must be labeled *x* and the field used
+        for the position must be labeled *pos*.
+
+        For a function a `~matplotlib.ticker.FuncFormatter` is used.
+        The function should take in two inputs (a tick value ``x`` and a
+        position ``pos``), and return a string containing the corresponding
+        tick label.
+
         Parameters
         ----------
-        formatter : `~matplotlib.ticker.Formatter`
+        formatter : `~matplotlib.ticker.Formatter`, str, or function
         """
-        cbook._check_isinstance(mticker.Formatter, formatter=formatter)
-        if (isinstance(formatter, mticker.FixedFormatter)
-                and len(formatter.seq) > 0
-                and not isinstance(self.major.locator, mticker.FixedLocator)):
-            cbook._warn_external('FixedFormatter should only be used together '
-                                 'with FixedLocator')
-        self.isDefault_majfmt = False
-        self.major.formatter = formatter
-        formatter.set_axis(self)
-        self.stale = True
+        self._set_formatter(formatter, self.major)
 
     def set_minor_formatter(self, formatter):
         """
         Set the formatter of the minor ticker.
 
+        In addition to a `~matplotlib.ticker.Formatter` instance,
+        this also accepts a `str` or function.
+
+        For a `str` a `~matplotlib.ticker.StrMethodFormatter` is used.
+        The field used for the tick value must be labeled *x* and the field
+        used for the tick position must be labeled *pos*.
+        See the  `~matplotlib.ticker.StrMethodFormatter` documentation for
+        more information.
+
+        For a function a `~matplotlib.ticker.FuncFormatter` is used.
+        The function should take in two inputs (a tick value ``x`` and a
+        position ``pos``), and return a string containing the corresponding
+        tick label.
+        See the  `~matplotlib.ticker.FuncFormatter` documentation for
+        more information.
+
         Parameters
         ----------
-        formatter : `~matplotlib.ticker.Formatter`
+        formatter : `~matplotlib.ticker.Formatter`, str, or function
         """
-        cbook._check_isinstance(mticker.Formatter, formatter=formatter)
+        self._set_formatter(formatter, self.minor)
+
+    def _set_formatter(self, formatter, level):
+        """
+        Set the formatter of the major or minor ticker.
+
+        In addition to a `~matplotlib.ticker.Formatter` instance,
+        this also accepts a `str` or function.
+
+        For a `str` a `~matplotlib.ticker.StrMethodFormatter` is used.
+        The field used for the value must be labeled *x* and the field used
+        for the position must be labeled *pos*.
+
+        For a function a `~matplotlib.ticker.FuncFormatter` is used.
+        The function should take in two inputs (a tick value ``x`` and a
+        position ``pos``), and return a string containing the corresponding
+        tick label.
+
+        Parameters
+        ----------
+        formatter : `~matplotlib.ticker.Formatter`, str, or function
+        level : `self.major` or `self.minor`
+        """
+        if isinstance(formatter, str):
+            formatter = mticker.StrMethodFormatter(formatter)
+        # Don't allow any other TickHelper to avoid easy-to-make errors,
+        # like using a Locator instead of a Formatter.
+        elif (callable(formatter) and
+              not isinstance(formatter, mticker.TickHelper)):
+            formatter = mticker.FuncFormatter(formatter)
+        else:
+            cbook._check_isinstance(mticker.Formatter, formatter=formatter)
+
         if (isinstance(formatter, mticker.FixedFormatter)
                 and len(formatter.seq) > 0
-                and not isinstance(self.minor.locator, mticker.FixedLocator)):
+                and not isinstance(level.locator, mticker.FixedLocator)):
             cbook._warn_external('FixedFormatter should only be used together '
                                  'with FixedLocator')
-        self.isDefault_minfmt = False
-        self.minor.formatter = formatter
+
+        if level == self.major:
+            self.isDefault_majfmt = False
+        else:
+            self.isDefault_minfmt = False
+
+        level.formatter = formatter
         formatter.set_axis(self)
         self.stale = True
 
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -203,6 +203,28 @@ def test_formatter_ticker():
     ax.autoscale_view()
 
 
+def test_auto_formatter():
+    def _formfunc(x, pos):
+        return ''
+
+    formstr = '{x}_{pos}'
+
+    ax = plt.figure().subplots()
+    ax.xaxis.set_major_formatter(_formfunc)
+    ax.yaxis.set_minor_formatter(formstr)
+
+    targ_funcformatter = mticker.FuncFormatter(_formfunc)
+    targ_strformatter = mticker.StrMethodFormatter(formstr)
+
+    assert isinstance(ax.xaxis.get_major_formatter(),
+                      mticker.FuncFormatter)
+    assert isinstance(ax.yaxis.get_minor_formatter(),
+                      mticker.StrMethodFormatter)
+
+    assert ax.xaxis.get_major_formatter().func == targ_funcformatter.func
+    assert ax.yaxis.get_minor_formatter().fmt == targ_strformatter.fmt
+
+
 @image_comparison(["twin_axis_locators_formatters"])
 def test_twin_axis_locators_formatters():
     vals = np.linspace(0, 1, num=5, endpoint=True)
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -159,6 +159,12 @@
   ax.yaxis.set_major_formatter(ymajor_formatter)
   ax.yaxis.set_minor_formatter(yminor_formatter)
 
+For `.StrMethodFormatter`, `~.Axis.set_major_formatter` and
+`~.Axis.set_minor_formatter` accept a ``str``.  In that case a
+`.StrMethodFormatter` will be automatically created and applied based on
+the given ``str``.  Similalry, a `.FuncFormatter` will be automatically
+created and applied if a function is provided.
+
 See :doc:`/gallery/ticks_and_spines/major_minor_demo` for an
 example of setting major and minor ticks. See the :mod:`matplotlib.dates`
 module for more information and examples of using date locators and formatters.
@@ -418,8 +424,8 @@ class StrMethodFormatter(Formatter):
     """
     Use a new-style format string (as used by `str.format`) to format the tick.
 
-    The field used for the value must be labeled *x* and the field used
-    for the position must be labeled *pos*.
+    The field used for the tick value must be labeled *x* and the field used
+    for the tick position must be labeled *pos*.
     """
     def __init__(self, fmt):
         self.fmt = fmt
diff --git a/tutorials/text/text_intro.py b/tutorials/text/text_intro.py
@@ -291,25 +291,26 @@
 axs[0].plot(x1, y1)
 axs[1].plot(x1, y1)
 ticks = np.arange(0., 8.1, 2.)
-# list comprehension to get all tick labels...
 formatter = matplotlib.ticker.StrMethodFormatter('{x:1.1f}')
 axs[1].xaxis.set_ticks(ticks)
 axs[1].xaxis.set_major_formatter(formatter)
 axs[1].set_xlim(axs[0].get_xlim())
 plt.show()
 
 #############################################################################
+# A `matplotlib.ticker.StrMethodFormatter` can also be created by simply
+# passing a ``str`` without having to explicitly create the formatter.
+#
 # And of course we could have used a non-default locator to set the
 # tick locations.  Note we still pass in the tick values, but the
 # x-limit fix used above is *not* needed.
 
 fig, axs = plt.subplots(2, 1, figsize=(5, 3), tight_layout=True)
 axs[0].plot(x1, y1)
 axs[1].plot(x1, y1)
-formatter = matplotlib.ticker.FormatStrFormatter('%1.1f')
 locator = matplotlib.ticker.FixedLocator(ticks)
 axs[1].xaxis.set_major_locator(locator)
-axs[1].xaxis.set_major_formatter(formatter)
+axs[1].xaxis.set_major_formatter('±{x}°')
 plt.show()
 
 #############################################################################
@@ -350,27 +351,29 @@
 
 ##############################################################################
 #  Finally, we can specify functions for the formatter using
-# `matplotlib.ticker.FuncFormatter`.
+# `matplotlib.ticker.FuncFormatter`.  Further, like
+# `matplotlib.ticker.StrMethodFormatter`, simply passing a function will
+# automatically create a `matplotlib.ticker.FuncFormatter`.
 
 
 def formatoddticks(x, pos):
     """Format odd tick positions
     """
     if x % 2:
-        return '%1.2f' % x
+        return '{:1.2f}'.format(x)
     else:
         return ''
 
 
 fig, ax = plt.subplots(figsize=(5, 3), tight_layout=True)
 ax.plot(x1, y1)
-formatter = matplotlib.ticker.FuncFormatter(formatoddticks)
 locator = matplotlib.ticker.MaxNLocator(nbins=6)
-ax.xaxis.set_major_formatter(formatter)
+ax.xaxis.set_major_formatter(formatoddticks)
 ax.xaxis.set_major_locator(locator)
 
 plt.show()
 
+
 ##############################################################################
 # Dateticks
 # ~~~~~~~~~
