cmocean

cmocean is a collection of perceptually uniform colormaps designed for oceanographic and scientific visualization. The colormaps are based on guidelines for color selection in oceanography as described in:

Thyng, K. M., Greene, C. A., Hetland, R. D., Zimmerle, H. M., & DiMarco, S. F. (2016). True colors of oceanography. Oceanography, 29(3), 10.

Beyond Python, these colormaps are available in several other environments including MATLAB, R, Julia, Plotly, Tableau, and more.

The cmocean package is organized into several functional submodules designed for oceanographic data visualization and color management:

• cmocean.cmocean: The core module containing colormaps specifically designed for oceanographic applications.
• cmocean.plots: Provides high-level plotting utilities and functions to simplify visualization tasks.
• cmocean.tools: Contains utility functions and tools to assist with data manipulation or color management.
• cmocean (top-level): The main entry point that exposes the package's primary functionality.

cmocean colormaps are available across various scientific and data visualization platforms. If you are working outside of a Python/Matplotlib environment, you can find implementations for:

• MATLAB: Original implementation by Chad Greene.
• R: Via the Oce oceanographic analysis package.
• Generic Mapping Tools (GMT): Available via cpt-city and GitHub.
• Other Tools: Paraview, Plotly, Tableau (via preference files), and ImageJ (via LUTs).
• Other Languages: Included in the julia package.

You can modify existing colormaps using standard suffixes:

• Reversed: Append _r to the name (e.g., cmocean.cm.gray_r).
• Inverted Lightness: Append _i to the name. This is useful for diverging colormaps used on light backgrounds (e.g., cmocean.cm.balance_i).
• Combined: You can combine both, such as _i_r or _r_i (e.g., cmocean.cm.balance_i_r).

import cmocean.cm as cmo

# Reversed
cmap_rev = cmo.gray_r

# Inverted lightness
cmap_inv = cmo.balance_i

# Both
cmap_both = cmo.balance_i_r

When using cmocean, it is important to choose the correct type of colormap based on the nature of your data. The project emphasizes moving away from the jet colormap due to its non-perceptual nature and tendency to create visual artifacts.

Key considerations for choosing a colormap include:

• Perceptual Uniformity: Use colormaps that represent data changes linearly in perception to avoid artifacts.
• Data Type: Determine if your data is sequential (e.g., temperature, depth) or diverging (e.g., anomalies from a mean, political leaning).
• Accessibility: Consider color blindness by using tools like a colourblind simulator to ensure your visualizations are readable by all users.

You can install cmocean using pip or conda. If you require the plots submodule (which includes visualization tools like viscm and colorspacious), install the [plots] extra.

Standard Installation:

pip install cmocean

Anaconda Installation:

conda install -c conda-forge cmocean

Installation with plotting capabilities:

pip install "cmocean[plots]"

# Standard installation
pip install cmocean

# Installation with plotting capabilities
pip install "cmocean[plots]"

All oceanographic colormaps are located in the cmocean.cm module. You can access them directly as objects or use their registered names within matplotlib by prefixing them with cmo..

Direct access: Use cmocean.cm.name (e.g., cmocean.cm.thermal).

Matplotlib integration: Once imported, you can use the string name in matplotlib functions: cmap='cmo.name' (e.g., cmap='cmo.amp').

Available names: You can retrieve a list of all available colormap names using cmocean.cm.cmapnames.

import cmocean
import matplotlib.pyplot as plt
import numpy as np

Z = np.random.randn(10,10)
fig, ax = plt.subplots()

# Method 1: Direct object access
ax.pcolormesh(Z, cmap=cmocean.cm.thermal)

# Method 2: Using registered matplotlib string
ax.pcolormesh(Z, cmap='cmo.amp')

# To see all names:
print(cmocean.cm.cmapnames)

You can quickly inspect and test cmocean colormaps using the cmocean.plots module. The test method provides a standard visualization, while quick_plot offers an alternative view. This is useful for verifying how a colormap will appear in your specific plots.

import cmocean
import matplotlib.pyplot as plt

fig = plt.figure(figsize=(8, 3))
ax = fig.add_subplot(1, 2, 1)
cmocean.plots.test(cmocean.cm.gray, ax=ax)
ax = fig.add_subplot(1, 2, 2)
cmocean.plots.quick_plot(cmocean.cm.gray, ax=ax)

You can visualize all available cmocean colormaps using the cmocean.plots.wrap_viscm function. This function wraps the viscm tool to display colormaps. To iterate through and visualize all colormaps in the library, use cmocean.cm.cmapnames to get the names and cmocean.cm.cmap_d to retrieve the actual colormap objects.

import cmocean

# Iterate through all colormap names and visualize them using viscm
for cmapname in cmocean.cm.cmapnames:
    cmocean.plots.wrap_viscm(cmocean.cm.cmap_d[cmapname], saveplot=False)

The topo colormap is a composite colormap containing two distinct parts:

• A blue/yellow component (the deep colormap) for water depths.
• A brown/green component for land elevation.

The following colormaps are designed for diverging datasets, centered around a critical value (usually zero):

• balance: Dark blue (negative) $\rightarrow$ off-white (zero) $\rightarrow$ dark red (positive). Ideal for sea surface elevation.
• delta: Darker blues $\rightarrow$ off-white $\rightarrow$ yellow-green. Ideal for diverging velocity values.
• curl: Darker teal $\rightarrow$ off-white $\rightarrow$ magenta. Ideal for diverging vorticity values.
• diff: Blues $\rightarrow$ browns. Diverging colormap.
• tarn: Dry browns $\rightarrow$ greens/blues. Designed as a complementary colormap to rain for representing rain anomalies.