.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_gallery_ticks_and_spines_tick-formatters.py>`     to download the full example code
    .. rst-class:: sphx-glr-example-title

    .. _sphx_glr_gallery_ticks_and_spines_tick-formatters.py:


===============
Tick formatters
===============

Tick formatters define how the numeric value associated with a tick on an axis
is formatted as a string.

This example illustrates the usage and effect of the most common formatters.


.. code-block:: default


    import matplotlib.pyplot as plt
    from matplotlib import ticker


    def setup(ax, title):
        """Set up common parameters for the Axes in the example."""
        # only show the bottom spine
        ax.yaxis.set_major_locator(ticker.NullLocator())
        ax.spines['right'].set_color('none')
        ax.spines['left'].set_color('none')
        ax.spines['top'].set_color('none')

        # define tick positions
        ax.xaxis.set_major_locator(ticker.MultipleLocator(1.00))
        ax.xaxis.set_minor_locator(ticker.MultipleLocator(0.25))

        ax.xaxis.set_ticks_position('bottom')
        ax.tick_params(which='major', width=1.00, length=5)
        ax.tick_params(which='minor', width=0.75, length=2.5, labelsize=10)
        ax.set_xlim(0, 5)
        ax.set_ylim(0, 1)
        ax.text(0.0, 0.2, title, transform=ax.transAxes,
                fontsize=14, fontname='Monospace', color='tab:blue')


    # Tick formatters can be set in one of two ways, either by passing a ``str``
    # or function to `~.Axis.set_major_formatter` or `~.Axis.set_minor_formatter`,
    # or by creating an instance of one of the various `~.ticker.Formatter` classes
    # and providing that to `~.Axis.set_major_formatter` or
    # `~.Axis.set_minor_formatter`.

    # The first two examples directly pass a ``str`` or function.

    fig0, axs0 = plt.subplots(2, 1, figsize=(8, 2))
    fig0.suptitle('Simple Formatting')

    # A ``str``, using format string function syntax, can be used directly as a
    # formatter.  The variable ``x`` is the tick value and the variable ``pos`` is
    # tick position.  This creates a StrMethodFormatter automatically.
    setup(axs0[0], title="'{x} km'")
    axs0[0].xaxis.set_major_formatter('{x} km')

    # A function can also be used directly as a formatter. The function must take
    # two arguments: ``x`` for the tick value and ``pos`` for the tick position,
    # and must return a ``str``  This creates a FuncFormatter automatically.
    setup(axs0[1], title="lambda x, pos: str(x-5)")
    axs0[1].xaxis.set_major_formatter(lambda x, pos: str(x-5))

    fig0.tight_layout()


    # The remaining examples use Formatter objects.

    fig1, axs1 = plt.subplots(7, 1, figsize=(8, 6))
    fig1.suptitle('Formatter Object Formatting')

    # Null formatter
    setup(axs1[0], title="NullFormatter()")
    axs1[0].xaxis.set_major_formatter(ticker.NullFormatter())

    # StrMethod formatter
    setup(axs1[1], title="StrMethodFormatter('{x:.3f}')")
    axs1[1].xaxis.set_major_formatter(ticker.StrMethodFormatter("{x:.3f}"))


    # FuncFormatter can be used as a decorator
    @ticker.FuncFormatter
    def major_formatter(x, pos):
        return f'[{x:.2f}]'


    setup(axs1[2], title='FuncFormatter("[{:.2f}]".format')
    axs1[2].xaxis.set_major_formatter(major_formatter)

    # Fixed formatter
    setup(axs1[3], title="FixedFormatter(['A', 'B', 'C', ...])")
    # FixedFormatter should only be used together with FixedLocator.
    # Otherwise, one cannot be sure where the labels will end up.
    positions = [0, 1, 2, 3, 4, 5]
    labels = ['A', 'B', 'C', 'D', 'E', 'F']
    axs1[3].xaxis.set_major_locator(ticker.FixedLocator(positions))
    axs1[3].xaxis.set_major_formatter(ticker.FixedFormatter(labels))

    # Scalar formatter
    setup(axs1[4], title="ScalarFormatter()")
    axs1[4].xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True))

    # FormatStr formatter
    setup(axs1[5], title="FormatStrFormatter('#%d')")
    axs1[5].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d"))

    # Percent formatter
    setup(axs1[6], title="PercentFormatter(xmax=5)")
    axs1[6].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5))

    fig1.tight_layout()
    plt.show()





.. rst-class:: sphx-glr-horizontal


    *

      .. image:: /gallery/ticks_and_spines/images/sphx_glr_tick-formatters_001.png
          :alt: Simple Formatting
          :class: sphx-glr-multi-img

    *

      .. image:: /gallery/ticks_and_spines/images/sphx_glr_tick-formatters_002.png
          :alt: Formatter Object Formatting
          :class: sphx-glr-multi-img





------------

References
""""""""""

The use of the following functions, methods, classes and modules is shown
in this example:


.. code-block:: default


    import matplotlib
    matplotlib.pyplot.subplots
    matplotlib.axes.Axes.text
    matplotlib.axis.Axis.set_major_formatter
    matplotlib.axis.Axis.set_major_locator
    matplotlib.axis.Axis.set_minor_locator
    matplotlib.axis.XAxis.set_ticks_position
    matplotlib.axis.YAxis.set_ticks_position
    matplotlib.ticker.FixedFormatter
    matplotlib.ticker.FixedLocator
    matplotlib.ticker.FormatStrFormatter
    matplotlib.ticker.FuncFormatter
    matplotlib.ticker.MultipleLocator
    matplotlib.ticker.NullFormatter
    matplotlib.ticker.NullLocator
    matplotlib.ticker.PercentFormatter
    matplotlib.ticker.ScalarFormatter
    matplotlib.ticker.StrMethodFormatter








.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  1.721 seconds)


.. _sphx_glr_download_gallery_ticks_and_spines_tick-formatters.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: tick-formatters.py <tick-formatters.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: tick-formatters.ipynb <tick-formatters.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    Keywords: matplotlib code example, codex, python plot, pyplot
    `Gallery generated by Sphinx-Gallery
    <https://sphinx-gallery.readthedocs.io>`_