Univariate Colormaps#

Univariate colormaps are essential for visualizing scalar data in a meaningful way.

pycolorbar holds a colormap registry making it easy to work with a consistent set of colormap across different visualizations. The colormaps configurations can be saved into YAML files and re-used/re-registered across various projects.

In this tutorial, we’ll explain how to utilize the pycolorbar package to define, manipulate, validate and register the colormaps configurations.

Colormap configuration#

A univariate colormap is defined by its colors palette and the way the colors are assigned to the data. Here below we details the parameters required to define a colormap:

colormap_type: Type of colormap. Allowed names are LinearSegmentedColormap and ListedColormap.
color_space: Describes the color space (e.g., rgb, rgba, hex, name, hsv) of the color_palette.
color_palette: An array or list of colors that compose the colormap.

We will now explore how to utilize the pycolorbar package to register, manage, validate, and visualize univariate colormaps.

First of all, let’s start by importing the necessary functions and libraries

[1]:

import os
import pycolorbar
from pprint import pprint

Register configurations#

To get started, let’s explore what colormaps are available in the registry:

[2]:

# List all registered colormaps in pycolorbar
available_colormaps = pycolorbar.colormaps.names
print("Available colormaps:", available_colormaps)

Available colormaps: []

Now let’s specify the directory where we have saved our colormap configuration YAML files. For illustrative purposes, we here use the pycolorbar software directory wherein we have curated a selection of sample colormaps configurations.

[3]:

# Specify the directory containing colormap configuration YAML files

# dst_dir = "/path/to/your/colormap/configs"
dst_dir = os.path.join(pycolorbar.etc_directory, "colormaps") # example colormaps directory in pycolorbar

To register all colormap configuration YAML files located within a specified directory, you can use pycolorbar.register_colormaps:

[4]:

# Register all colormap configuration YAML files located in a directory
pycolorbar.register_colormaps(dst_dir)

# Verify the colormaps are registered
print("Colormaps after registration:", pycolorbar.colormaps.names)

Colormaps after registration: ['IMERG_Liquid', 'IMERG_Solid', 'STEPS-BE', 'STEPS-BOM-RF3', 'STEPS-MCH', 'STEPS-NL']

If when we register new colormaps we are overwriting pre-registered colormaps, by default pycolorbar raise a warning:

[5]:

pycolorbar.register_colormaps(dst_dir)

Warning: Overwriting existing colormap 'IMERG_Liquid'
Warning: Overwriting existing colormap 'IMERG_Solid'
Warning: Overwriting existing colormap 'STEPS-BE'
Warning: Overwriting existing colormap 'STEPS-MCH'
Warning: Overwriting existing colormap 'STEPS-BOM-RF3'
Warning: Overwriting existing colormap 'STEPS-NL'

To silence the warning, you can specify the argument verbose=False

[6]:

pycolorbar.register_colormaps(dst_dir, verbose=False)

To instead unallow overwriting, you can specify the argument force=False. If an existing colormap is gonna to be overwritten, an informative error is raised.

[7]:

# pycolorbar.register_colormaps(dst_dir, force=False)

If you aim to register only a specific colormap configuration YAML file, you can use the pycolorbars.register_colormap function:

[8]:

# Retrieve the filepath for a registered colormap's configuration with:
cmap_filepath = pycolorbar.colormaps.get_cmap_filepath("STEPS-MCH")
print("Colormap configuration filepath:", cmap_filepath)

# Now let's register a single colormap configuration YAML file
pycolorbar.register_colormap(cmap_filepath)

Colormap configuration filepath: /home/ghiggi/Python_Packages/pycolorbar/pycolorbar/etc/colormaps/precipitation/STEPS-MCH.yaml
Warning: Overwriting existing colormap 'STEPS-MCH'

Unregister configurations#

If you need to remove a colormap from the registry, you can use the unregister method:

[9]:

# Unregister a specific colormap
pycolorbar.colormaps.unregister("STEPS-MCH")

# Check the current list of registered colormaps
print("Colormaps after unregistering 'STEPS-MCH':", pycolorbar.colormaps.names)

Colormaps after unregistering 'STEPS-MCH': ['IMERG_Liquid', 'IMERG_Solid', 'STEPS-BE', 'STEPS-BOM-RF3', 'STEPS-NL']

Reset the registry#

You can reset the colormap registry with:

[10]:

