Migrating from Scanpy

Cellestial replaces scanpy.pl with Lets-Plot-based plotting functions that return composable plot objects.

Key Differences

A handful of mental shifts cover most of the migration:

• Functions return plot objects. cl.umap(...) returns a Lets-Plot PlotSpec. Add titles, themes, scales and extra layers with +. The function returns the plot; display or save it explicitly as needed.

• One color slot is named key , not color. The key can be either a metadata column (cluster, cell type) or a gene name; Cellestial picks the right scale automatically.

• Multiple panels use the plural form. Where sc.pl.umap accepts a list of colors and tiles the result, Cellestial exposes a separate cl.umaps (and cl.tsnes, cl.pcas, cl.violins, …).

• Snake case parameters. groupby becomes group_by, var_names becomes keys.

• Saving is a separate call. Use cl.save(plot, "umap.png") instead of passing save= to the plotting function.

• Interactivity is on by default. Tooltips, zoom and pan ship with every plot through the Lets-Plot toolbar.

Function Reference

Scanpy	Cellestial	Notes
sc.pl.umap	cl.umap / cl.umaps	color= → key=. Use the plural for multi-key panels.
sc.pl.tsne	cl.tsne / cl.tsnes
sc.pl.pca	cl.pca / cl.pcas
sc.pl.embedding	cl.dimensional / cl.dimensionals	Pass the embedding name through use_key=.
sc.pl.scatter	cl.scatter	Takes a Lets-Plot aes(x=..., y=..., color=...) mapping.
sc.pl.dotplot	cl.dotplot	var_names= → keys=, groupby= → group_by=.
sc.pl.heatmap	cl.heatmap	Built-in dendrogram via dendrogram=True.
sc.pl.matrixplot	cl.matrixplot
sc.pl.stacked_violin	cl.stacked_violin
sc.pl.violin	cl.violin / cl.violins	keys= → key=. Pair with cl.bracket for significance.
sc.pl.spatial	cl.spatial / cl.spatials
sc.pl.highest_expr_genes	cl.highest_expressed_genes
sc.pl.rank_genes_groups	cl.volcano / cl.volcanos	Use cl.volcano / cl.volcanos for differential expression results.

Worked Examples

UMAP by cluster

Scanpy

sc.pl.umap(
    adata,
    color="leiden",
    legend_loc="on data",
)

Cellestial

cl.umap(
    data,
    key="leiden",
    legend_ondata=True,
) + scale_color_hue()

UMAP by gene, multi-panel

Scanpy

sc.pl.umap(
    adata,
    color=["MS4A1", "CD3D", "NKG7"],
)

Cellestial

cl.umaps(
    data,
    keys=["MS4A1", "CD3D", "NKG7"],
)

Dotplot of marker genes

Scanpy

sc.pl.dotplot(
    adata,
    var_names=markers,
    groupby="cell_type_lvl1",
    dendrogram=True,
)

Cellestial

cl.dotplot(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
    dendrogram=True,
)

Violin per group

Scanpy

sc.pl.violin(
    adata,
    keys="CD3D",
    groupby="cell_type_lvl1",
)

Cellestial

cl.violin(
    data,
    key="CD3D",
    fill="cell_type_lvl1",
) + scale_fill_hue()

Cellestial adds significance brackets through a separate layer, which has no direct equivalent in scanpy:

(
   cl.violin(data, key="CD3D", fill="cell_type_lvl1", threshold=0.1)
   + scale_fill_hue()
   + cl.bracket(
      y_padding=0.2,
      label="pvalue",
      prefix="p",
      prefix_style="<",
      comparisons=[
         ("Lymphocytes", "Monocytes"),
         ("Monocytes", "B Cells"),
      ],
   )
)

Spatial overlay

Scanpy

sc.pl.spatial(
    spatial_adata,
    color="clusters",
)

Cellestial

cl.spatial(
    spatial_data,
    key="clusters",
)

Saving plots

Scanpy

sc.pl.umap(
    adata,
    color="leiden",
    save="_leiden.png",
)

Cellestial

plot = cl.umap(data, key="leiden")
cl.save(plot, "umap_leiden.png")

Missing Scanpy Plot Mappings

A few scanpy plotting helpers do not have a one-to-one replacement yet:

• sc.pl.tracksplot

• sc.pl.embedding_density

• sc.pl.paga and other trajectory-specific helpers

Where To Next

• Quickstart for a guided tour of the API.

• API Reference for the full function reference.

• Features for a deeper look at each plot family.