CMasher

Scientific colormaps for making accessible, informative and cmashing plots.

cmasher.create_cmap_mod(cmap, *, save_dir='.')[source]

Creates a standalone Python module of the provided CMasher cmap and saves it in the given save_dir as ‘<cmap>.py’.

A standalone colormap module can be used to quickly share a colormap with someone without adding the CMasher dependency. Importing the created module allows the colormap to be used in the same way as usual through MPL (including the ‘cmr.’ prefix).

Parameters:cmap (str) – The name of the CMasher colormap a standalone Python module must be made for. An added ‘cmr.’ prefix will be ignored.
Other Parameters:
 save_dir (str. Default: ‘.’) – The path to the directory where the module must be saved. By default, the current directory is used.
Returns:cmap_path (str) – The path to the Python file containing the colormap module.

Example

Creating a standalone Python module of the ‘rainforest’ colormap:

>>> create_cmap_mod('rainforest')

One can now import the ‘rainforest’ colormap in any script by moving the created ‘rainforest.py’ file to the proper working directory and importing it with import rainforest.

Note

Unlike other CMasher utility functions, cmap solely accepts names of colormaps that are registered in CMasher (cmasher.cm).

cmasher.create_cmap_overview(cmaps=None, *, savefig=None, use_types=True, sort='alphabetical', plot_profile=False, title='Colormap Overview')[source]

Creates an overview plot containing all colormaps defined in the provided cmaps.

Other Parameters:
 
  • cmaps (list of {str; Colormap objects}, dict of lists or None. Default: None) – A list of all colormaps that must be included in the overview plot. If dict of lists, the keys define categories for the colormaps. If None, all colormaps defined in CMasher are used instead.
  • savefig (str or None. Default: None) – If not None, the path where the overview plot must be saved to. Else, the plot will simply be shown.
  • use_types (bool. Default: True) – Whether all colormaps in cmaps should be categorized into their colormap types (sequential; diverging; cyclic; qualitative; misc). If cmaps is a dict, this value is ignored.
  • sort ({‘alphabetical’/’name’; ‘lightness’}, function or None. Default: ‘alphabetical’) – String or function indicating how the colormaps should be sorted in the overview. If ‘alphabetical’, the colormaps are sorted alphabetically on their name. If ‘lightness’, the colormaps are sorted based on their lightness profile. If function, a function definition that takes a Colormap object and returns the sorted position of that colormap. If None, the colormaps retain the order they were given in.
  • plot_profile (bool or float. Default: False) – Whether the lightness profiles of all colormaps should be plotted. If not False, the lightness profile of a colormap is plotted on top of its gray-scale version and plot_profile is used for setting the alpha (opacity) value. If plot_profile is True, it will be set to 0.25.
  • title (str or None. Default: “Colormap Overview”) – String to be used as the title of the colormap overview. If empty or None, no title will be used.

Notes

The colormaps in cmaps can either be provided as their registered name in matplotlib.cm, or their corresponding Colormap object. Any provided reversed colormaps (colormaps that end their name with ‘_r’) are ignored if their normal versions were provided as well.

If plot_profile is not set to False, the lightness profiles are plotted on top of the gray-scale colormap versions, where the y-axis ranges from 0% lightness to 100% lightness. The lightness profile transitions between black and white at 50% lightness.

cmasher.get_bibtex()[source]

Prints a string that gives the BibTeX entry for citing the CMasher paper (Van der Velden 2020, JOSS, 5, 2004).

cmasher.get_cmap_type(cmap)[source]

Checks what the colormap type (sequential; diverging; cyclic; qualitative; misc) of the provided cmap is and returns it.

Parameters:cmap (str or Colormap object) – The registered name of the colormap in matplotlib.cm or its corresponding Colormap object.
Returns:cm_type ({‘sequential’; ‘diverging’; ‘cyclic’; ‘qualitative’; ‘misc’}) – A string stating which of the defined colormap types the provided cmap has.
cmasher.get_sub_cmap(cmap, start, stop)[source]

Creates a ListedColormap object using the colors in the range [start, stop] of the provided cmap and returns it.

This function can be used to create a colormap that only uses a portion of an existing colormap.

New in version 1.3.2.

Parameters:
  • cmap (str or Colormap object) – The registered name of the colormap in matplotlib.cm or its corresponding Colormap object.
  • start, stop (float) – The normalized range of the colors in cmap that must be in the sub colormap.
Returns:

sub_cmap (ListedColormap) – The created colormap that uses a subset of the colors in cmap.

Example

Creating a colormap using the first 80% of the ‘rainforest’ colormap:

>>> get_sub_cmap('cmr.rainforest', 0, 0.8)

Notes

As it can create artifacts, this function does not interpolate between the colors in cmap to fill up the space. Therefore, using values for start and stop that are too close to each other, may result in a colormap that contains too few different colors to be smooth. It is recommended to use at least 128 different colors in a colormap for optimal results (CMasher colormaps have 256 or 511 different colors, for sequential or diverging colormaps respectively). One can check the number of colors in a colormap with matplotlib.colors.Colormap.N.

