CMasher colours and colormaps

Colours and colormaps from CMasher. CMasher is optional: install it with pip install cmasher (or pip install "plotastro[cmasher]"). plotastro imports it only when one of these features is used. See the CMasher section of the colours guide for choosing a map and worked examples.

Functions

plotastro.cmasher_colors(cmap, n=8, *, cmap_range=(0.15, 0.85))

Discrete colours sampled from a CMasher colormap — e.g. a colour cycle for a family of lines. Needs the optional cmasher package.

Parameters:

• cmap (str or Colormap) – A CMasher colormap name, with or without the "cmr." prefix ("rainforest", "cmr.torch_r", …), or a Colormap object.

• n (int, optional) – Number of colours (default 8).

• cmap_range ((float, float), optional) – Part of the colormap to sample, in [0, 1]. The default (0.15, 0.85) follows CMasher’s own advice for line colours: most of its sequential maps run from black to white, and those ends vanish against the axes or the white page.

Returns:

list of str

Return type:

n hex colours, equally spaced in cmap_range.

Notes

Sequential maps make the best line colours. For lines that should be easy to tell apart, CMasher recommends maps with a large perceptual range (apple, chroma, neon, rainforest, torch); for lines that are steps of one quantity, a single-hue map (flamingo, freeze, gothic, jungle, ocean). Most diverging maps have a white or black centre, which the middle colours approach.

Examples

>>> pa.set_style("mnras", palette="cmr.rainforest")         # 8 colours
>>> ax.set_prop_cycle(color=pa.cmasher_colors("torch", n=5))

plotastro.cmasher_cmap(cmap, *, cmap_range=None, n=None)

A CMasher colormap, optionally cut to part of its range or split into n discrete colours. Needs the optional cmasher package.

Parameters:

• cmap (str or Colormap) – A CMasher colormap name, with or without the "cmr." prefix — e.g. "rainforest", "cmr.iceburn", "ocean_r" — or a Colormap object.

• cmap_range ((float, float), optional) – Keep only this part of the colormap (in [0, 1]), e.g. (0.15, 0.85) to drop the black and white ends. CMasher advises keeping at least half of a sequential map, so that it stays smooth.

• n (int, optional) – Split the map into n discrete colours — for filled contours or binned data.

Return type:

matplotlib.colors.Colormap

Examples

>>> ax.imshow(img, cmap=pa.cmasher_cmap("rainforest"))
>>> ax.contourf(x, y, z, levels=6, cmap=pa.cmasher_cmap("iceburn", n=6))

Once CMasher has been imported (by this function, by set_style(cmap=...), or by you), its maps can also be passed to matplotlib by name: cmap="cmr.rainforest".

Through set_style

argument	effect
set_style(palette="cmr.<name>")	colour cycle of 8 colours, cmasher_colors("<name>")
set_style(cmap="cmr.<name>")	default colormap for imshow, pcolormesh, scatter, …

Here the cmr. prefix is required. The two functions above accept names with or without it. Add _r to any name for the reversed map.

Once CMasher has been imported, by one of these calls or by import cmasher, matplotlib also accepts its maps by name: cmap="cmr.iceburn".

Errors

error	cause
ImportError: This feature needs the optional CMasher package	CMasher isn’t installed
ValueError: Unknown CMasher colormap '...'	the name isn’t a CMasher map in your version; cmasher.get_cmap_list() lists them
ValueError: Unknown palette '...'	set_style(palette=...) got a CMasher name without the cmr. prefix
ValueError: '...' is not a valid value for cmap	raised by matplotlib: a cmr. name was used before CMasher was imported

set_style checks the palette and colormap before it changes anything, so when it raises one of these errors the previous style is still active.