ondata_legend#

ondata_legend(*, plot: PlotSpec | None = None, x: str | None = None, y: str | None = None, group_by: str | None = None, size: float = 12, color: str = '#3f3f3f', fontface: str = 'bold', family: str = 'sans', alpha: float = 1, weighted: bool = True, repel: bool = False, **geom_kwargs) → DeferredLayer#

Layer of geom_text that places per-group labels at the center of each cluster.

Parameters:

  • plot (PlotSpec | None, default None) – If provided, labels are computed from this plot’s data and aesthetics regardless of which plot the resulting layer is added to. When None, the layer is deferred and introspects the plot it is added to via +.

  • x (str | None, default None) – The column name in the data used for x-axis coordinates. e.g ‘X_UMAP1’. If None, it will be inferred from the plot aesthetics.

  • y (str | None, default None) – The column name in the data used for y-axis coordinates. e.g ‘X_UMAP2’. If None, it will be inferred from the plot aesthetics.

  • group_by (str | None, default None) – The column name in the data used to group clusters by. e.g ‘cell_type’. If None, it will be inferred from the plot’s color aesthetic.

  • size (float, default 12) – Size of the legend text.

  • color (str, default '#3f3f3f') – Color of the legend text.

  • fontface (str, default 'bold') – Fontface of the legend text. https://lets-plot.org/python/pages/aesthetics.html#font-face

  • family (str, default 'sans') – Font family of the legend text. https://lets-plot.org/python/pages/aesthetics.html#font-family

  • alpha (float, default 1) – Alpha (transparency) of the legend text.

  • weighted (bool, default True) – Whether to use a weighted mean of group coordinates for label placement. If True, each point’s contribution is weighted by its inverse distance to the group mean, pulling the label toward the cluster’s dense core. If False, the arithmetic mean of group coordinates is used.

  • repel (bool, default False) – If True, use geom_text_repel so labels are shifted to avoid overlapping each other. Repel-specific options (e.g. box_padding, point_padding, max_iter, seed) can be passed via geom_kwargs.

  • **geom_kwargs – Additional parameters for the underlying geom layer. For geom_text parameters, see: https://lets-plot.org/python/pages/api/lets_plot.geom_text.html For geom_text_repel parameters (when repel=True), see: https://lets-plot.org/python/pages/api/lets_plot.geom_text_repel.html

Returns:

DeferredLayer – On-data legend layer.

Examples

A UMAP plot without on-data legends.

import cellestial as cl
import scanpy as sc

from lets_plot import *

data = sc.read_h5ad("data/pbmc3k_pped.h5ad")

umap = cl.umap(data, key="cell_type_lvl1", axis_type="arrow", size=1.5)
umap

Add the on-data legend.

umap + cl.ondata_legend()

Modify as needed.

umap + cl.ondata_legend(size=10, family="mono", fontface="italic")
On this page