Any colormaps created using this function are not registered in either CMasher or MPL.

cmasher.import_cmaps(cmap_path)[source]

Reads in custom colormaps from a provided file or directory cmap_path; transforms them into ListedColormap objects; and makes them available in the cmasher.cm module, in addition to registering them in the matplotlib.cm module. Both the imported colormap and its reversed version will be registered.

If a provided colormap is a ‘cyclic’ colormap, its shifted version will also be registered.

Parameters:cmap_path (str) – Relative or absolute path to a custom colormap file; or directory that contains custom colormap files. A colormap file can be a NumPy binary file (‘.npy’); a viscm source file (‘.jscm’); or any text file. If the file is not a JSCM-file, it must contain the normalized RGB values that define the colormap.

Notes

All colormap files must have names starting with the ‘cm_’ prefix. The resulting colormaps will have the name of their file without the prefix and extension.

In MPL, the colormaps will have the added ‘cmr.’ prefix to avoid name clashes.

Example

Importing a colormap named ‘test’ can be done by saving its normalized RGB values in a file called ‘cm_test.txt’ and executing

>>> import_cmaps('/path/to/dir/cm_test.txt')

The ‘test’ colormap is now available in CMasher and MPL using

>>> cmr.cm.test                 # CMasher
>>> plt.get_cmap('cmr.test')    # MPL
cmasher.register_cmap(name, data)[source]

Creates a ListedColormap object using the provided name and data, and registers the colormap in the cmasher.cm and matplotlib.cm modules. A reversed version of the colormap will be registered as well.

Parameters:
  • name (str) – The name that this colormap must have.
  • data (2D array_like of {float; int} with shape (N, 3)) – An array containing the RGB values of all segments in the colormap. If int, the array contains 8-bit RGB values. If float, the array contains normalized RGB values.

Note

In MPL, the colormap will have the added ‘cmr.’ prefix to avoid name clashes.

cmasher.set_cmap_legend_entry(artist, label)[source]

Sets the label of the provided artist to label, and creates a legend entry using a miniature version of the colormap of artist as the legend icon.

This function can be used to add legend entries for MPL artists that use a colormap, like those made with hexbin(); hist2d(); scatter(); or any pyplot function that takes cmap as an input argument. Keep in mind that using this function will override any legend entry that already exists for artist.

Parameters:
  • artist (Artist object) – Any artist object that has the cmap attribute, for which a legend entry must be made using its colormap as the icon.
  • label (str) – The string that must be set as the label of artist.
cmasher.take_cmap_colors(cmap, N, *, cmap_range=(0, 1), return_fmt='float')[source]

Takes N equally spaced colors from the provided colormap cmap and returns them.

New in version 1.3.2.

Parameters:
  • cmap (str or Colormap object) – The registered name of the colormap in matplotlib.cm or its corresponding Colormap object.
  • N (int or None) – The number of colors to take from the provided cmap. If None, take all colors in cmap within the provided cmap_range.
Other Parameters:
 
  • cmap_range (tuple of float. Default: (0, 1)) – The normalized value range in the colormap from which colors should be taken. By default, colors are taken from the entire colormap.
  • return_fmt ({‘float’/’norm’; ‘str’/’hex’; ‘int’/‘8bit’}. Default: ‘float’) – The format of the requested colors. If ‘float’/’norm’, the colors are returned as normalized RGB tuples. If ‘str’/’hex’, the colors are returned using their hexadecimal string representations. If ‘int’/‘8bit’, the colors are returned as 8-bit RGB tuples.
Returns:

colors (list of tuple, str) – The colors that were taken from the provided cmap.

Examples

Taking five equally spaced colors from the ‘rainforest’ colormap:

>>> take_cmap_colors('cmr.rainforest', 5)
[(0.0, 0.0, 0.0),
 (0.226123592, 0.124584033, 0.562997277),
 (0.0548210513, 0.515835251, 0.45667819),
 (0.709615979, 0.722863985, 0.0834727592),
 (1.0, 1.0, 1.0)]

Requesting their 8-bit RGB values instead:

>>> take_cmap_colors('cmr.rainforest', 5, return_fmt='int')
[(0, 0, 0),
 (58, 32, 144),
 (14, 132, 116),
 (181, 184, 21),
 (255, 255, 255)]

Requesting HEX-code values instead:

>>> take_cmap_colors('cmr.rainforest', 5, return_fmt='hex')
['#000000', '#3A2090', '#0E8474', '#B5B815', '#FFFFFF']

Requesting colors in a specific range:

>>> take_cmap_colors('cmr.rainforest', 5, cmap_range=(0.2, 0.8),
                     return_fmt='hex')
['#3E0374', '#10528A', '#0E8474', '#5CAD3C', '#D6BF4A']

Note

Using this function on a perceptually uniform sequential colormap, like those in CMasher, allows one to pick a number of line colors that are different but still sequential. This is useful when plotting a set of lines that describe the same property, but have a different initial state.