pycolorbar.colormaps.reset()
print("Colormaps after resetting the registry:", pycolorbar.colormaps.names)

Colormaps after resetting the registry: []

[11]:

# Now let's register the colormaps to continue with the tutorial
pycolorbar.register_colormaps(dst_dir)

Read configurations#

Now let’s have a look on how to read a colormap configuration YAML file into a python dictionary.

The read_yaml provides the “raw” colormap dictionary, while the read_cmap_dict function provides the pycolorbar validated colormap dictionary.

[12]:

from pycolorbar.settings.colormap_io import read_cmap_dict
from pycolorbar.utils.yaml import read_yaml

[13]:

# Read the raw dictionary
cmap_dict = read_yaml(cmap_filepath)
pprint(cmap_dict)

{'auxiliary': {'category': ['MeteoSwiss', 'precipitation']},
 'color_palette': ['#9c7e94',
                   '#640064',
                   '#AF00AF',
                   '#DC00DC',
                   '#3232C8',
                   '#0064FF',
                   '#009696',
                   '#00C832',
                   '#64FF00',
                   '#96FF00',
                   '#C8FF00',
                   '#FFFF00',
                   '#FFC800',
                   '#FFA000',
                   '#FF7D00',
                   '#E11900'],
 'color_space': 'hex',
 'colormap_type': 'LinearSegmentedColormap'}

[14]:

# Read the validated dictionary
# - Note the added defaults arguments 'n' and 'segmentdata' set to None.
cmap_dict = read_cmap_dict(cmap_filepath)
pprint(cmap_dict)

{'auxiliary': {'category': ['MeteoSwiss', 'precipitation']},
 'color_palette': array(['#9c7e94', '#640064', '#AF00AF', '#DC00DC', '#3232C8', '#0064FF',
       '#009696', '#00C832', '#64FF00', '#96FF00', '#C8FF00', '#FFFF00',
       '#FFC800', '#FFA000', '#FF7D00', '#E11900'], dtype='<U7'),
 'color_space': 'hex',
 'colormap_type': 'LinearSegmentedColormap',
 'n': 256,
 'segmentdata': None}

The colormap dictionary can also be retrieved directly from the colormaps registry:

[15]:

cmap_dict = pycolorbar.colormaps.get_cmap_dict("STEPS-MCH")

[16]:

pprint(cmap_dict)

{'auxiliary': {'category': ['MeteoSwiss', 'precipitation']},
 'color_palette': array(['#9c7e94', '#640064', '#AF00AF', '#DC00DC', '#3232C8', '#0064FF',
       '#009696', '#00C832', '#64FF00', '#96FF00', '#C8FF00', '#FFFF00',
       '#FFC800', '#FFA000', '#FF7D00', '#E11900'], dtype='<U7'),
 'color_space': 'hex',
 'colormap_type': 'LinearSegmentedColormap',
 'n': 256,
 'segmentdata': None}

Add temporary configurations#

The colormap registry add_cmap_dict allows to temporary add colormap configurations to the registry.

[17]:

pycolorbar.colormaps.add_cmap_dict(cmap_dict, name="CUSTOM_COLORMAP")

[18]:

# Let's check the custom colormap dictionary has been added to the registry
assert "CUSTOM_COLORMAP" in pycolorbar.colormaps

Validate configurations#

If you aims to define your own colormap configuration dictionary, you can validate it with:

[19]:

validated_cmap_dict = pycolorbar.validate_cmap_dict(cmap_dict)

To validate the registered colormap configurations you can use the pycolorbar.colormaps.validate method.

[20]:

pycolorbar.colormaps.validate("CUSTOM_COLORMAP") # validate a specific colormap
pycolorbar.colormaps.validate() # validate all colormaps in the registry

Save configurations#

Every pycolorbar colormap has a corresponding YAML configuration file to disk. The name of each YAML file corresponds to the name of the colormap registered in pycolorbar.

You can save a colormap configuration to disk with:

[21]:

filepath = "/tmp/CUSTOM_COLORMAP.yaml"
pycolorbar.colormaps.to_yaml(name="CUSTOM_COLORMAP", filepath=filepath, force=True)

[22]:

# Let's check the written YAML file
cmap_dict = read_yaml(filepath)
pprint(cmap_dict)

