---
title: "colorspace: A Python Toolbox for Manipulating and Assessing Colors and Palettes"
bibliography: references.bib
---

The colorspace package provides a broad toolbox for selecting individual colors
or color palettes, manipulating colors, and employing them in various
kinds of visualizations.

At the core of the package is a class which allows to draw and transform colors
in different color spaces (as the package name conveys). Thus, the package
helps to map various three-dimensional representations of color to each other.
A particularly important mapping is the one from the perceptually-based and
device-independent color model HCL (Hue-Chroma-Luminance) to standard
Red-Green-Blue (sRGB) which is the basis for color specifications in many
systems based on the corresponding hex codes (e.g., in HTML but also in R). For
completeness further standard color models are included as well in the package:
[`polarLUV`](/man/colorspace.colorlib.polarLUV.qmd) (=HCL),
[`CIELUV`](/man/colorspace.colorlib.CIELUV.qmd),
[`polarLAB`](/man/colorspace.colorlib.polarLAB.qmd),
[`CIELAB`](/man/colorspace.colorlib.CIELAB.qmd),
[`CIEXYZ`](/man/colorspace.colorlib.CIEXYZ.qmd),
[`RGB`](/man/colorspace.colorlib.RGB.qmd),
[`sRGB`](/man/colorspace.colorlib.sRGB.qmd),
[`HLS`](/man/colorspace.colorlib.HLS.qmd),
[`HSV`](/man/colorspace.colorlib.HSV.qmd).

The HCL space (= polar coordinates in
[`CIELUV`](/man/colorspace.colorlib.CIELUV.qmd)) is particularly useful for
specifying individual colors and color palettes as its three axes match those
of the human visual system very well: Hue (= type of color, dominant
wavelength), chroma (= colorfulness), luminance (= brightness).


```{python}
#| echo: true

from colorspace import palette, sequential_hcl, swatchplot

H = palette(sequential_hcl(h = [0, 300], c = [60, 60], l = 65).colors(5), "Hue")
C = palette(sequential_hcl(h = 0, c = [0, 100], l = 65, power = 1).colors(5), "Chroma")
L = palette(sequential_hcl(h = 260, c = [25, 25], l = [90, 25], power = 1).colors(5), "Luminance")

swatchplot([H, C, L], figsize = (5, 1.5));
```


The colorspace package provides three types of palettes based on the HCL model:

* *Qualitative*: Designed for coding categorical information, i.e., where no
  particular ordering of categories is available and every color should receive
  the same perceptual weight.
  Class: [`qualitative_hcl`](/man/colorspace.palettes.qualitative_hcl.qmd).
* *Sequential*: Designed for coding ordered/numeric information, i.e., where
  colors go from high to low (or vice versa).
  Class: [`sequential_hcl`](/man/colorspace.palettes.sequential_hcl.qmd).
* *Diverging*: Designed for coding ordered/numeric information around a central
  neutral value, i.e., where colors diverge from neutral to two extremes.
  Class: [`diverging_hcl`](/man/colorspace.palettes.diverging_hcl.qmd).

To aid choice and application of these palettes there are: scales for use with
matplotlib and an app for interactive exploration; visualizations of palette
properties; accompanying manipulation utilities (like
[`desaturation`](/man/colorspace.CVD.desaturate.qmd),
[`lighten`](/man/colorspace.utils.lighten.qmd)/[`darken`](/man/colorspace.utils.darken.qmd),
and emulation of color vision deficiencies).


More detailed overviews and examples are provided in the articles:

* [Installation](/installation.qmd)
* [Color spaces](/articles/color_spaces.qmd)
* [HCL-Based Color Palettes](/articles/hcl_palettes.qmd)
* [Palette Visualization and Assessment](/articles/palette_visualization.qmd)
* [App for Choosing Palettes Interactively](/articles/choose_palette.qmd)
* [Color Vision Deficiency Emulation](/articles/cvd.qmd)
* [Color Manipulation and Utilities](/articles/manipulation_utilities.qmd)
* [Approximate Colors from Other Packages](/articles/approximations.qmd)
* [Somewhere over the Rainbow](/articles/endrainbow.qmd)

