Doc: Add ticks document

Author: jklymak

galleries/users_explain/axes/index.rst

@@ -37,6 +37,7 @@ annotations like x- and y-labels, titles, and legends.
     colorbar_placement
     Autoscaling axes <autoscale>
     scales
+    ticks
     Legends <legend_guide>
     Subplot mosaic <mosaic>
     Constrained layout guide <constrainedlayout_guide>

galleries/users_explain/axes/scales.py

@@ -1,4 +1,6 @@
 """
+.. _user_axes_scales:
+
 ===========
 Axis scales
 ===========

galleries/users_explain/axes/ticks.py

@@ -0,0 +1,134 @@
+"""
+.. _user_axes_ticks:
+
+==========================
+Tick locations and formats
+==========================
+
+The x and y Axis on each Axes have default tick "locators" and "formatters"
+that depend on the scale being used (see :ref:`user_axes_scales`).  It is
+possible to customize the ticks and tick labels with either high-level methods
+like `~.axes.Axes.set_xticks` or set the locators and formatters directly on
+the axis.
+
+Manual location and formats
+===========================
+
+The simplest method to customize the tick locations and formats is to use
+`~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks`.  These can be used on
+either the major or the minor ticks.
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+
+import matplotlib.ticker as ticker
+
+
+fig, axs = plt.subplots(2, 1, figsize=(5.4, 5.4), layout='constrained')
+x = np.arange(100)
+for nn, ax in enumerate(axs):
+    ax.plot(x, x)
+    if nn == 1:
+        ax.set_title('Manual ticks')
+        ax.set_yticks(np.arange(0, 100.1, 100/3))
+        xticks = np.arange(0.50, 101, 20)
+        xlabels = [f'\\${x:1.2f}' for x in xticks]
+        ax.set_xticks(xticks, labels=xlabels)
+    else:
+        ax.set_title('Automatic ticks')
+
+# %%
+#
+# Note that the length of the ``labels`` argument must have the same length as
+# the array used to specify the ticks.
+#
+# By default `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` act on the
+# major ticks of an Axis, however it is possible to add minor ticks:
+
+fig, axs = plt.subplots(2, 1, figsize=(5.4, 5.4), layout='constrained')
+x = np.arange(100)
+for nn, ax in enumerate(axs):
+    ax.plot(x, x)
+    if nn == 1:
+        ax.set_title('Manual ticks')
+        ax.set_yticks(np.arange(0, 100.1, 100/3))
+        ax.set_yticks(np.arange(0, 100.1, 100/30), minor=True)
+    else:
+        ax.set_title('Automatic ticks')
+
+
+# %%
+#
+# Locators and Formatters
+# =======================
+#
+# Manually setting the ticks as above works well for specific final plots, but
+# does not adapt as the user interacts with the axes.   At a lower level,
+# Matplotlib has ``Locators`` that are meant to automatically choose ticks
+# depending on the current view limits of the axis, and ``Formatters`` that are
+# meant to format the tick labels automatically.
+#
+# The full list of locators provided by Matplotlib are listed at
+# :ref:`locators`, and the formatters at :ref:`formatters`.
+
+
+# %%
+
+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[['left', 'right', 'top']].set_visible(False)
+
+    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)
+    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')
+
+
+fig, axs = plt.subplots(8, 1, layout='constrained')
+
+# Null Locator
+setup(axs[0], title="NullLocator()")
+axs[0].xaxis.set_major_locator(ticker.NullLocator())
+axs[0].xaxis.set_minor_locator(ticker.NullLocator())
+
+# Multiple Locator
+setup(axs[1], title="MultipleLocator(0.5)")
+axs[1].xaxis.set_major_locator(ticker.MultipleLocator(0.5))
+axs[1].xaxis.set_minor_locator(ticker.MultipleLocator(0.1))
+
+# Fixed Locator
+setup(axs[2], title="FixedLocator([0, 1, 5])")
+axs[2].xaxis.set_major_locator(ticker.FixedLocator([0, 1, 5]))
+axs[2].xaxis.set_minor_locator(ticker.FixedLocator(np.linspace(0.2, 0.8, 4)))
+
+# Linear Locator
+setup(axs[3], title="LinearLocator(numticks=3)")
+axs[3].xaxis.set_major_locator(ticker.LinearLocator(3))
+axs[3].xaxis.set_minor_locator(ticker.LinearLocator(31))
+
+# Index Locator
+setup(axs[4], title="IndexLocator(base=0.5, offset=0.25)")
+axs[4].plot(range(0, 5), [0]*5, color='white')
+axs[4].xaxis.set_major_locator(ticker.IndexLocator(base=0.5, offset=0.25))
+
+# Auto Locator
+setup(axs[5], title="AutoLocator()")
+axs[5].xaxis.set_major_locator(ticker.AutoLocator())
+axs[5].xaxis.set_minor_locator(ticker.AutoMinorLocator())
+
+# MaxN Locator
+setup(axs[6], title="MaxNLocator(n=4)")
+axs[6].xaxis.set_major_locator(ticker.MaxNLocator(4))
+axs[6].xaxis.set_minor_locator(ticker.MaxNLocator(40))
+
+# Log Locator
+setup(axs[7], title="LogLocator(base=10, numticks=15)")
+axs[7].set_xlim(10**3, 10**10)
+axs[7].set_xscale('log')
+axs[7].xaxis.set_major_locator(ticker.LogLocator(base=10, numticks=15))
+plt.show()

lib/matplotlib/ticker.py

@@ -9,6 +9,9 @@
 Although the locators know nothing about major or minor ticks, they are used
 by the Axis class to support major and minor tick locating and formatting.
 
+.. _tick_locating:
+.. _locators:
+
 Tick locating
 -------------