stanhue

Automatic, publication-quality colors for scatter plots with many categorical labels.
_{Infers lineage structure from the 2D layout · keeps related categories in one hue family · pushes overlapping categories apart}

Install · Quick start · Overlap-aware · How it works · API · FAQ

PBMC CITE-seq · 57 cell types	Brain · 21 cell types · 2.5 M cells
Heart · 17 cell types	Meniscus · 15 cell types

_{Every plot above is colored fully automatically — no manual palette picking.}

Why stanhue?

With 30+ categories on a UMAP, random palettes scatter similar hues across unrelated groups and sequential palettes make neighbors indistinguishable. Picking colors by hand is tedious and rarely looks good.

stanhue reads the structure out of the 2D layout itself and assigns colors so that:

One function, two inputs, returns {label: "#hex"}. You keep your own plotting code.

Installation

Python

pip install stanhue

R — no packages needed beyond base R:

source("https://raw.githubusercontent.com/chansigit/stanhue/main/scatter_colormap.R")

Claude Code plugin

/plugins add chansigit/stanhue

Then mention "stanhue" in a conversation to activate the skill.

Prefer a single file? stanhue/scatter_colormap.py is a standalone script that only needs numpy and scipy.

Quick start

Python

from stanhue import assign_celltype_colors

colors = assign_celltype_colors(adata.obsm["X_umap"], adata.obs["cell_type"])
# {'CD4 Naive': '#a6cee3', 'CD8 TEM': '#1f78b4', ...}

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

Straight from a .h5ad file, without loading the expression matrix:

from stanhue import color_h5ad

colors = color_h5ad("data.h5ad", label_key="cell_type", embedding_key="X_umap")

R

colors <- assign_celltype_colors(umap_coords, cell_types)
# Seurat / SingleCellExperiment shortcuts
colors <- color_seurat(seurat_obj, reduction = "umap", group_by = "cell_type")
colors <- color_sce(sce, dimred = "UMAP", col_name = "cell_type")

DimPlot(seurat_obj, group.by = "cell_type", cols = colors)

Works with any 2D embedding (UMAP, t-SNE, PCA, PHATE, spatial coordinates) and any categorical scatter plot, not just single-cell data.

Overlap-aware coloring

Hierarchical palettes have a blind spot: two categories that sit on top of each other end up with the two most similar colors available. Since 1.1, stanhue measures how much each pair of categories mixes in 2D and pushes overlapping pairs toward perceptually distant colors (CIELAB ΔE), while everything else keeps the hierarchical scheme.

• Few categories (≤ palette size): colors are handed out in farthest-point order in CIELAB space, so 2 categories get two strongly contrasting hues instead of light/dark of the same hue.
• Many categories: overlapping members swap slots within their hue family, or borrow from a neighboring one. Non-overlapping categories keep exactly the colors they had before, so results stay stable.
• Rare populations embedded inside a large one are detected too.
• overlap_aware=False reproduces the 1.0 behavior bit for bit.

How it works

flowchart LR
    A["2D coords<br/>+ labels"] --> B["Centroid<br/>per category"]
    B --> C["Ward clustering<br/>→ auto-cut into k groups"]
    C --> D["Order within group:<br/>dominant first,<br/>then dendrogram leaf order"]
    D --> E["Groups get palette offsets<br/>(step 2 → distinct anchors)"]
    E --> F["Overlap-aware refinement:<br/>grid label-mixing → ΔE-max slots"]
    F --> G["{ label: '#hex' }"]
    style A fill:#f0f4f8,stroke:#999
    style G fill:#d4edda,stroke:#28a745

1. Group. Category centroids are clustered with Ward linkage. The number of groups is found automatically from the first significant jump in merge distance, or set with n_major_groups.
2. Order. Inside each group the largest category comes first; the rest follow the dendrogram so neighbors stay adjacent.
3. Anchor. Groups are sorted by size and start at palette positions 0, 2, 4, … so every group's dominant color is distinct. Members walk the palette from there.
4. Separate. A grid-based estimate of neighbor-label mixing gives an overlap score per pair. Overlapping categories pick, among their available slots, the color that maximizes overlap-weighted CIELAB ΔE.

The whole pipeline is deterministic: same input, same colors.

API

assign_celltype_colors(coords, labels, n_major_groups=None, palette=None,
                       return_groups=False, overlap_aware=True, overlap_threshold=0.1)

Also available: get_groups(coords, labels) to inspect the grouping, color_h5ad(path, ...) for backed h5ad files, and plot_umap / plot_palette helpers (matplotlib). The R script mirrors the same functions plus color_seurat and color_sce.

Custom palette. The default is ColorBrewer Paired (6 light/dark pairs). Any ordered list works; the offset logic adapts to its length:

warm = ["#fee5d9", "#fcbba1", "#fc9272", "#fb6a4a", "#de2d26", "#a50f15"]
colors = assign_celltype_colors(coords, labels, palette=warm)

FAQ

License

MIT © Sijie Chen