ColorMyCells

A Biological Approach to Cell Type Visualization

colormycells is a Python package that solves a common problem in single-cell analysis: creating colormaps where the perceptual distance between colors meaningfully represents the biological similarity between cell types.

The Problem: Color Selection in Single-Cell Visualization

Standard colormaps like tab10 or rainbow aren't great when applied to single-cell data:

• Biological meaning is lost: Default colormaps assign colors arbitrarily, with no relation to cell type similarity
• Perceptual imbalance: Some colors jump out while others blend together, drawing attention to cell types for no biological reason
• Limited palette: Most standard colormaps support 10-20 colors, but you may have hundreds of cell types

Standard Colormap	ColorMyCells

Installation

bash pip install colormycells

For 3D visualization support, also install pillow and ipython.

Dependencies

• numpy
• pandas
• matplotlib
• seaborn
• scikit-learn
• scipy
• colour-science

Optional Dependencies (for 3D visualization)

• pillow
• ipython

Usage

```python import scanpy as sc from colormycells import get_colormap

Load your data

adata = sc.readh5ad("yourdata.h5ad")

Create a colormap based on cell type similarities

colors = getcolormap(adata, key="celltype")

Use the colormap for plotting

sc.pl.umap(adata, color="cell_type", palette=colors)

Visualize the color space with 2D and 3D plots

colors = getcolormap(adata, key="celltype", plot_colorspace=True)

A 2D scatter plot will be displayed, and in Jupyter notebooks

an interactive 3D rotating visualization will also be shown

Create reproducible colormap with seed

colors1 = getcolormap(adata, key="celltype", seed=123) colors2 = getcolormap(adata, key="celltype", seed=123) # colors1 and colors2 will be identical ```

You can also pass a file path directly:

```python

Load directly from file

colors = getcolormap("yourdata.h5ad", key="cell_type")

Works with various file formats

colors = getcolormap("expressionmatrix.csv", key="cell_type") ```

Try multiple seeds!

Each seed produces a new random colormap.

python colors1 = get_colormap(adata, key="cell_type", seed=2)

Parameters

• adata: AnnData object with observations/cells as rows and variables/genes as columns
• key: Key in adata.obs encoding cell type information (default: "cell_type")
• plot_colorspace: Whether to visualize the colorspace (default: False)
• include_unknown: Whether to include "Unknown" category in the colormap (default: False)
• unknown_color: Color to use for "Unknown" category if not included (default: 'w')
• deficiency: Type of color vision deficiency to simulate (options: None, "Deuteranomaly", "Protanomaly", "Tritanomaly", default: None)
• severity: Severity of color vision deficiency (0-100, default: 0)
• seed: Random seed for reproducible colormaps (default: 42, set to None for stochastic behavior)

Our Approach: Biology-Driven Color Assignment

colormycells takes a fundamentally different approach:

1. Biological similarity drives color selection: Similar cell types receive similar colors
2. Gene expression determines color: We use the average expression profile of each cell type (pseudobulk) to measure cell type similarity
3. Perceptually uniform color space: We map cell type relationships to the LUV color space, where perceptual distances are uniform
4. Intuitive visualization: The result is a colormap where visual intuition aligns with biological reality

The result is a colormap where: - Similar cell types appear in similar colors - Color distances reflect biological relationships - Visualizations become more intuitive to interpret

Note

Color vision deficiency simulation is currently not fully implemented.

License

GPL-3.0 License

How to Cite

If you use ColorMyCells in your research, please cite:

Ari Benjamin. (2025). ColorMyCells: A Python package for biologically faithful colormaps for cell type visualization. (Version 0.1.0). Zenodo. https://doi.org/10.5281/zenodo.15595324

or the bibtex entry:

bibtex @software{colormycells2025, author = {Benjamin, Ari}, title = {{ColorMyCells: A Python package for biologically faithful colormaps for cell type visualization}}, month = jun, year = 2025, publisher = {Zenodo}, version = {0.1.0}, doi = {10.5281/zenodo.15595324}, url = {https://doi.org/10.5281/zenodo.15595324}, note = {Available at: https://github.com/ZadorLaboratory/colormycells} }