Diverging X HCL Color Palettes

Description

More flexible version of the diverging_hcl class. A diverging X palette basically consists of two multi-hue sequential palettes.

The divergingx_hcl function simply calls sequential_hcl twice with a prespecified set of hue, chroma, and luminance parameters. This is similar to diverging_hcl but allows for more flexibility: diverging_hcl employs two single-hue sequential palettes, always uses zero chroma for the neutral/central color, and restricts the chroma/luminance path to be the same in both “arms” of the palette. In contrast, divergingx_hcl relaxes this to two full multi-hue palettes that can thus go through a non-gray neutral color (typically light yellow). Consequently, the chroma/luminance paths can be rather unbalanced between the two arms.

With this additional flexibility various diverging palettes suggested by https://ColorBrewer2.org/ and CARTO (https://carto.com/carto-colors/), can be emulated along with the Zissou 1 palette from ‘wesanderson’, Cividis from ‘viridis’, and Roma from ‘scico’.

Available CARTO palettes: ArmyRose, Earth, Fall, Geyser, TealRose, Temps, and Tropic (available in diverging_hcl).
Available ColorBrewer.org palettes: PuOr, RdBu, RdGy, PiYG, PRGn, BrBG, RdYlBu, RdYlGn, Spectral.

If h is str it will overwrite the palette argument. In this case, pre-specified palette settings will be loaded but are allowed to be overwritten by the user. At any time the user can overwrite any of the settings.

Usage

divergingx_hcl(h=[192, 77, 21], c=[40, 35, 100],
               l=[50, 95, 50],
               power=[1.0, 1.0, 1.2, 1.0], cmax=20,
               fixup=True, palette=None, rev=False,
               *args, **kwargs)

Arguments

hlist: Hue values (color), list of three numerics. Divergingx color palettes should have different hues for both ends and the center of the palette. For this class three values must be provided. If input h is a str this argument acts like the palette argument (see palette input parameter).
clist: Chroma value (colorfullness), list of floats. In case two values are provided the firt is taken as c1 and c3 while the second one is used for c2 (center value). When three values are provided they are used as c1, c2, and c3 (see also cmax).
llist: Luminance values (lightness), list of float/int. In case two values are provided the firt is taken as l1 and l3 while the second one is used for l2 (center value). When three are provided they are used as l1, l2, and l3 respectively.
powerlist: Power parameters for non-linear behaviour of the color palette, list of floats. If two values are provided power[0] will be used for p1 and p4 while power[1] is used for p2 and p3 (symmetric). A list of length four allows to specify p1, p2, p3, and p4 individually. List of length three acts like a list of length two, the last element is ignored.
cmaxNone, float, int, list, numpy.ndarray: Maximum chroma for triangular trajectory. Unused if set Non. If one value is provided it is used for cmax1, if two values are provided they are used as cmax1 and cmax2, respectively.
fixupbool: Only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?
palettestr: Can be used to load a default diverging color palette specification. If the palette does not exist an exception will be raised. Else the settings of the palette as defined will be used to create the color palette.
revbool: Should the color map be reversed.
*args: Currently unused.
**kwargs: Additional named arguments to overwrite the palette settings. Allowed: h1, h2, h3, c1, cmax1, c2, cmax2 c3, l1, l2, l3, p1, p2, p3, p4.

Return

Initialize new object, no return. Raises a set of errors if the parameters are misspecified. Note that the object is callable, the default object call can be used to return hex colors (identical to the .colors() method), see examples.

Methods

divergingx_hcl.cmap(n=256, name='custom_hcl_cmap'): Create Matplotlib Compatible Color Map
divergingx_hcl.colors(n=11, fixup=None, alpha=None, **kwargs): Get Colors
divergingx_hcl.get(key): Get Specific Palette Setting
divergingx_hcl.hclplot(n=7, **kwargs): Palette Plot in HCL Space
divergingx_hcl.name(): Get Palette Name
divergingx_hcl.show_settings(): Show Palette Settings
divergingx_hcl.specplot(n=180, *args, **kwargs): Color Spectrum Plot
divergingx_hcl.swatchplot(n=7, **kwargs): Palette Swatch Plot

Examples

from colorspace import divergingx_hcl
pal1 = divergingx_hcl()
pal1.colors(5)

['#008585', '#9BBAA0', '#FBF2C4', '#DEA868', '#C7522B']

pal1.swatchplot(show_names = False, figsize = (5.5, 0.5));

# Different color palette by name
pal2 = divergingx_hcl("ArmyRose")
pal2.colors(7)

['#D66982', '#DF94A3', '#EEBEC7', '#FFF2F7', '#F3C3B2', '#BEA062', '#798233']

pal2.swatchplot(show_names = False, figsize = (5.5, 0.5));

# The standard call of the object also returns hex colors
divergingx_hcl("Fall")(3)

['#3C5941', '#FBF2C4', '#C7522B']

# Manual palette with user settings. The following diverginx
# palette goes from h = 180 (left) to h = 100 (center) and h = 20 (right).
# Croma is c = 30 (left), c = 5 (center), and c = 30 (right).
# In addition, both 'arms' have a maximum chroma of cmax = 70
# in the center of each of the two arms.
pal3 = divergingx_hcl(h = [180, 100, 20], 
                      c = [30, 5, 30],
                      cmax = [70, 70]) 
pal3.specplot();

# Drawing 5 colors from the custom palette.
pal3(3)

['#3C827A', '#EFF2EB', '#976D66']

# Available default palettes (divergingx_hcl palettes)
from colorspace import divergingx_hcl, swatchplot, palette
carto  = ["ArmyRose", "Earth", "Fall",
          "Geyser", "TealRose", "Temps"]                 
brewer = ["PuOr", "RdBu", "RdGy", "PiYG", "PRGn",
          "BrBG", "RdYlBu", "RdYlGn", "Spectral"]
others = ["Zissou 1", "Cividis", "Roma"]
# Create named palettes for swatchplot
col_carto  = [palette(divergingx_hcl(x)(11), name = x) for x in carto]
col_brewer = [palette(divergingx_hcl(x)(11), name = x) for x in carto]
col_others = [palette(divergingx_hcl(x)(11), name = x) for x in others]
# Visualize available divergingx palettes
swatchplot({"Carto":  col_carto,
            "Brewer": col_brewer,
            "Others": col_others},
           figsize = (5.5, 6));

# Checking settings of a specific palette
pal4 = divergingx_hcl("PRGn")
pal4.show_settings()

Class:  divergingx_hcl
h1           300
h2         300.0
h3           128
c1            30
cmax1         65
c2             0
cmax2         65
c3            30
l1            15
l2            97
l3            25
p1           1.3
p2           1.2
p3           0.9
p4           1.5
fixup       True

Raises

TypeError: If fixup is not bool.
TypeError: If palette is not None or str.
TypeError: If cmax not Non, float, int, list, numpy.ndarray.
ValueError: If cmax is list of length <1 or >2.
ValueError: If h, c, l, power, cmax contain unexpected types or values.
ValueError: If palette is string, but palette with this name cannot be found.
Exception: If h3 is not specified.
ValueError: If **kwargs are provides which are not among the allowed ones.