## Installation

The latest release candidate of this package is
available via the [Python Package Index (PyPI)](https://pypi.org/project/colorspace/)
as well as on [GitHub](https://https://github.com/retostauffer/python-colorspace>).

**Install via pip**

The installation of the latest release can be done using pip. Will automatically
install the necessary requirement (`numpy`). To use the full functionality of the
package, `matplotlib` and `imageio` will be needed to be installed, though not
required for [visualization](/articles/palette_visualization.qmd)
and [CVD emulation](/articles/cvd.qmd).
Check out the [Installation](/installation.qmd) page for more details.


```
pip install colorspace
# pip install matplotlib
# pip install imageio
```


## Choosing HCL-based color palettes

The colorspace package ships with a wide range of predefined color palettes,
specified through suitable trajectories in the HCL (Hue-Chroma-Luminance) color
space. A quick overview can be gained easily with the
[`hcl_palettes`](/man/colorspace.hcl_palettes.hcl_palettes.qmd) function:



```{python}
#| echo: true
#| lightbox:
#|    group: hcl_palettes

from colorspace import hcl_palettes
hcl_palettes(plot = True, figsize = (15, 10));
```


A suitable palette object can be easily computed by specifying the desired
palette name (see the plot above), e.g.,

```{python}
#| echo: true

from colorspace import qualitative_hcl
pal = qualitative_hcl("Dark 3")
pal(4)  # Draw list of 4 colors across the palette
```


The functions [`sequential_hcl`](/man/colorspace.palettes.sequential_hcl.qmd)and
[`diverging_hcl`](/man/colorspace.palettes.diverging_hcl.qmd) work analogously.
Additionally, their hue/chroma/luminance parameters can be modified, thus
allowing for easy customization of each palette. 
Moreover, [`choose_palette`](/man/colorspace.choose_palette.choose_palette.qmd) 
provides a convenient user interfaces to perform palette customization
interactively.
Finally, even more flexible diverging HCL palettes are provided by
[`divergingx_hcl`](/man/colorspace.palettes.divergingx_hcl.qmd).


## Use with matplotlib, seaborn, and plotly graphics

The HCL-based color palettes can be integrated into commonly used
Python packages for plotting such as 
[`seaborn`](https://seaborn.pydata.org/),
[`plotly`](https://plotly.com/python/), and [`matplotlib`](https://matplotlib.org/).
For the latter all palettes come with a `cmap()` method to generate objects of 
class `LinearSegmentedColormap` as used by by matplotlib, making it straight forward
to be used with most matplotlib plotting functions.

Below, one example on how to use colors based on the _colorspace_ package
with matplotlib, seaborn, and plotly. Several additional examples can be found
on the dedicated articles:

* [HCL-Based Color Scales for matplotlib](/articles/usewith_matplotlib.qmd)
* [HCL-Based Color Scales for seaborn](/articles/usewith_seaborn.qmd)
* [HCL-Based Color Scales for plotly](/articles/usewith_plotly.qmd)

#### Matplotlib

The following figure shows a two-dimensional histogram
(joint density) of the daily minimum and maximum temperature observed
at a weather station in the Harz region in Germany using the
"HarzTraffic" data set. The custom HCL-based palette is provided
as 'cmap' (a `LinearSegmentedColormap`) using the `.cmap()` method.

Whilst the left supblot uses the sequential
HCL-based color palette "ag_Sunset" (reversed), the right plot shows
the same data using the "Blues 2" palette.

```{python matplotlib_minimal}
#| warning: true
#| error: true

from colorspace import sequential_hcl, dataset
import matplotlib.pyplot as plt

# Loading data
df = dataset("HarzTraffic")

# Creating new figure
fig, (ax1, ax2) = plt.subplots(1, 2, figsize = (10, 5))

ax1.hist2d(df.tempmin, df.tempmax, bins = 20,
           cmap = sequential_hcl("ag_Sunset", rev = True).cmap())
ax2.hist2d(df.tempmin, df.tempmax, bins = 20,
           cmap = sequential_hcl("Blues 2").cmap())

# Setting title and labels
ax1.set_title("Joint density daily min/max temperature")
ax1.set_xlabel("minimum temperature [deg C]")
ax1.set_ylabel("maximum temperature [deg C]")
ax2.set_title("Joint density daily min/max temperature")
ax2.set_xlabel("minimum temperature [deg C]")
plt.show()
```


#### Seaborn

To demonstrate the use of HCL-based colormaps with seaborn, 
the barplot below shows the average number of bikes per day of week (with error bars)
during summer seasons (June, July, August) 2021 to 2023.

```{python seaborn_minimal}
#| warning: true
#| error: true
#| layout-ncol: 1

from colorspace import qualitative_hcl, dataset
import matplotlib.pyplot as plt
import seaborn as sns

# Loading data set
df = dataset("HarzTraffic")
df = df.loc[(df.season == "summer"), :]

sns.barplot(x = "dayofweek", y = "bikes", hue = "dow", data = df,
            order = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
            legend = False,
            palette = qualitative_hcl("Harmonic").colors(7))
plt.title("Average number of bikes per day of week\nsummer season 2021-2023")
plt.show()
```

#### Plotly

Finally, an example using the plotly graphics library is shown.
The interactive plot below shows the daily mean temperature plotted
against the day of year (Julian day) for the three consecutive years
2021, 2022, and 2023 using colors from the (slightly adjusted) diverging HCL-based
color palette "Blue-Red".

```{python plotly_minimal}
#| warning: true
#| error: true

from colorspace import diverging_hcl, dataset
import plotly.express as px
import pandas as pd

df = dataset("HarzTraffic")
df["year"] = pd.DatetimeIndex(df.date).year

# Picking three colors from (adjusted) diverging color map
cols = diverging_hcl("Blue-Red", l2 = 60).colors(3)

# Plotting
fig = px.line(df, x = "yday", y = "temp", color = "year",
        title = "Daily mean temperature<br>Sonnenberg, Harz, Germany",
        color_discrete_sequence = cols,
        template = "plotly_white",
        labels = {"yday": "day of year", "temp": "temperature [deg C]"})
fig.show()
```



## Palette visualization and assessment

The *colorspace* package also provides a number of functions that aid
visualization and assessment of its palettes. The
[`demoplot`](/man/colorspace.demos.demoplot.qmd) function
provides a series of generic/basic plot types as used by the
interactive interface ([`choose_palette`](/man/colorspace.choose_palette.choose_palette.qmd)
which can also be used in-line to test color palettes.

In addition, [`specplot`](/man/colorspace.specplot.specplot.qmd) allows to visualize and
graphically assess the spectrum of a series of colors in the RGB and HCL spectrum,
whilst [`hclplot`](/man/colorspace.hclplot.hclplot.qmd) converts the colors of
a palette to the corresponding hue/chroma/luminance coordinates and displays
them in HCL space with one dimension collapsed. The collapsed dimension is the
luminance for qualitative palettes and the hue for sequential/diverging
palettes.



```{python}
#| echo: true

from colorspace import diverging_hcl, demoplot
import matplotlib.pyplot as plt

fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize = (10, 3.5))
pal = diverging_hcl("Purple-Green")
demoplot(pal, "Map",    ax = ax1)
demoplot(pal, "Bar",    ax = ax2)
demoplot(pal, "Matrix", ax = ax3)
plt.show()
```

```{python}
#| echo: true

from colorspace import diverging_hcl, specplot
pal = diverging_hcl("Purple-Green")
specplot(pal(100), hcl = True, palette = True, rgb = True);
```

```{python}
#| echo: true

from colorspace import sequential_hcl, diverging_hcl, qualitative_hcl, hclplot
import matplotlib.pyplot as plt

fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize = (10, 3.5))
hclplot(sequential_hcl()(7),  ax = ax1)
hclplot(diverging_hcl()(7),   ax = ax2)
hclplot(qualitative_hcl()(7), ax = ax3)
plt.show()
```






