From 468435101595180837d088640c7c50748c01d7aa Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 4 Jun 2023 17:31:08 +0200 Subject: [PATCH] Rewrite Tick formatters example - Collect all relevant descriptions in the summary text at the top - Merge everything into one figure. The code should be mostly irrelevant for the example. The figure can serve as a standalone reference. Also remove "Dollar Ticks" example (closes #25967). The formatting is more concisely explained in this overview. We don't need individual examples for all the formatters. --- galleries/examples/ticks/dollar_ticks.py | 39 ------- galleries/examples/ticks/tick-formatters.py | 123 ++++++++------------ lib/matplotlib/ticker.py | 2 + 3 files changed, 48 insertions(+), 116 deletions(-) delete mode 100644 galleries/examples/ticks/dollar_ticks.py diff --git a/galleries/examples/ticks/dollar_ticks.py b/galleries/examples/ticks/dollar_ticks.py deleted file mode 100644 index 4186e8c369e9..000000000000 --- a/galleries/examples/ticks/dollar_ticks.py +++ /dev/null @@ -1,39 +0,0 @@ -""" -============ -Dollar ticks -============ - -Use a `~.ticker.FormatStrFormatter` to prepend dollar signs on y-axis labels. - -.. redirect-from:: /gallery/pyplots/dollar_ticks -""" -import matplotlib.pyplot as plt -import numpy as np - -# Fixing random state for reproducibility -np.random.seed(19680801) - -fig, ax = plt.subplots() -ax.plot(100*np.random.rand(20)) - -# Use automatic StrMethodFormatter -ax.yaxis.set_major_formatter('${x:1.2f}') - -ax.yaxis.set_tick_params(which='major', labelcolor='green', - labelleft=False, labelright=True) - -plt.show() - - -# %% -# -# .. admonition:: References -# -# The use of the following functions, methods, classes and modules is shown -# in this example: -# -# - `matplotlib.pyplot.subplots` -# - `matplotlib.axis.Axis.set_major_formatter` -# - `matplotlib.axis.Axis.set_tick_params` -# - `matplotlib.axis.Tick` -# - `matplotlib.ticker.StrMethodFormatter` diff --git a/galleries/examples/ticks/tick-formatters.py b/galleries/examples/ticks/tick-formatters.py index 45f59d0b48c2..543aec57e4d2 100644 --- a/galleries/examples/ticks/tick-formatters.py +++ b/galleries/examples/ticks/tick-formatters.py @@ -8,6 +8,23 @@ This example illustrates the usage and effect of the most common formatters. +The tick format is configured via the function `~.Axis.set_major_formatter` +or `~.Axis.set_minor_formatter`. It accepts: + +- a format string, which implicitly creates a `.StrMethodFormatter`. +- a function, implicitly creates a `.FuncFormatter`. +- an instance of a `.Formatter` subclass. The most common are + + - `.NullFormatter`: No labels on the ticks. + - `.StrMethodFormatter`: Use string `str.format` method. + - `.FormatStrFormatter`: Use %-style formatting. + - `.FuncFormatter`: Define labels through a function. + - `.FixedFormatter`: Set the label strings explicitly. + - `.ScalarFormatter`: Default formatter for scalars: auto-pick the format string. + - `.PercentFormatter`: Format labels as a percentage. + + See :ref:`formatters` for a complete list. + """ import matplotlib.pyplot as plt @@ -34,103 +51,55 @@ def setup(ax, title): 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. +fig = plt.figure(figsize=(8, 8), layout='constrained') +fig0, fig1, fig2 = fig.subfigures(3, height_ratios=[1.5, 1.5, 7.5]) -fig0, axs0 = plt.subplots(2, 1, figsize=(8, 2)) -fig0.suptitle('Simple Formatting') +fig0.suptitle('String Formatting', fontsize=16, x=0, ha='left') +ax0 = fig0.subplots() -# 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') +setup(ax0, title="'{x} km'") +ax0.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() +fig1.suptitle('Function Formatting', fontsize=16, x=0, ha='left') +ax1 = fig1.subplots() +setup(ax1, title="def(x, pos): return str(x-5)") +ax1.xaxis.set_major_formatter(lambda x, pos: str(x-5)) -# %% -# The remaining examples use `.Formatter` objects. -fig1, axs1 = plt.subplots(7, 1, figsize=(8, 6)) -fig1.suptitle('Formatter Object Formatting') +fig2.suptitle('Formatter Object Formatting', fontsize=16, x=0, ha='left') +axs2 = fig2.subplots(7, 1) -# Null formatter -setup(axs1[0], title="NullFormatter()") -axs1[0].xaxis.set_major_formatter(ticker.NullFormatter()) +setup(axs2[0], title="NullFormatter()") +axs2[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}")) +setup(axs2[1], title="StrMethodFormatter('{x:.3f}')") +axs2[1].xaxis.set_major_formatter(ticker.StrMethodFormatter("{x:.3f}")) +setup(axs2[2], title="FormatStrFormatter('#%d')") +axs2[2].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d")) -# FuncFormatter can be used as a decorator -@ticker.FuncFormatter -def major_formatter(x, pos): + +def fmt_two_digits(x, pos): return f'[{x:.2f}]' -setup(axs1[2], title='FuncFormatter("[{:.2f}]".format)') -axs1[2].xaxis.set_major_formatter(major_formatter) +setup(axs2[3], title='FuncFormatter("[{:.2f}]".format)') +axs2[3].xaxis.set_major_formatter(ticker.FuncFormatter(fmt_two_digits)) -# Fixed formatter -setup(axs1[3], title="FixedFormatter(['A', 'B', 'C', ...])") +setup(axs2[4], title="FixedFormatter(['A', 'B', 'C', 'D', 'E', 'F'])") # 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)) +axs2[4].xaxis.set_major_locator(ticker.FixedLocator(positions)) +axs2[4].xaxis.set_major_formatter(ticker.FixedFormatter(labels)) -# FormatStr formatter -setup(axs1[5], title="FormatStrFormatter('#%d')") -axs1[5].xaxis.set_major_formatter(ticker.FormatStrFormatter("#%d")) +setup(axs2[5], title="ScalarFormatter()") +axs2[5].xaxis.set_major_formatter(ticker.ScalarFormatter(useMathText=True)) -# Percent formatter -setup(axs1[6], title="PercentFormatter(xmax=5)") -axs1[6].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5)) +setup(axs2[6], title="PercentFormatter(xmax=5)") +axs2[6].xaxis.set_major_formatter(ticker.PercentFormatter(xmax=5)) -fig1.tight_layout() plt.show() - - -# %% -# -# .. admonition:: References -# -# The use of the following functions, methods, classes and modules is shown -# in this example: -# -# - `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` diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py index 1aea4e946144..3c49f3a07700 100644 --- a/lib/matplotlib/ticker.py +++ b/lib/matplotlib/ticker.py @@ -77,6 +77,8 @@ ax.xaxis.set_major_locator(MultipleLocator(5)) ax2.xaxis.set_major_locator(MultipleLocator(5)) +.. _formatters: + Tick formatting ---------------