lmcinnes/glasbey

Algorithmically create or extend categorical colour palettes

_ _ _ _ _

Glasbey Categorical Color Palette Tools

The glasbey library allows for the algorithmic creation of colour palettes designed for use with categorical data using techniques from the paper Colour Displays for Categorical Images by Glasbey, Heijden, Toh and Gray. You don't need to worry about the technical details however -- the glasbey library is easy to use.

It is quite common to require a colour palette for some categorical data such that each category has a visually distinctive colour. Usually one relies upon predefined colour palettes such as those from ColorBrewer, or provided by your plotting library of choice. Unfortunately such palettes do not always meet your needs: perhaps they don't have enough distinct colours and you don't want to re-use or cycle the palette; perhaps you have specific constraints you want to apply to get a certain look to your palette. Fortunately we can use math and perceptual colour spaces to create new palettes that maximize the perceptual visual distinctiveness of colours within constraints. It is also easy to extend an existing palette, or seed a created palette with some initial colours (perhaps your company or institutions colours). Lastly, glasbey makes it easy to generate block palettes, suitable for working with hierarchical categories.

Create categorical palettes

or constrain the palette options (e.g. to muted colours)

or extend existing palettes

or create block categorical palettes

Basic Usage

Creating new categorical colour palettes is as easy as single function call.

import glasbey

# Create a categorical palette with 15 colours
glasbey.create_palette(palette_size=15)
# Create a muted palette with 12 colours
glasbey.create_palette(palette_size=12, lightness_bounds=(20, 40), chroma_bounds=(40, 50))

It is also easy to extend an existing palette, or create a new palette from some seed colours.

import glasbey

# Add an extra 5 colours to matplotlib's tab10 palette
glasbey.extend_palette("tab10", palette_size=15)
# Seed a palette with some initial colours
glasbey.extend_palette(["#2a3e63", "#7088b8", "#fcaf3e", "#b87088"], palette_size=8)

Installation

Glasbey requires:

• numba
• numpy
• colorspacious
• matplotlib

Glasbey can be installed via pip:

pip install glasbey

To manually install this package:

wget https://github.com/lmcinnes/glasbey/archive/main.zip
unzip main.zip
rm main.zip
cd glasbey-main
python setup.py install

Acknowledgements

This library is heavily indebted to the original glasbey library by Sergey Alexandrov.

References

1. Glasbey, C., van der Heijden, G., Toh, V. F. K. and Gray, A. (2007), Colour Displays for Categorical Images. Color Research and Application, 32: 304-309
2. Luo, M. R., Cui, G. and Li, C. (2006), Uniform Colour Spaces Based on CIECAM02 Colour Appearance Model. Color Research and Application, 31: 320–330

License

Glasbey is MIT licensed. See the LICENSE file for details.

Contributing

Contributions are more than welcome! If you have ideas for features of projects please get in touch. Everything from code to notebooks to examples and documentation are all equally valuable so please don't feel you can't contribute. To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged in.

glasbey's Issues

Assigning colors to classes to maximize dissimilarity of neighbouring classes in a given embedding

Hi Leland, cool work! I wonder if you considered the following scenario: there is a 2D embedding (e.g. UMAP) of some data that contain K classes. We want to make a scatter plot and assign a distinct colour to each class. We want to do this assignment such that neighbouring classes (i.e. classes that partially overlap in the embedding, or are simply adjacent to each other) have as distinct colours as possible. I.e. if there are two shades of red, then they should be given to classes that are far away in the embedding.

I guess this could be be approached by first generating a colormap of K distinct suitable colours, and then assigning them to classes to maximize colour dissimilarity between "neighbouring" classes (could be measured by kNN overlap or some other method). This can be either solved greedily or with annealing.

Does this sound like something that could potentially be within the scope of glasbey?

Crash in `extend_colormap` when colormap contains more colors than requested

Thanks for the nice library. I've come across a bug that occurrs when I want to extend a matplotlib colormap, e.g., tab10, but request fewer colors than the initial colormap contains.

For instance

glasbey.extend_palette("tab10", 10)
glasbey.extend_palette("tab10", 15)

both work fine, but if I request something <10, e.g.,

glasbey.extend_palette("tab10", 5)

I get the following error

ValueError                                Traceback (most recent call last)
Input In [24], in <cell line: 2>()
      1 import glasbey
----> 2 glasbey.extend_palette("tab10", 5)

File ~/miniconda3/envs/ml/lib/python3.10/site-packages/glasbey/_glasbey.py:338, in extend_palette(palette, palette_size, grid_size, as_hex, grid_space, lightness_bounds, chroma_bounds, hue_bounds, red_bounds, green_bounds, blue_bounds, colorblind_safe, cvd_type, cvd_severity)
    334 if not colorblind_safe:
    335     palette = cspace_convert(palette, "sRGB1", "CAM02-UCS").astype(
    336         np.float32, order="C"
    337     )
--> 338     palette = generate_palette_cam02ucs(colors, palette, np.uint32(palette_size))
    339 else:
    340     cvd_space = {
    341         "name": "sRGB1+CVD",
    342         "cvd_type": cvd_type,
    343         "severity": cvd_severity,
    344     }

ValueError: cannot assign slice from input of different size

I understand that it makes no sense to actually call this function when the colormap contains enough colors, but I'm trying to integrate this into my plotting utils where the number of colors I need can be highly variable, so this would be a "nice to have". If nothing else, a less crpytic error would be preferrable.

installation error

Hi Leland,
When I install it with "pip install glasbey", I met the following ERROR message:

ERROR: Package 'glasbey' requires a different Python: 3.9.13 not in '>=3.10'

Do you have any idea how to solve it?

Consider not including matplotlib in install dependencies?

Hi and thanks for the snappy glasbey implementation here.

I work on a number of visualization libs (napari, and related projects), and am making a new lightweight cmap library for those who need, but don't want to bring on big dependencies like matplotlib. I'd like to include this library as the functional backing for glasbey, but the dependency on matplotlib is a dealbreaker. (ideally, numba would also be optional, but I can see how that's the a lot of the crux of what this library has to offer over the previous implementation).

I wonder if you'd consider vendoring just the few conversion functions you need from matplotlib, and making any export to matplotlib colormap instances lazily import matplotlib? (if someone is exporting to matplotlib colormap, it's likely they have it installed in their environment, but those who want a lean glasbey implementation don't necessarily)

I'd happily make a PR to this effect, but want to gauge your openness first.

thanks!