Colormap

Colormap(*args, name=None, listmode='perceptual', filemode='continuous', discrete=False, cycle=None, save=False, save_kw=None, **kwargs)

Generate, retrieve, modify, and/or merge instances of PerceptualColormap, ContinuousColormap, and DiscreteColormap.

Parameters:

• *args (colormap-spec) – Positional arguments that individually generate colormaps. If more than one argument is passed, the resulting colormaps are merged with append or append. The arguments are interpreted as follows:

  • If a registered colormap name, that colormap instance is looked up. If colormap instance is a native matplotlib colormap class, it is converted to a ultraplot colormap class.

  • If a filename string with valid extension, the colormap data is loaded with ultraplot.colors.ContinuousColormap.from_file or ultraplot.colors.DiscreteColormap.from_file depending on the value of filemode (see below). Default behavior is to load a ContinuousColormap.

  • If RGB tuple or color string, a PerceptualColormap is generated with from_color. If the string ends in '_r', the monochromatic map will be reversed, i.e. will go from dark to light instead of light to dark.

  • If sequence of RGB tuples or color strings, a DiscreteColormap, PerceptualColormap, or ContinuousColormap is generated depending on the value of listmode (see below). Default behavior is to generate a PerceptualColormap.

  • If dictionary, a PerceptualColormap is generated with from_hsl. The dictionary should contain the keys 'hue', 'saturation', 'luminance', and optionally 'alpha', or their aliases (see below).

• name (str, optional) – Name under which the final colormap is registered. It can then be reused by passing cmap='name' to plotting functions. Names with leading underscores are ignored.

• filemode ({'perceptual', 'continuous', 'discrete'}, optional) – Controls how colormaps are generated when you input list(s) of colors. The options are as follows:

  • If 'perceptual' or 'continuous', a colormap is generated using from_file. The resulting colormap may be a ContinuousColormap or PerceptualColormap depending on the data file.

  • If 'discrete', a DiscreteColormap is generated using from_file.

  Default is 'continuous' when calling Colormap directly and 'discrete' when Colormap is called by Cycle.

• listmode ({'perceptual', 'continuous', 'discrete'}, optional) – Controls how colormaps are generated when you input sequence(s) of colors. The options are as follows:

  • If 'perceptual', a PerceptualColormap is generated with from_list.

  • If 'continuous', a ContinuousColormap is generated with from_list.

  • If 'discrete', a DiscreteColormap is generated by simply passing the colors to the class.

  Default is 'perceptual' when calling Colormap directly and 'discrete' when Colormap is called by Cycle.

• samples (int or sequence of int, optional) – For ContinuousColormaps, this is used to generate DiscreteColormaps with to_discrete. For DiscreteColormaps, this is used to updates the number of colors in the cycle. If samples is integer, it applies to the final merged colormap. If it is a sequence of integers, it applies to each input colormap individually.

• discrete (bool, optional) – If True, when the final colormap is a DiscreteColormap, we leave it alone, but when it is a ContinuousColormap, we always call to_discrete with a default samples value of 10. This argument is not necessary if you provide the samples argument.

• left, right (float or sequence of float, optional) – Truncate the left or right edges of the colormap. Passed to :method:`~ultraplot.colors.ContinuousColormap.truncate`. If float, these apply to the final merged colormap. If sequence of float, these apply to each input colormap individually.

• cut (float or sequence of float, optional) – Cut out the center of the colormap. Passed to cut. If float, this applies to the final merged colormap. If sequence of float, these apply to each input colormap individually.

• reverse (bool or sequence of bool, optional) – Reverse the colormap. Passed to reversed. If float, this applies to the final merged colormap. If sequence of float, these apply to each input colormap individually.

• shift (float or sequence of float, optional) – Cyclically shift the colormap. Passed to :property:`~ultraplot.colors.ContinuousColormap.shifted`. If float, this applies to the final merged colormap. If sequence of float, these apply to each input colormap individually.

• a – Shorthand for alpha.

• alpha (float or color-spec or sequence, optional) – The opacity of the colormap or the opacity gradation. Passed to ultraplot.colors.ContinuousColormap.set_alpha or ultraplot.colors.DiscreteColormap.set_alpha. If float, this applies to the final merged colormap. If sequence of float, these apply to each colormap individually.

• h, s, l, c – Shorthands for hue, luminance, saturation, and chroma.

• hue, saturation, luminance (float or color-spec or sequence, optional) – The channel value(s) used to generate colormaps with from_hsl and from_color.

  • If you provided no positional arguments, these are used to create an arbitrary perceptually uniform colormap with from_hsl. This is an alternative to passing a dictionary as a positional argument with hue, saturation, and luminance as dictionary keys (see args).

  • If you did provide positional arguments, and any of them are color specifications, these control the look of monochromatic colormaps generated with from_color. To use different values for each colormap, pass a sequence of floats instead of a single float. Note the default luminance is 90 if discrete is True and 100 otherwise.

• chroma – Alias for saturation.

• cycle (str, optional) – The registered cycle name used to interpret color strings like 'C0' and 'C2'. Default is from the active property rc.cycle. This lets you make monochromatic colormaps using colors selected from arbitrary cycles.

• save (bool, optional) – Whether to call the colormap/color cycle save method, i.e. ultraplot.colors.ContinuousColormap.save or ultraplot.colors.DiscreteColormap.save.

• save_kw (dict-like, optional) – Ignored if save is False. Passed to the colormap/color cycle save method, i.e. ultraplot.colors.ContinuousColormap.save or ultraplot.colors.DiscreteColormap.save.

Other Parameters:

**kwargs – Passed to ultraplot.colors.ContinuousColormap.copy, ultraplot.colors.PerceptualColormap.copy, or ultraplot.colors.DiscreteColormap.copy.

Returns:

matplotlib.colors.Colormap – A ContinuousColormap or DiscreteColormap instance.

See also

matplotlib.colors.Colormap, matplotlib.colors.LinearSegmentedColormap, matplotlib.colors.ListedColormap, ultraplot.constructor.Norm, ultraplot.constructor.Cycle, ultraplot.utils.get_colors