Palette optimization for publication-quality single-cell & spatial plots¶

Color is not just an aesthetic choice—it directly affects how clearly readers can distinguish neighboring categories (cell types, clusters, domains) in dense visualizations. In spatially resolved transcriptomics (SRT), default categorical palettes and lexicographical (alphabetical) color assignment often place similar colors on spatially adjacent or interlaced cell types, creating perceptual ambiguity.

In this tutorial notebook we demonstrate how to improve categorical colorization using Spaco (Jing et al., Patterns 2024), a spatially aware colorization framework that:

1. Models spatial relationships between clusters using the Degree of Interlacement (DOI) metric and a cluster interlacement graph (CI-graph).
2. Selects a palette either (i) automatically from the CI-graph embedding (graph-guided) or (ii) from a reference image (image-guided).
3. Assigns colors to clusters by matching the CI-graph to a color-difference graph (CD-graph), so that strongly interlaced/neighboring clusters receive more contrasting colors.

Learning goals¶

By the end of this notebook you will be able to:

• Preview and combine OmicVerse categorical palettes for UMAP and spatial plots.
• Optimize only the cluster→color mapping while keeping a given palette fixed.
• Automatically generate a palette and mapping using Spaco (CI-graph guided).
• Extract a publication-style “theme palette” from an image and apply it to your data.
• Understand key parameters (radius, n_neighbors) and when to tune them.

Reference: Jing, Z. et al. (2024) Spaco: A comprehensive tool for coloring spatial data at single-cell resolution. Patterns 5:100915.

Setup¶

We use OmicVerse for plotting and its external.spaco wrapper to access Spaco.
The code cells below are kept minimal on purpose; the tutorial emphasis is on what each step accomplishes and why it matches the method described in the Spaco paper.

Inputs needed by Spaco

• cell_coordinates: a 2D coordinate matrix (e.g., X_umap or spatial)
• cell_labels: categorical labels for each cell/spot
• Optional: a fixed palette (to only optimize the assignment), or image_palette (to extract theme colors)

Key parameters

• n_neighbors: k in the spatial kNN graph used to compute DOI (paper default k≈30).
• radius: a distance scale used in the “dual-outlier-free” neighbor refinement; it must match the units of cell_coordinates.
  • For spatial coordinates (µm), a typical starting point is ~50 µm.
  • For UMAP coordinates (dimensionless), start with ~0.05–0.2 and adjust if results look over/under-smoothed.

Example datasets¶

We load:

• PBMC8k (single-cell RNA-seq) and visualize cell types on UMAP.
• seqFISH (spatial) and visualize cell types on tissue coordinates.

Although Spaco is designed for spatial coordinates, the same idea applies to any embedding where “neighbors” are meaningful. Here we use UMAP as a simple demonstration of neighborhood-aware color assignment, and obsm['spatial'] for the true spatial case.

1) Prepare and preview palettes¶

OmicVerse provides a set of ready-to-use categorical palettes, e.g. sc_color, red_color, green_color, orange_color, blue_color, purple_color.

In practice, you may want to:

• Start from a default qualitative palette for quick exploration.
• Manually compose a palette (e.g., mixing a few distinct hues) for small numbers of clusters.
• When you have many clusters or strong spatial mixing, keep a broad palette but optimize the cluster→color assignment with Spaco.

Below we preview:

1. The default sc_color on UMAP and spatial plots.
2. A manually composed palette (by concatenating several base palettes).

Apply the same palette to a spatial plot¶

The goal is consistency: once you decide a palette style, you typically want it to work across both embedding plots (UMAP) and tissue plots. The next cell applies sc_color to a spatial embedding and visualizes the palette as a color strip.

Manual palette composition (when you want full control)¶

For a small set of categories (e.g., <10–20), manually combining a few high-contrast colors can be enough.

In the next cell we build a custom palette by concatenating subsets of OmicVerse palettes, then apply it to the UMAP plot.

2) Optimize color assignment with a given palette¶

