From 1542cee78139d78a337501d654aadb2e0981e9f9 Mon Sep 17 00:00:00 2001
From: Steffen Rehberg <steffen.rehberg@googlemail.com>
Date: Tue, 4 Jul 2023 17:57:30 +0200
Subject: [PATCH] DOC: Modernize Colorbar Tick Labelling example

- use colorbar.set_ticks instead of colorbar.ax.set_[x|y]ticklabels whose
  usage is discouraged
- now that we don't have to handle vertical and horizontal colorbars
  differently we can instead show different ways to achieve the same
  and show additional tweaks like labelling the colorbar extensions
  (strictly speaking the old labels >1 and <-1 were simply wrong for
  clipped data)
- update numpy random number generation
- add admonition
---
 .../ticks/colorbar_tick_labelling_demo.py     | 47 +++++++++++++------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/galleries/examples/ticks/colorbar_tick_labelling_demo.py b/galleries/examples/ticks/colorbar_tick_labelling_demo.py
index 56294c6abbb3..8a1e5b28043d 100644
--- a/galleries/examples/ticks/colorbar_tick_labelling_demo.py
+++ b/galleries/examples/ticks/colorbar_tick_labelling_demo.py
@@ -3,45 +3,62 @@
 Colorbar Tick Labelling
 =======================
 
-Produce custom labelling for a colorbar.
-
-Contributed by Scott Sinclair
+Vertical colorbars have ticks, tick labels, and labels visible on the *y* axis,
+horizontal colorbars on the *x* axis. The ``ticks`` parameter can be used to
+set the ticks and the ``format`` parameter can be used to format the tick labels
+of the visible colorbar axes. For further adjustments, the ``yaxis`` or
+``xaxis`` axes of the colorbar can be retrieved using its ``ax`` property.
 """
-
 import matplotlib.pyplot as plt
 import numpy as np
-from numpy.random import randn
 
-from matplotlib import cm
+import matplotlib.ticker as mticker
 
 # Fixing random state for reproducibility
-np.random.seed(19680801)
+rng = np.random.default_rng(seed=19680801)
 
 # %%
 # Make plot with vertical (default) colorbar
 
 fig, ax = plt.subplots()
 
-data = np.clip(randn(250, 250), -1, 1)
+data = rng.standard_normal((250, 250))
 
-cax = ax.imshow(data, cmap=cm.coolwarm)
+cax = ax.imshow(data, vmin=-1, vmax=1, cmap='coolwarm')
 ax.set_title('Gaussian noise with vertical colorbar')
 
 # Add colorbar, make sure to specify tick locations to match desired ticklabels
-cbar = fig.colorbar(cax, ticks=[-1, 0, 1])
-cbar.ax.set_yticklabels(['< -1', '0', '> 1'])  # vertically oriented colorbar
+cbar = fig.colorbar(cax,
+                    ticks=[-1, 0, 1],
+                    format=mticker.FixedFormatter(['< -1', '0', '> 1']),
+                    extend='both'
+                    )
+labels = cbar.ax.get_yticklabels()
+labels[0].set_verticalalignment('top')
+labels[-1].set_verticalalignment('bottom')
 
 # %%
 # Make plot with horizontal colorbar
 
 fig, ax = plt.subplots()
 
-data = np.clip(randn(250, 250), -1, 1)
+data = np.clip(data, -1, 1)
 
-cax = ax.imshow(data, cmap=cm.afmhot)
+cax = ax.imshow(data, cmap='afmhot')
 ax.set_title('Gaussian noise with horizontal colorbar')
 
-cbar = fig.colorbar(cax, ticks=[-1, 0, 1], orientation='horizontal')
-cbar.ax.set_xticklabels(['Low', 'Medium', 'High'])  # horizontal colorbar
+# Add colorbar and adjust ticks afterwards
+cbar = fig.colorbar(cax, orientation='horizontal')
+cbar.set_ticks(ticks=[-1, 0, 1], labels=['Low', 'Medium', 'High'])
 
 plt.show()
+
+# %%
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `matplotlib.colorbar.Colorbar.set_ticks`
+#    - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`