---
title: "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](colorspace.palettes.sequential_hcl.qmd) twice
with a prespecified set of hue, chroma, and luminance parameters. This is
similar to [diverging_hcl](colorspace.palettes.diverging_hcl.qmd) but allows for more flexibility:
[diverging_hcl](colorspace.palettes.diverging_hcl.qmd) 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](colorspace.palettes.diverging_hcl.qmd)).
* 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.

See also: [qualitative_hcl](colorspace.palettes.qualitative_hcl.qmd), [sequential_hcl](colorspace.palettes.sequential_hcl.qmd),
[diverging_hcl](colorspace.palettes.diverging_hcl.qmd), [rainbow_hcl](colorspace.palettes.rainbow_hcl.qmd), [heat_hcl](colorspace.palettes.heat_hcl.qmd),
[terrain_hcl](colorspace.palettes.terrain_hcl.qmd), [diverging_hsv](colorspace.palettes.diverging_hsv.qmd), and
[rainbow](colorspace.palettes.rainbow.qmd).

### Usage

<pre><code class='language-python'>divergingx_hcl(h=[192, 77, 21], c=[40, 35, 100],<br/>               l=[50, 95, 50],<br/>               power=[1.0, 1.0, 1.2, 1.0], cmax=20,<br/>               fixup=True, palette=None, rev=False,<br/>               *args, **kwargs)</code></pre>

### Arguments

<dl class="pyp-list param-list">
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:h">h</code><code class="argument-class">list</code>
  </dt>
 <dd>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).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:c">c</code><code class="argument-class">list</code>
  </dt>
 <dd>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`).</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:l">l</code><code class="argument-class">list</code>
  </dt>
 <dd>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.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:power">power</code><code class="argument-class">list</code>
  </dt>
 <dd>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.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:cmax">cmax</code><code class="argument-class">None, float, int, list, numpy.ndarray</code>
  </dt>
 <dd>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.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:fixup">fixup</code><code class="argument-class">bool</code>
  </dt>
 <dd>Only used when converting the HCL colors to hex.  Should RGB
values outside the defined RGB color space be corrected?</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:palette">palette</code><code class="argument-class">str</code>
  </dt>
 <dd>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.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:rev">rev</code><code class="argument-class">bool</code>
  </dt>
 <dd>Should the color map be reversed.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:*args">*args</code>
  </dt>
 <dd>Currently unused.</dd>
  <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
   <code id="colorspace.palettes.divergingx_hcl:**kwargs">**kwargs</code>
  </dt>
 <dd>Additional named arguments to overwrite the palette settings.
Allowed: `h1`, `h2`, `h3`, `c1`, `cmax1`, `c2`, `cmax2` `c3`,
`l1`, `l2`, `l3`, `p1`, `p2`, `p3`, `p4`.</dd>
</dl>

### 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

<dl class="pyp-list method-list">
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.cmap(n=256, name=&#x27;custom_hcl_cmap&#x27;)](colorspace.palettes.divergingx_hcl.cmap.qmd)</code>
    </dt>
    <dd>Create Matplotlib Compatible Color Map</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.colors(n=11, fixup=None, alpha=None, **kwargs)](colorspace.palettes.divergingx_hcl.colors.qmd)</code>
    </dt>
    <dd>Get Colors</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.get(key)](colorspace.palettes.divergingx_hcl.get.qmd)</code>
    </dt>
    <dd>Get Specific Palette Setting</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.hclplot(n=7, **kwargs)](colorspace.palettes.divergingx_hcl.hclplot.qmd)</code>
    </dt>
    <dd>Palette Plot in HCL Space</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.name()](colorspace.palettes.divergingx_hcl.name.qmd)</code>
    </dt>
    <dd>Get Palette Name</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.show_settings()](colorspace.palettes.divergingx_hcl.show_settings.qmd)</code>
    </dt>
    <dd>Show Palette Settings</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.specplot(n=180, *args, **kwargs)](colorspace.palettes.divergingx_hcl.specplot.qmd)</code>
    </dt>
    <dd>Color Spectrum Plot</dd>
    <dt style = "white-space: nowrap; font-family: monospace; vertical-align: top">
       <code>[divergingx_hcl.swatchplot(n=7, **kwargs)](colorspace.palettes.divergingx_hcl.swatchplot.qmd)</code>
    </dt>
    <dd>Palette Swatch Plot</dd>
</dl>


### Examples

```{python}
#| echo: true
#| warning: true
#| error: true
from colorspace import divergingx_hcl
pal1 = divergingx_hcl()
pal1.colors(5)
```

```{python}
#| echo: true
#| warning: true
#| error: true
pal1.swatchplot(show_names = False, figsize = (5.5, 0.5));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Different color palette by name
pal2 = divergingx_hcl("ArmyRose")
pal2.colors(7)
```

```{python}
#| echo: true
#| warning: true
#| error: true
pal2.swatchplot(show_names = False, figsize = (5.5, 0.5));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# The standard call of the object also returns hex colors
divergingx_hcl("Fall")(3)
```

```{python}
#| echo: true
#| warning: true
#| error: true
# 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();
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Drawing 5 colors from the custom palette.
pal3(3)
```

```{python}
#| echo: true
#| warning: true
#| error: true
# 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));
```

```{python}
#| echo: true
#| warning: true
#| error: true
# Checking settings of a specific palette
pal4 = divergingx_hcl("PRGn")
pal4.show_settings()
```




### Raises

<ul class="python-raises">
<li><code class="text-warning">TypeError</code>: If `fixup` is not bool.
<li><code class="text-warning">TypeError</code>: If `palette` is not `None` or str.
<li><code class="text-warning">TypeError</code>: If `cmax` not `Non`, float, int, list, numpy.ndarray.
<li><code class="text-warning">ValueError</code>: If `cmax` is list of length `&lt;1` or `&gt;2`.
<li><code class="text-warning">ValueError</code>: If `h`, `c`, `l`, `power`, `cmax` contain unexpected types or values.
<li><code class="text-warning">ValueError</code>: If `palette` is string, but palette with this name cannot be found.
<li><code class="text-warning">Exception</code>: If `h3` is not specified.
<li><code class="text-warning">ValueError</code>: If `**kwargs` are provides which are not among the allowed ones.
</ul>

