Cellestial

The Grammar of Graphics for single-cell omics.

Cellestial is an interactive and a highly customizable Single-Cell & Spatial omics data visualization library. Built on top Lets-Plot, it offers a ggplot-like layered and modular approach offering high customizability and publication-ready figures.

Cellestial is highly integrated with scverse's AnnData with room for integration with any upcoming single-cell omics data type in the Python single-cell omics ecosystem.

Cellestial leverages the performance of Polars ensuring speed and scalability.

Installation

pip install cellestial

uv add cellestial

poetry add cellestial

Quickstart

Cellestial accepts a standard AnnData directly. The same function plots a categorical column or a gene, and everything composes through + like ggplot.

from lets_plot import *
import cellestial as cl

data = cl.datasets.pbmc3k(cache_directory="data")

cl.umap(
    data,
    key="cell_type_lvl1",
    axis_type="arrow",
    legend_ondata=True,
) + scale_color_hue()

UMAP coloured by cell type

Examples

Spatial omics

Overlay categorical labels or gene expression on tissue coordinates.

Show code

import squidpy as sq

lymph_node = cl.datasets.human_lymph_node(cache_directory="data")
hne = sq.datasets.visium_hne_adata()

gggrid(
    [
        cl.spatial(lymph_node, key="clusters"),
        cl.spatial(hne, key="leiden"),
    ],
    ncol=2,
) + ggsize(1000, 400)

Spatial categorical overlay

Dimensionality reduction with layers

Cellestial ships single-cell-specific layers (cluster_outlines, stream, arrow_axis, ondata_legend) that compose with + like any geom.

Show code

velocity_data = cl.datasets.pancreas(cache_directory="data")

outlined = cl.umap(
    data,
    key="cell_type_lvl1",
    axis_type="arrow",
    size=1.5,
    legend_ondata=True,
) + scale_color_hue() + cl.cluster_outlines(groups=["Lymphocytes", "B Cells"])

streamed = cl.umap(
    velocity_data,
    key="clusters_coarse",
    axis_type="arrow",
    size=4,
    alpha=0.4,
    legend_ondata=True,
    ondata_color="black",
) + cl.stream()

gggrid([outlined, streamed])

UMAP with cluster outlines and velocity stream

Marker genes

Heatmaps, dotplots, matrixplots and stacked violins share the same call shape and ship with built-in dendrograms and group bars.

Show code

markers = [
    "PSAP", "LYZ", "CST3",          # Monocytes
    "CD79A", "CD79B",                # B cells
    "IL7R", "CD3D", "CD3E", "CD4",   # T cells (CD4+)
    "CD8A", "CD8B",                  # T cells (CD8+)
    "NKG7", "GNLY", "KLRD1",         # NK cells
    "HLA-DRA", "FCER1A",             # Dendritic cells
]

cl.heatmap(
    data,
    group_by="cell_type_lvl1",
    keys=markers,
    geom="raster",
    group_lines_size=0.5,
    group_lines_color="white",
    group_bars=True,
    group_bars_labels=True,
    dendrogram=True,
    dendrogram_size=1,
) + scale_fill_viridis()

Marker gene heatmap

Statistical comparisons

cl.bracket runs pairwise tests on a cl.boxplot or cl.violin and draws annotated significance brackets.

Show code

cl.boxplot(
    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", "Erythroid"),
        ("Monocytes", "B Cells"),
    ],
)

Boxplot with significance brackets

Ridge plots

Quick exploratory views of expression distributions across groups.

Show code

cl.ridge(
    data,
    key="B2M",
    alpha=0.6,
    group_by="cell_type_lvl1",
) + scale_fill_hue()

Ridge plot of B2M expression

Migrating from Scanpy

Cellestial mirrors most of scanpy.pl with a few naming shifts:

color= becomes key=.
Multi-panel calls use a plural function (cl.umaps, cl.violins, ...).
groupby becomes group_by, var_names becomes keys.
Saving is a separate cl.save(plot, "umap.png") call.

See the migration guide for a side-by-side mapping.

Documentation

Quickstart — guided tour of the API.
Features — tooltips, layers, grids, colors, faceting.
API reference — every function.
Migrating from Scanpy.

License

Apache 2.0. See LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cellestial-0.58.1.tar.gz (112.9 kB view details)

Uploaded Jul 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cellestial-0.58.1-py3-none-any.whl (161.3 kB view details)

Uploaded Jul 23, 2026 Python 3

File details

Details for the file cellestial-0.58.1.tar.gz.

File metadata

Download URL: cellestial-0.58.1.tar.gz
Upload date: Jul 23, 2026
Size: 112.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: poetry/2.4.1 CPython/3.14.6 Darwin/25.5.0

File hashes

Hashes for cellestial-0.58.1.tar.gz
Algorithm	Hash digest
SHA256	`5d321650aa57a1c0cfcb44ee17460e76d52057594be62c07ec304b31b818299a`
MD5	`d643b45a057a3a32c5eba8d07aff943c`
BLAKE2b-256	`6e66d0b4dc1146de6e23f8fe94613349d90ba76e12ef9485a40794dd357b7528`

See more details on using hashes here.

File details

Details for the file cellestial-0.58.1-py3-none-any.whl.

File metadata

Download URL: cellestial-0.58.1-py3-none-any.whl
Upload date: Jul 23, 2026
Size: 161.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: poetry/2.4.1 CPython/3.14.6 Darwin/25.5.0

File hashes

Hashes for cellestial-0.58.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`f7942561c0ac49cc0f54e65a1e33e85ba0e8365426c04dc9f21da4c4f6a1755b`
MD5	`6528f41fe6cdf580b2cf98ff55658fd3`
BLAKE2b-256	`8909cb6ea35a8c72566c14e2c6d9ab927c6b67750b4e902cab41efa9374a02a7`