{'auxiliary': {'category': ['MeteoSwiss', 'precipitation']},
 'color_palette': ['#9c7e94',
                   '#640064',
                   '#AF00AF',
                   '#DC00DC',
                   '#3232C8',
                   '#0064FF',
                   '#009696',
                   '#00C832',
                   '#64FF00',
                   '#96FF00',
                   '#C8FF00',
                   '#FFFF00',
                   '#FFC800',
                   '#FFA000',
                   '#FF7D00',
                   '#E11900'],
 'color_space': 'hex',
 'colormap_type': 'LinearSegmentedColormap',
 'n': 256.0,
 'segmentdata': None}

Retrieve the colormaps#

To retrieve the matplotlib colormap corresponding to a pycolorbar configuration, you just need to call the get_cmap function.

[23]:

cmap = pycolorbar.get_cmap("STEPS-MCH")
cmap

Note that the get_cmapmethods also allow to retrieve the available matplotlib colormaps.

[24]:

cmap = pycolorbar.get_cmap("Spectral")
cmap

Moreover, you can also revert the colormap by adding the suffix _r the colormap name and resample the colormap look-up-table:

[25]:

cmap = pycolorbar.get_cmap("STEPS-MCH_r", lut=10)
cmap

You can also visualize the colormap with:

[26]:

pycolorbar.show_colormap("STEPS-MCH")

../_images/tutorials_Introduction_univariate_colormaps_54_0.png

Colormaps categories#

pycolorbar provides a way to retrieve a custom selection of registered colormaps according to the categories specified in the auxiliary/category field of the colormap YAML configuration file.

For example, the “STEPS-MCH” has the categories ['MeteoSwiss', 'precipitation'] indicating the type and use of the colormap.

[27]:

cmap_dict = pycolorbar.colormaps.get_cmap_dict("STEPS-MCH")
pprint(cmap_dict)

{'auxiliary': {'category': ['MeteoSwiss', 'precipitation']},
 'color_palette': array(['#9c7e94', '#640064', '#AF00AF', '#DC00DC', '#3232C8', '#0064FF',
       '#009696', '#00C832', '#64FF00', '#96FF00', '#C8FF00', '#FFFF00',
       '#FFC800', '#FFA000', '#FF7D00', '#E11900'], dtype='<U7'),
 'color_space': 'hex',
 'colormap_type': 'LinearSegmentedColormap',
 'n': 256,
 'segmentdata': None}

With the available_colormaps function we can retrieve the list of colormaps belonging to a given category:

[28]:

pycolorbar.available_colormaps("precipitation")

[28]:

['CUSTOM_COLORMAP',
 'IMERG_Liquid',
 'IMERG_Solid',
 'STEPS-BOM-RF3',
 'STEPS-MCH']

while with show_colormaps we can visualize a selection of registered pycolorbar colormaps:

[29]:

pycolorbar.show_colormaps(category="precipitation")

../_images/tutorials_Introduction_univariate_colormaps_60_0.png

or all the registered pycolorbar colormaps:

[30]:

pycolorbar.show_colormaps(category="pycolorbar")

../_images/tutorials_Introduction_univariate_colormaps_62_0.png

We also provide a way a quick way to list and visualize registered matplotlib and pycolorbar colormaps based on their characteristics. Some relevant categories are perceptual, sequential, diverging, qualitative and cycliccolormaps.

If you aim to contribute colormaps to pycolorbar, please consider to add the relevant categories to the auxiliary/categoryfield of the colormap configuration YAML file.

[31]:

pycolorbar.available_colormaps(category="perceptual")
pycolorbar.show_colormaps(category="perceptual")

../_images/tutorials_Introduction_univariate_colormaps_64_0.png

[32]:

pycolorbar.available_colormaps(category="sequential")
pycolorbar.show_colormaps(category="sequential")

../_images/tutorials_Introduction_univariate_colormaps_65_0.png

[33]:

pycolorbar.available_colormaps(category="diverging")
pycolorbar.show_colormaps(category="diverging")

../_images/tutorials_Introduction_univariate_colormaps_66_0.png

[34]:

pycolorbar.available_colormaps(category="qualitative")
pycolorbar.show_colormaps(category="qualitative")

../_images/tutorials_Introduction_univariate_colormaps_67_0.png

[35]:

pycolorbar.available_colormaps(category="cyclic")
pycolorbar.show_colormaps(category="cyclic")

../_images/tutorials_Introduction_univariate_colormaps_68_0.png

Univariate Colormaps

Contents