For the best experience,
browse Cellestial website on a computer.

Cellestial v0.60.0#

PyPI version License: Apache 2.0 Powered by Polars Built with ggrust

The grammar of graphics for single-cell omics.

Installation#

pip install cellestial

uv add cellestial

poetry add cellestial

Examples#

Hover over the plot ‘geoms’ to see tooltips, or use toolbar above the plot for zooming and panning options.

Spatial#

Overlay categorical labels or gene expression on tissue coordinates.

clusters 0 2 3 4 5 7 6 1 8 9 leiden 2 11 7 10 8 4 12 0 6 9 5 14 1 3 13
Spatial categorical example
Show code
import cellestial as cl
import squidpy as sq
from ggrust import *

data_spatial = cl.datasets.human_lymph_node()
data_hne = sq.datasets.visium_hne_adata()

s1 = cl.spatial(data_spatial, key="clusters")
s2 = cl.spatial(data_hne, key="leiden")
spatial_categorical = gggrid([s1, s2], ncol=2) + ggsize(1000, 400) + ggtb(size_zoomin=-1)
MS4A1 0 1 2 3 4 Mef2c 0 1 2 3
Spatial expression example
Show code
import cellestial as cl
import squidpy as sq
from ggrust import *

data_spatial = cl.datasets.human_lymph_node()
data_hne = sq.datasets.visium_hne_adata()

s3 = cl.spatial(data_spatial, key="MS4A1") + scale_color_viridis(option="inferno")
s4 = cl.spatial(data_hne, key="Mef2c") + scale_color_viridis(option="inferno")
spatial_numeric = gggrid([s3, s4], ncol=2) + ggsize(1000, 400) + ggtb(size_zoomin=-1)

Dimensionality Reduction#

Cellestial offers dimensionality reduction plots such as UMAP and t-SNE, which accept a key for categorical and numeric columns.

Also, cellestial-specific layers, providing utilities, could be added to dimensionality reduction plots.

Lymphocytes Lymphocytes B Cells B Cells Monocytes Monocytes Erythroid Erythroid UMAP1 UMAP2 tSNE1 tSNE2 NEAT1 0 1 2 3 4 5
Dimensionality reduction example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

dims = gggrid(
    [
        cl.umap(data, key="cell_type_lvl1", axis_type="arrow", size=1.5, legend_ondata=True)
        + scale_color_hue(),
        cl.tsne(
            data,
            key="NEAT1",
            tooltips=["NEAT1", "cell_type_lvl1"],
            axis_type="arrow",
            size=2,
            color_high="#219B9D",
            color_low="#f6f6f6",
        ),
    ]
) + ggtb(size_zoomin=-1)
B Cells B Cells Lymphocytes Lymphocytes Monocytes Monocytes Erythroid Erythroid UMAP1 UMAP2 Endocrine Endocrine Ngn3 high EP Ngn3 high EP Pre-endocrine Pre-endocrine Ductal Ductal Ngn3 low EP Ngn3 low EP UMAP1 UMAP2
Dimensionality reduction layers example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()
data_velocity = cl.datasets.pancreas()

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(
         data_velocity,
         key="clusters_coarse",
         axis_type="arrow",
         size=4,
         alpha=0.4,
   )
   + cl.stream()
   + cl.ondata_legend(halo_width=1)
)
layers = gggrid([outlined, streamed]) + ggtb(size_zoomin=-1)

Heatmaps#

Cellestial offers heatmap variants, with built-in dendrogram features.

PSAP LYZ CST3 CD79A CD79B IL7R CD3D CD3E CD4 CD8A CD8B NKG7 GNLY KLRD1 HLA-DRA FCER1A B Cells Monocytes Erythroid Lymphocytes value 0 1 2 3 4
Heatmap example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

markers = [
    "PSAP",
    "LYZ",
    "CST3",
    "CD79A",
    "CD79B",
    "IL7R",
    "CD3D",
    "CD3E",
    "CD4",
    "CD8A",
    "CD8B",
    "NKG7",
    "GNLY",
    "KLRD1",
    "HLA-DRA",
    "FCER1A",
]
htmp = (
    cl.heatmap(
        data,
        group_by="cell_type_lvl1",
        keys=markers,
        geom="raster",
        group_lines_size=0.5,
        group_lines_color="white",
        dendrogram=True,
        dendrogram_size=1,
        group_bars_labels=True,
        group_bars=True,
    )
    + scale_fill_viridis()
)
PSAP LYZ CST3 CD79A CD79B IL7R CD3D CD3E CD4 CD8A CD8B NKG7 GNLY KLRD1 HLA-DRA FCER1A 26 25 9 17 18 19 14 22 11 24 2 21 7 16 20 3 4 15 5 12 23 10 0 1 13 6 8 value 0 1 2 3
Matrixplot example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

markers = [
    "PSAP",
    "LYZ",
    "CST3",
    "CD79A",
    "CD79B",
    "IL7R",
    "CD3D",
    "CD3E",
    "CD4",
    "CD8A",
    "CD8B",
    "NKG7",
    "GNLY",
    "KLRD1",
    "HLA-DRA",
    "FCER1A",
]
mtrx = cl.matrixplot(
    data,
    group_by="leiden",
    keys=markers,
    group_lines_size=0.5,
    group_lines_color="white",
    dendrogram=True,
    dendrogram_size=1,
) + scale_fill_viridis(option="inferno", begin=0.1)
PSAP LYZ CST3 CD79A CD79B IL7R CD3D CD3E CD4 CD8A CD8B NKG7 GNLY KLRD1 HLA-DRA FCER1A 5 16 9 12 7 11 0 4 6 1 15 13 8 2 10 3 14 expression 0 1 2 3
Stacked violin example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