Sometimes you already have a palette you want to keep (lab conventions, previous figures, journal theme), but you want to reorder which cluster gets which color so that neighboring/interlaced clusters become easier to distinguish.

Spaco (Jing et al., Patterns 2024) does this by:

1. Building a cluster interlacement graph (CI-graph) from coordinates + labels using the Degree of Interlacement (DOI) metric computed on a refined spatial kNN graph (dual-outlier-free strategy).
2. Building a color difference graph (CD-graph) from the chosen palette using a perceptual color difference metric.
3. Finding a one-to-one graph matching (a permutation of colors) that best aligns CI-graph edge weights with CD-graph edge weights.

A common way to write the objective is:

[ L(P) = \lVert P A_{CI} P^T - A_{CD} \rVert_F, \quad P^* = \arg\min_P L(P), ]

where (P) is a permutation matrix (one-to-one assignment).

In code, this corresponds to calling spaco.colorize(..., palette=palette_default), which keeps colors fixed but optimizes the mapping from clusters to colors.

UMAP example: optimize only the mapping¶

We start from the palette that Scanpy/OmicVerse already stored in adata.uns['..._colors'].
Spaco returns a dictionary {label: hex_color} that you can pass directly to plotting functions.

Spatial example: optimize only the mapping¶

We repeat the same procedure on true spatial coordinates (sdata.obsm['spatial']), where neighborhood relationships correspond to physical proximity in tissue.

3) Automatic colorization (CI-graph guided)¶

If you do not provide a palette, Spaco can generate one automatically by embedding the CI-graph into color space:

• Compute DOI and CI-graph from labels + coordinates (kNN + dual-outlier-free refinement).
• Embed CI-graph vertices into a 3D space using UMAP and rescale the embedding into the perceptually uniform CIELab color space.
• To avoid overly dark/bright colors, the illuminant channel (L) is typically constrained (e.g., (L\in[20,85]) in the paper).
• Convert Lab → RGB hex and then optionally refine the final cluster-color assignment (graph matching step).

This mode is particularly useful when:

• You have many clusters (dozens to hundreds),
• Clusters are spatially intermixed, and
• You do not want to manually curate a large palette.

UMAP: generate palette + mapping automatically¶

Here spaco.colorize infers both the palette (graph-guided) and the cluster→color mapping.

Spatial: generate palette + mapping automatically¶

Same as above, but using obsm['spatial'] so the DOI reflects tissue neighborhoods.

4) Automatic colorization (Image guided)¶

For publication figures, you may want a coherent “theme” palette (e.g., from a cover image or an existing figure). Spaco supports image-guided palette extraction:

• Convert pixels to CIELab, bin colors, and filter extreme luminance / rare colors.
• Iteratively pick high-frequency colors while penalizing colors similar to already chosen ones.
• Refine the palette using farthest point sampling (FPS) to maximize separation.

After a palette is extracted, Spaco still performs the graph-based assignment so that adjacent/interlaced clusters get more contrasting colors.

Tip: image-guided palettes are a great way to keep figures stylistically consistent across a paper or slide deck.

Load a reference image¶

We load a demo image (from the Spaco vignette repository) and visualize it. In practice, you can replace this with your own figure/cover image.

Apply image-guided palette to your data¶

Pass the image via image_palette=img. Spaco will extract a theme palette and then assign colors to clusters based on spatial (or embedding) neighborhoods.

Summary / take-home checklist¶

• If you already like your colors but the plot is confusing → keep palette, optimize assignment (palette=...).
• If you have many clusters and want maximal discernibility → CI-graph guided auto palette (no palette).
• If you want a publication theme → image-guided palette (image_palette=...) + graph-based assignment.
• Always tune radius to match the scale of your coordinates (UMAP vs µm).

Method reference¶

Spaco workflow: cluster interlacement modeling (DOI → CI-graph), adaptive palette selection (graph-guided or image-guided), and cluster-color assignment (CI-graph ↔ CD-graph matching).