Colormap¶
- Colormap(*args, name=None, listmode='perceptual', to_listed=False, cycle=None, save=False, save_kw=None, **kwargs)[source]¶
Generate, retrieve, modify, and/or merge instances of
PerceptuallyUniformColormap
,LinearSegmentedColormap
, andListedColormap
. Used to interpret thecmap
andcmap_kw
arguments when passed to any plotting method wrapped byapply_cmap
.- Parameters
*args (colormap-spec) – Positional arguments that individually generate colormaps. If more than one argument is passed, the resulting colormaps are merged with
append
orappend
. Arguments are interpreted as follows:If the argument is a
Colormap
or a registered colormap name, nothing more is done.If a filename string with valid extension, the colormap data will be loaded. See
register_cmaps
andregister_cycles
.If RGB tuple or color string, a
PerceptuallyUniformColormap
is generated withfrom_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 list of RGB tuples or color strings, a
PerceptuallyUniformColormap
is generated withfrom_list
.If dictionary, a
PerceptuallyUniformColormap
is generated withfrom_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 likecontourf
.listmode ({‘perceptual’, ‘linear’, ‘listed’}, optional) – Controls how colormaps are generated when you input list(s) of colors. If
'perceptual'
, aPerceptuallyUniformColormap
is generated withfrom_list
. If'linear'
, aLinearSegmentedColormap
is generated withfrom_list
. If'listed'
, aListedColormap
is generated. Default is'perceptual'
when callingColormap
directly and'listed'
whenColormap
is called byCycle
.samples (int or list of int, optional) – For
LinearSegmentedColormap
s, this is used to generateListedColormap
s withto_listed
. ForListedColormap
s, this is used to updates the number of colors in the cycle. Ifsamples
is integer, it applies to the final merged colormap. If it is a list of integers, it applies to each input colormap individually.to_listed (bool, optional) – If
True
, when the final colormap is aListedColormap
, we leave it alone, but when it is aLinearSegmentedColormap
, we always callto_listed
with a defaultsamples
value of10
. This argument is not necessary if you provide thesamples
argument.left, right (float or list of float, optional) – Truncate the left or right edges of the colormap. Passed to
truncate
. If float, these apply to the final merged colormap. If list of float, these apply to each input colormap individually.cut (float or list of float, optional) – Cut out the center of the colormap. Passed to
cut
. If float, this applies to the final merged colormap. If list of float, these apply to each input colormap individually.reverse (bool or list of bool, optional) – Reverse the colormap. Passed to
reversed
. If float, this applies to the final merged colormap. If list of float, these apply to each input colormap individually.shift (float or list of float, optional) – Cyclically shift the colormap. Passed to
shifted
. If float, this applies to the final merged colormap. If list of float, these apply to each input colormap individually.a – Shorthand for
alpha
.alpha, a (channel-spec or list of channel-spec, optional) – The opacity of the colormap or the opacity gradation. Passed to
proplot.colors.LinearSegmentedColormap.set_alpha
orproplot.colors.ListedColormap.set_alpha
. If float, this applies to the final merged colormap. If list of float, these apply to each colormap individually.h, s, l, c – Shorthands for
hue
,luminance
,saturation
, andchroma
.hue, saturation, luminance (channel-spec or list of channel-spec, optional) – The channel value(s) used to generate colormaps with
from_hsl
andfrom_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 withhue
,saturation
, andluminance
as dictionary keys (seeargs
).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 list of floats instead of a scalar. Note the defaultluminance
is90
ifto_listed
isTrue
and100
otherwise.
chroma – Alias for
saturation
.cycle (str or list of str, optional) – The registered cycle name or a list of colors used to interpret cycle color strings like
'C0'
and'C2'
. Default is from the active property cycler. This lets you make monochromatic colormaps using colors selected from arbitrary property cycles.save (bool, optional) – Whether to call the colormap/color cycle save method, i.e.
proplot.colors.LinearSegmentedColormap.save
orproplot.colors.ListedColormap.save
.save_kw (dict-like, optional) – Ignored if
save
isFalse
. Passed to the colormap/color cycle save method, i.e.proplot.colors.LinearSegmentedColormap.save
orproplot.colors.ListedColormap.save
.
- Other Parameters
**kwargs – Passed to
proplot.colors.LinearSegmentedColormap.copy
,proplot.colors.PerceptuallyUniformColormap.copy
, orproplot.colors.ListedColormap.copy
.- Returns
Colormap
– ALinearSegmentedColormap
orListedColormap
instance.