cellestial.cluster_outlines#

cluster_outlines(plot: PlotSpec, /, groups: str | Sequence[str | Sequence[str]], *, padding: float = 1.5, level: float = 0.04, grid_size: int = 200, color: str = '#1f1f1f', linetype: Literal['blank', 'solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash'] = 'dashed', mapping: FeatureSpec | None = None, size: float = 1, group_by: str | None = None, x: str | None = None, y: str | None = None, **geom_kwargs) → LayerSpec#

Returns a Layer of geom_path that outlines the given clusters.

Parameters:

  • plot (PlotSpec) – The plot to which the layer will be added. Used to extract data and aesthetics.

  • groups (str | Sequence[str | Sequence[str]]) – The group(s) to outline. Can be a single group name or a list of group Providing string(s) will outline clusters with those group names. Providing nested sequences of strings combines each sequence into a their own group. E.g groups=[[‘A’, ‘B’]] will outline groups A and B as if they were one cluster.

  • padding (float, default 1.5) – The spatial buffer added to the cluster’s bounding box before calculating density. Increasing this value allows the density ‘cloud’ to expand further from the outermost points, ensuring the resulting curve is smooth and not truncated at the data edges.

  • level (float, default 0.04) – The density threshold for the outline, expressed as a fraction of the peak density (0.0 to 1.0). A lower value creates a larger, more inclusive ‘bubble’ that captures outliers, while a higher value creates a tighter boundary around the cluster’s core.

  • grid_size (int, default 200) – The resolution of the internal sampling grid used for the Marching Squares algorithm. A higher value produces a smoother, more ‘curvy’ path by increasing the number of interpolation points, while a lower value improves calculation speed but may result in a more jagged or ‘pixelated’ appearance.

  • color (str, default '#1f1f1f') – The color of the outline.

  • linetype (str, default 'dashed') – The linetype of the outline. E.g ‘dashed’, ‘dotted’,

  • mapping (FeatureSpec | None, default None) – Additional aesthetic mappings for the plot, the result of aes().

  • size (float, default 1) – The size of the outline.

  • 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 aesthetics.

  • 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.

  • **geom_kwargs – Additional parameters for the geom_path layer. For more information on geom_path parameters, see: https://lets-plot.org/python/pages/api/lets_plot.geom_path.html

Returns:

LayerSpec – Cluster Outlines.

Examples

Outline a specific group or cluster.

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=0.5, legend_ondata=True)
    + scale_color_hue()
)
umap + cl.cluster_outlines(umap, groups="B Cells")

Multiple groups can be outlined.

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=0.5, legend_ondata=True)
    + scale_color_hue()
)
umap + cl.cluster_outlines(umap, groups=["B Cells", "Erythroid"])

Grouping multiple clusters with nested lists.

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=0.5, legend_ondata=True)
    + scale_color_hue()
)
umap + cl.cluster_outlines(umap, groups=[["Lymphocytes","Monocytes"],"B Cells"])
On this page