Colormap¶
- Colormap(*args, name=None, listmode='perceptual', filemode='continuous', discrete=False, cycle=None, save=False, save_kw=None, **kwargs)[source]¶
Generate, retrieve, modify, and/or merge instances of
PerceptualColormap
,ContinuousColormap
, andDiscreteColormap
.- Parameters
*args (
colormap-spec
) – Positional arguments that individually generate colormaps. If more than one argument is passed, the resulting colormaps are merged withappend
orappend
. 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 ProPlot colormap class.
If a filename string with valid extension, the colormap data is loaded with
proplot.colors.ContinuousColormap.from_file
orproplot.colors.DiscreteColormap.from_file
depending on the value offilemode
(see below). Default behavior is to load aContinuousColormap
.If RGB tuple or color string, a
PerceptualColormap
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 sequence of RGB tuples or color strings, a
DiscreteColormap
,PerceptualColormap
, orContinuousColormap
is generated depending on the value oflistmode
(see below). Default behavior is to generate aPerceptualColormap
.If dictionary, a
PerceptualColormap
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 passingcmap='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 usingfrom_file
. The resulting colormap may be aContinuousColormap
orPerceptualColormap
depending on the data file.If
'discrete'
, aDiscreteColormap
is generated usingfrom_file
.
Default is
'continuous'
when callingColormap
directly and'discrete'
whenColormap
is called byCycle
.listmode (
{'perceptual', 'continuous', 'discrete'}
, optional) – Controls how colormaps are generated when you input sequence(s) of colors. The options are as follows:If
'perceptual'
, aPerceptualColormap
is generated withfrom_list
.If
'continuous'
, aContinuousColormap
is generated withfrom_list
.If
'discrete'
, aDiscreteColormap
is generated by simply passing the colors to the class.
Default is
'perceptual'
when callingColormap
directly and'discrete'
whenColormap
is called byCycle
.samples (
int
or sequence ofint
, optional) – ForContinuousColormap
s, this is used to generateDiscreteColormap
s withto_discrete
. ForDiscreteColormap
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 sequence of integers, it applies to each input colormap individually.discrete (
bool
, optional) – IfTrue
, when the final colormap is aDiscreteColormap
, we leave it alone, but when it is aContinuousColormap
, we always callto_discrete
with a defaultsamples
value of10
. This argument is not necessary if you provide thesamples
argument.left, right (
float
or sequence offloat
, optional) – Truncate the left or right edges of the colormap. Passed totruncate
. If float, these apply to the final merged colormap. If sequence of float, these apply to each input colormap individually.cut (
float
or sequence offloat
, optional) – Cut out the center of the colormap. Passed tocut
. If float, this applies to the final merged colormap. If sequence of float, these apply to each input colormap individually.reverse (
bool
or sequence ofbool
, optional) – Reverse the colormap. Passed toreversed
. If float, this applies to the final merged colormap. If sequence of float, these apply to each input colormap individually.shift (
float
or sequence offloat
, optional) – Cyclically shift the colormap. Passed toshifted
. 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
orcolor-spec
or sequence, optional) – The opacity of the colormap or the opacity gradation. Passed toproplot.colors.ContinuousColormap.set_alpha
orproplot.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
, andchroma
.hue, saturation, luminance (
float
orcolor-spec
or sequence, optional) – The channel value(s) used to generate colormaps withfrom_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 sequence of floats instead of a single float. Note the defaultluminance
is90
ifdiscrete
isTrue
and100
otherwise.
chroma – Alias for
saturation
.cycle (
str
, optional) – The registered cycle name 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.ContinuousColormap.save
orproplot.colors.DiscreteColormap.save
.save_kw (dict-like, optional) – Ignored if
save
isFalse
. Passed to the colormap/color cycle save method, i.e.proplot.colors.ContinuousColormap.save
orproplot.colors.DiscreteColormap.save
.
- Other Parameters
**kwargs – Passed to
proplot.colors.ContinuousColormap.copy
,proplot.colors.PerceptualColormap.copy
, orproplot.colors.DiscreteColormap.copy
.- Returns
Colormap
– AContinuousColormap
orDiscreteColormap
instance.