markers = [
    "PSAP",
    "LYZ",
    "CST3",
    "CD79A",
    "CD79B",
    "IL7R",
    "CD3D",
    "CD3E",
    "CD4",
    "CD8A",
    "CD8B",
    "NKG7",
    "GNLY",
    "KLRD1",
    "HLA-DRA",
    "FCER1A",
]
stck = cl.stacked_violin(
    data,
    group_by="leiden_res_0.50",
    keys=markers,
    dendrogram=True,
    dendrogram_size=1,
)
PSAP LYZ CST3 CD79A CD79B IL7R CD3D CD3E CD4 CD8A CD8B NKG7 GNLY KLRD1 HLA-DRA FCER1A 5 16 9 12 7 11 0 4 6 1 15 13 8 2 10 3 14 avg_exp 0 1 2 3 pct_exp 25 50 75 100
Dotplot example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

markers = [
    "PSAP",
    "LYZ",
    "CST3",
    "CD79A",
    "CD79B",
    "IL7R",
    "CD3D",
    "CD3E",
    "CD4",
    "CD8A",
    "CD8B",
    "NKG7",
    "GNLY",
    "KLRD1",
    "HLA-DRA",
    "FCER1A",
]
dtplt = cl.dotplot(
    data,
    group_by="leiden_res_0.50",
    keys=markers,
    dendrogram=True,
    dendrogram_size=1,
)

Distribution#

Cellestial comes with distribution (boxplot and violin) plots with built-in statistical analysis.

Lymphocytes Monocytes Erythroid B Cells 0 0.5 1 1.5 2 2.5 3 3.5 CD3D cell_type_lvl1 Lymphocytes Monocytes Erythroid B Cells
Boxplot example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

bx = (
    cl.boxplot(
        data,
        key="CD3D",
        fill="cell_type_lvl1",
        threshold=0.1,
    )
    + scale_fill_hue()
)
<2e-16 8.7e-09 3.9e-12 Lymphocytes Monocytes Erythroid B Cells 0 1 2 3 4 5 CD3D cell_type_lvl1 Lymphocytes Monocytes Erythroid B Cells
Boxplot with brackets example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

bx = (
    cl.boxplot(
        data,
        key="CD3D",
        fill="cell_type_lvl1",
        threshold=0.1,
    )
    + scale_fill_hue()
)
bx_brckt = bx + cl.bracket(
    y_padding=0.2,
    label="pvalue",
    comparisons=[
        ("Lymphocytes", "Monocytes"),
        ("Monocytes", "Erythroid"),
        ("Monocytes", "B Cells"),
    ],
)
Lymphocytes Monocytes Erythroid B Cells 0 0.5 1 1.5 2 2.5 3 3.5 CD3D cell_type_lvl1 Lymphocytes Monocytes Erythroid B Cells
Violin example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

vln = (
    cl.violin(
        data,
        key="CD3D",
        fill="cell_type_lvl1",
        threshold=0.1,
    )
    + scale_fill_viridis()
)
<2e-16 8.7e-09 3.9e-12 Lymphocytes Monocytes Erythroid B Cells 0 1 2 3 4 5 CD3D cell_type_lvl1 Lymphocytes Monocytes Erythroid B Cells
Violin with brackets example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

vln = (
    cl.violin(
        data,
        key="CD3D",
        fill="cell_type_lvl1",
        threshold=0.1,
    )
    + scale_fill_viridis()
)
vln_brckt = vln + cl.bracket(
    y_padding=0.2,
    label="pvalue",
    comparisons=[
        ("Lymphocytes", "Monocytes"),
        ("Monocytes", "Erythroid"),
        ("Monocytes", "B Cells"),
    ],
)

Exploratory#

Cellestial ships with quick exploratory plots.

0 1 2 3 4 5 Lymphocytes Monocytes Erythroid B Cells B2M cell_type_lvl1 cell_type_lvl1 Lymphocytes Monocytes Erythroid B Cells
Ridge example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

rdg = (
    cl.ridge(
        data,
        key="B2M",
        alpha=0.6,
        group_by="cell_type_lvl1",
    )
    + scale_fill_hue()
)
0 1 2 3 4 5 6 7 8 RPS27 TPT1 B2M RPL41 HBD RPS12 MT-ND2 MTRNR2L12 MT-ND1 MT-ND4 MT-CYB MT-ND3 MT-CO2 MT-CO3 MT-ATP6 HBA1 MT-CO1 MALAT1 HBA2 HBB Percentage of Total Counts
Highest expressed genes example
Show code
import cellestial as cl
from ggrust import *

data = cl.datasets.pbmc3k()

hexp = cl.highest_expressed_genes(data, n=20) + scale_fill_viridis()

Documentation#

About ggrust#

Cellestial is built on ggrust, a grammar of graphics engine written in Rust with a lets-plot compatible Python API. It renders interactive HTML with tooltips and zooming and panning, and static SVG and PNG. Layers, scales and themes come from from ggrust import * and compose with +.