Skip to content

Copy-edit the standalone colorbar tutorial #27253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 2, 2023
Merged

Copy-edit the standalone colorbar tutorial #27253

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 63 additions & 68 deletions galleries/users_explain/colors/colorbar_only.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,65 @@
"""
.. redirect-from:: /tutorials/colors/colorbar_only

=============================
Customized Colorbars Tutorial
=============================
====================
Standalone colorbars
====================

This tutorial shows how to build and customize standalone colorbars, i.e.
without an attached plot.

Customized Colorbars
====================

A `~.Figure.colorbar` needs a "mappable" (`matplotlib.cm.ScalarMappable`)
object (typically, an image) which indicates the colormap and the norm to be
used. In order to create a colorbar without an attached image, one can instead
use a `.ScalarMappable` with no associated data.

Basic continuous colorbar
-------------------------

Here we create a basic continuous colorbar with ticks and labels.

The arguments to the `~.Figure.colorbar` call are the `.ScalarMappable`
(constructed using the *norm* and *cmap* arguments), the axes where the
colorbar should be drawn, and the colorbar's orientation.

For more information see the :mod:`~matplotlib.colorbar` API.
"""

import matplotlib.pyplot as plt

import matplotlib as mpl

fig, ax = plt.subplots(figsize=(6, 1))
fig.subplots_adjust(bottom=0.5)
# %%
# Basic continuous colorbar
# -------------------------
# Here, we create a basic continuous colorbar with ticks and labels.
#
# The arguments to the `~.Figure.colorbar` call are the `.ScalarMappable`
# (constructed using the *norm* and *cmap* arguments), the axes where the
# colorbar should be drawn, and the colorbar's orientation.
#
# For more information see the `~matplotlib.colorbar` API.

fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')

cmap = mpl.cm.cool
norm = mpl.colors.Normalize(vmin=5, vmax=10)

fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap=cmap),
cax=ax, orientation='horizontal', label='Some Units')

# %%
# Colorbar attached next to a pre-existing axes
# ---------------------------------------------
# All examples in this tutorial (except this one) show a standalone colorbar on
# its own figure, but it is possible to display the colorbar *next* to a
# pre-existing Axes *ax* by passing ``ax=ax`` to the colorbar() call (meaning
# "draw the colorbar next to *ax*") rather than ``cax=ax`` (meaning "draw the
# colorbar on *ax*").

fig, ax = plt.subplots(layout='constrained')

fig.colorbar(mpl.cm.ScalarMappable(norm=mpl.colors.Normalize(0, 1), cmap='magma'),
ax=ax, orientation='vertical', label='a colorbar label')

# %%
# Extended colorbar with continuous colorscale
# --------------------------------------------
#
# The second example shows how to make a discrete colorbar based on a
# continuous cmap. With the "extend" keyword argument the appropriate colors
# are chosen to fill the colorspace, including the extensions:
fig, ax = plt.subplots(figsize=(6, 1))
fig.subplots_adjust(bottom=0.5)
# Discrete and extended colorbar with continuous colorscale
# ---------------------------------------------------------
# The following example shows how to make a discrete colorbar based on a
# continuous cmap. We use `matplotlib.colors.BoundaryNorm` to describe the
# interval boundaries (which must be in increasing order), and further pass the
# *extend* argument to it to further display "over" and "under" colors (which
# are used for data outside of the norm range).

fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')

cmap = mpl.cm.viridis
bounds = [-1, 2, 5, 7, 12, 15]
Expand All @@ -61,72 +70,58 @@
label="Discrete intervals with extend='both' keyword")

# %%
# Discrete intervals colorbar
# ---------------------------
#
# The third example illustrates the use of a
# :class:`~matplotlib.colors.ListedColormap` which generates a colormap from a
# set of listed colors, `.colors.BoundaryNorm` which generates a colormap
# index based on discrete intervals and extended ends to show the "over" and
# "under" value colors. Over and under are used to display data outside of the
# normalized [0, 1] range. Here we pass colors as gray shades as a string
# encoding a float in the 0-1 range.
# Colorbar with arbitrary colors
# ------------------------------
# The following example still uses a `.BoundaryNorm` to describe discrete
# interval boundaries, but now uses a `matplotlib.colors.ListedColormap` to
# associate each interval with an arbitrary color (there must be as many
# intervals than there are colors). The "over" and "under" colors are set on
# the colormap using `.Colormap.with_extremes`.
#
# If a :class:`~matplotlib.colors.ListedColormap` is used, the length of the
# bounds array must be one greater than the length of the color list. The
# bounds must be monotonically increasing.
# We also pass additional arguments to `~.Figure.colorbar`:
#
# This time we pass additional arguments to
# `~.Figure.colorbar`. For the out-of-range values to display on the colorbar
# without using the *extend* keyword with
# `.colors.BoundaryNorm`, we have to use the *extend* keyword argument directly
# in the colorbar call. Here we also
# use the spacing argument to make
# the length of each colorbar segment proportional to its corresponding
# interval.

fig, ax = plt.subplots(figsize=(6, 1))
fig.subplots_adjust(bottom=0.5)
# - To display the out-of-range values on the colorbar, we use the *extend*
# argument in the colorbar() call. (This is equivalent to passing the
# *extend* argument in the `.BoundaryNorm` constructor as done in the
# previous example.)
# - To make the length of each colorbar segment proportional to its
# corresponding interval, we use the *spacing* argument in the colorbar()
# call.

cmap = (mpl.colors.ListedColormap(['red', 'green', 'blue', 'cyan'])
.with_extremes(over='0.25', under='0.75'))
fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')

cmap = (mpl.colors.ListedColormap(['red', 'green', 'blue', 'cyan'])
.with_extremes(under='yellow', over='magenta'))
bounds = [1, 2, 4, 7, 8]
norm = mpl.colors.BoundaryNorm(bounds, cmap.N)

fig.colorbar(
mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
cax=ax,
cax=ax, orientation='horizontal',
extend='both',
ticks=bounds,
spacing='proportional',
orientation='horizontal',
label='Discrete intervals, some other units',
)

# %%
# Colorbar with custom extension lengths
# --------------------------------------
#
# Here we illustrate the use of custom length colorbar extensions, on a
# colorbar with discrete intervals. To make the length of each extension the
# We can customize the length colorbar extensions, on a colorbar with discrete
# intervals. To make the length of each extension the
# same as the length of the interior colors, use ``extendfrac='auto'``.

fig, ax = plt.subplots(figsize=(6, 1))
fig.subplots_adjust(bottom=0.5)
fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')

cmap = (mpl.colors.ListedColormap(['royalblue', 'cyan', 'yellow', 'orange'])
.with_extremes(over='red', under='blue'))

bounds = [-1.0, -0.5, 0.0, 0.5, 1.0]
norm = mpl.colors.BoundaryNorm(bounds, cmap.N)

fig.colorbar(
mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
cax=ax,
extend='both',
extendfrac='auto',
ticks=bounds,
cax=ax, orientation='horizontal',
extend='both', extendfrac='auto',
spacing='uniform',
orientation='horizontal',
label='Custom extension lengths, some other units',
)

Expand Down