cellestial 0.43.0__tar.gz → 0.45.0__tar.gz

cellestial-0.45.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: cellestial
+Version: 0.45.0
+Summary: 
+License-Expression: Apache-2.0
+License-File: LICENSE
+Author: Zaf4
+Author-email: zafermolbio@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: extras
+Requires-Dist: anndata (>=0.10.8,<1.0)
+Requires-Dist: lets-plot (>=4.9.0,<5.0.0)
+Requires-Dist: matplotlib (>=3.9,<4.0) ; extra == "extras"
+Requires-Dist: polars[pyarrow] (>=1.30.0,<2.0.0)
+Requires-Dist: scanpy[leiden] (>=1.10.4,<2.0.0) ; extra == "extras"
+Requires-Dist: scikit-image (>=0.23.1,<1.0)
+Requires-Dist: scvelo (>=0.3.3,<0.4.0) ; extra == "extras"
+Requires-Dist: spatialdata (>=0.7,<1.0)
+Requires-Dist: tqdm (>=4)
+Description-Content-Type: text/markdown
+
+# Cellestial
+
+[![GitHub](https://img.shields.io/badge/GitHub-100000?style=flat&logo=github&logoColor=white)](https://github.com/DataVil/Cellestial)
+[![PyPI](https://img.shields.io/pypi/v/cellestial?color=377eb8)](https://pypi.org/project/cellestial/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-ff0000)](https://opensource.org/licenses/Apache-2.0)
+[![Powered by Polars](https://img.shields.io/badge/Powered%20by-Polars-377eb8?logo=polars&logoColor=white)](https://www.pola.rs/)
+[![Graphics: Lets-Plot](https://img.shields.io/badge/Graphics-Lets--Plot-FF00CC?logo=jetbrains&logoColor=white)](https://lets-plot.org/)
+
+<img align="right" src="assets/cellestial.svg" alt="Cellestial Logo" width="300">
+
+The __Grammar of Graphics__ for single-cell omics.
+
+## Introduction
+
+__Cellestial__ is an interactive and a highly customizable _Single-Cell_ & _Spatial_ omics data visualization library. Built on top [Lets-Plot](https://lets-plot.org/), it offers a ggplot-like layered and modular approach offering __high customizability__ and __publication-ready figures__.
+
+Cellestial is highly integrated with scverse's [AnnData](https://github.com/scverse/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](https://pola.rs/) ensuring speed and scalability.
+
+
+## Installation
+
+```bash
+pip install cellestial
+```
+
+```bash
+uv add cellestial
+```
+
+```bash
+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.
+
+```python
+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()
+```
+
+<p align="center">
+  <img src="assets/first-umap.svg" alt="UMAP coloured by cell type" width="600">
+</p>
+
+## Examples
+
+### Spatial omics
+
+Overlay categorical labels or gene expression on tissue coordinates.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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)
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/spatial-categorical.svg" alt="Spatial categorical overlay" width="800">
+</p>
+
+### Dimensionality reduction with layers
+
+Cellestial ships single-cell-specific layers (`cluster_outlines`, `stream`, `arrow_axis`, `ondata_legend`) that compose with `+` like any geom.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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])
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/dimensionality-layers.svg" alt="UMAP with cluster outlines and velocity stream" width="800">
+</p>
+
+### Marker genes
+
+Heatmaps, dotplots, matrixplots and stacked violins share the same call shape and ship with built-in dendrograms and group bars.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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()
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/heatmap.svg" alt="Marker gene heatmap" width="700">
+</p>
+
+### Statistical comparisons
+
+`cl.bracket` runs pairwise tests on a `cl.boxplot` or `cl.violin` and draws annotated significance brackets.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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"),
+    ],
+)
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/boxplot-bracket.svg" alt="Boxplot with significance brackets" width="600">
+</p>
+
+### Ridge plots
+
+Quick exploratory views of expression distributions across groups.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+cl.ridge(
+    data,
+    key="B2M",
+    alpha=0.6,
+    group_by="cell_type_lvl1",
+) + scale_fill_hue()
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/ridge.svg" alt="Ridge plot of B2M expression" width="600">
+</p>
+
+## 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](sphinx/migrating_from_scanpy.rst) for a side-by-side mapping.
+
+## Documentation
+
+- [Quickstart](sphinx/quickstart.rst) — guided tour of the API.
+- [Features](sphinx/features.rst) — tooltips, layers, grids, colors, faceting.
+- [API reference](sphinx/API.rst) — every function.
+- [Migrating from Scanpy](sphinx/migrating_from_scanpy.rst).
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).
+
+

cellestial-0.45.0/README.md

@@ -0,0 +1,237 @@
+# Cellestial
+
+[![GitHub](https://img.shields.io/badge/GitHub-100000?style=flat&logo=github&logoColor=white)](https://github.com/DataVil/Cellestial)
+[![PyPI](https://img.shields.io/pypi/v/cellestial?color=377eb8)](https://pypi.org/project/cellestial/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-ff0000)](https://opensource.org/licenses/Apache-2.0)
+[![Powered by Polars](https://img.shields.io/badge/Powered%20by-Polars-377eb8?logo=polars&logoColor=white)](https://www.pola.rs/)
+[![Graphics: Lets-Plot](https://img.shields.io/badge/Graphics-Lets--Plot-FF00CC?logo=jetbrains&logoColor=white)](https://lets-plot.org/)
+
+<img align="right" src="assets/cellestial.svg" alt="Cellestial Logo" width="300">
+
+The __Grammar of Graphics__ for single-cell omics.
+
+## Introduction
+
+__Cellestial__ is an interactive and a highly customizable _Single-Cell_ & _Spatial_ omics data visualization library. Built on top [Lets-Plot](https://lets-plot.org/), it offers a ggplot-like layered and modular approach offering __high customizability__ and __publication-ready figures__.
+
+Cellestial is highly integrated with scverse's [AnnData](https://github.com/scverse/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](https://pola.rs/) ensuring speed and scalability.
+
+
+## Installation
+
+```bash
+pip install cellestial
+```
+
+```bash
+uv add cellestial
+```
+
+```bash
+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.
+
+```python
+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()
+```
+
+<p align="center">
+  <img src="assets/first-umap.svg" alt="UMAP coloured by cell type" width="600">
+</p>
+
+## Examples
+
+### Spatial omics
+
+Overlay categorical labels or gene expression on tissue coordinates.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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)
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/spatial-categorical.svg" alt="Spatial categorical overlay" width="800">
+</p>
+
+### Dimensionality reduction with layers
+
+Cellestial ships single-cell-specific layers (`cluster_outlines`, `stream`, `arrow_axis`, `ondata_legend`) that compose with `+` like any geom.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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])
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/dimensionality-layers.svg" alt="UMAP with cluster outlines and velocity stream" width="800">
+</p>
+
+### Marker genes
+
+Heatmaps, dotplots, matrixplots and stacked violins share the same call shape and ship with built-in dendrograms and group bars.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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()
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/heatmap.svg" alt="Marker gene heatmap" width="700">
+</p>
+
+### Statistical comparisons
+
+`cl.bracket` runs pairwise tests on a `cl.boxplot` or `cl.violin` and draws annotated significance brackets.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+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"),
+    ],
+)
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/boxplot-bracket.svg" alt="Boxplot with significance brackets" width="600">
+</p>
+
+### Ridge plots
+
+Quick exploratory views of expression distributions across groups.
+
+<details>
+<summary><b>Show code</b></summary>
+
+```python
+cl.ridge(
+    data,
+    key="B2M",
+    alpha=0.6,
+    group_by="cell_type_lvl1",
+) + scale_fill_hue()
+```
+
+</details>
+
+<p align="center">
+  <img src="assets/ridge.svg" alt="Ridge plot of B2M expression" width="600">
+</p>
+
+## 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](sphinx/migrating_from_scanpy.rst) for a side-by-side mapping.
+
+## Documentation
+
+- [Quickstart](sphinx/quickstart.rst) — guided tour of the API.
+- [Features](sphinx/features.rst) — tooltips, layers, grids, colors, faceting.
+- [API reference](sphinx/API.rst) — every function.
+- [Migrating from Scanpy](sphinx/migrating_from_scanpy.rst).
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).
+

{cellestial-0.43.0 → cellestial-0.45.0}/cellestial/__init__.py

@@ -11,10 +11,12 @@ from cellestial.single import (
     dimensional,
     dimensionals,
     dotplot,
+    elbow,
     expression,
     expressions,
     heatmap,
     highest_expressed_genes,
+    markers,
     matrixplot,
     pca,
     pcas,
@@ -75,11 +77,13 @@ __all__ = [
     "dimensional",
     "dimensionals",
     "dotplot",
+    "elbow",
     "expression",
     "expressions",
     "get_mapping",
     "heatmap",
     "highest_expressed_genes",
+    "markers",
     "matrixplot",
     "ondata_legend",
     "pca",

{cellestial-0.43.0 → cellestial-0.45.0}/cellestial/frames/__init__.py

@@ -4,10 +4,11 @@ from cellestial.frames.build import (
     anndata_variables_frame,
     build_frame,
 )
-from cellestial.frames.operations import _highest_expressed_genes_frame
+from cellestial.frames.operations import _highest_expressed_genes_frame, _pca_variance_frame
 
 __all__ = [
     "_highest_expressed_genes_frame",
+    "_pca_variance_frame",
     "anndata_observations_frame",
     "anndata_variable_columns",
     "anndata_variables_frame",

{cellestial-0.43.0 → cellestial-0.45.0}/cellestial/frames/operations.py

@@ -43,3 +43,41 @@ def _highest_expressed_genes_frame(
         raise UnsupportedDataTypeError(msg)
 
     return frame
+
+
+def _pca_variance_frame(
+    data: AnnData,
+    n_pcs: int | None = None,
+    component_column: str = "Principal Component",
+    variance_column: str = "Variance Ratio",
+) -> DataFrame:
+    """Get PCA variance ratio per principal component as a polars DataFrame."""
+    if isinstance(data, AnnData):
+        pca_uns = data.uns.get("pca")
+        if pca_uns is None or "variance_ratio" not in pca_uns:
+            msg = (
+                "PCA variance ratio is not available on this data. "
+                "Run PCA first (e.g., `sc.tl.pca(data)`)."
+            )
+            raise ValueError(msg)
+        variance_ratio = np.asarray(pca_uns["variance_ratio"]).ravel()
+        n_available = variance_ratio.size
+        if n_pcs is not None:
+            if n_pcs > n_available:
+                msg = (
+                    f"Requested n_pcs={n_pcs} components, "
+                    f"but only {n_available} components available."
+                )
+                raise ValueError(msg)
+            variance_ratio = variance_ratio[:n_pcs]
+        frame = pl.DataFrame(
+            {
+                component_column: np.arange(1, variance_ratio.size + 1, dtype=np.int64),
+                variance_column: variance_ratio,
+            }
+        )
+    else:
+        msg = f"Unsupported data type: `{type(data)}`"
+        raise UnsupportedDataTypeError(msg)
+
+    return frame

{cellestial-0.43.0 → cellestial-0.45.0}/cellestial/layers/ondata_legend.py

@@ -2,10 +2,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-import numpy as np
 import polars as pl
 from lets_plot import aes, geom_label, geom_label_repel, geom_text, geom_text_repel, theme
-from scipy.stats import gaussian_kde
 
 from cellestial.layers._deferred import DeferredLayer
 from cellestial.util import get_mapping, retrieve
@@ -16,63 +14,19 @@ if TYPE_CHECKING:
     from polars import DataFrame
 
 
-def _label_center(
-    points: np.ndarray,
-    *,
-    max_sample: int = 500,
-    top_fraction: float = 0.2,
-    density_factor: float = 2.0,
-) -> np.ndarray:
-    """
-    Return the cluster's dense-core centroid if it dominates the centroid, else the centroid.
-
-    For unimodal clusters the centroid is already in the dense region, so it wins. For
-    multimodal or strongly skewed clusters the dense core is much denser than the centroid
-    (which sits in a gap), and the label is placed on that core instead.
-    """
-    centroid = points.mean(axis=0)
-    n_points = len(points)
-    if n_points < 3:
-        return centroid
-    sample = points
-    if n_points > max_sample:
-        rng = np.random.default_rng(0)
-        sample = points[rng.choice(n_points, max_sample, replace=False)]
-    try:
-        kde = gaussian_kde(sample.T)
-        density = kde(sample.T)
-    except (np.linalg.LinAlgError, ValueError):
-        return centroid
-    top_k = max(3, int(len(sample) * top_fraction))
-    top_indices = np.argpartition(density, -top_k)[-top_k:]
-    core = sample[top_indices].mean(axis=0)
-    if kde(core[:, None])[0] > density_factor * kde(centroid[:, None])[0]:
-        return core
-    return centroid
-
-
 def _compute_label_positions(
     frame: DataFrame,
     *,
     x: str,
     y: str,
     group_by: str,
-    dense: bool,
 ) -> DataFrame:
-    """Aggregate per-group label coordinates for `geom_text` placement."""
+    """Aggregate per-group median coordinates for `geom_text` placement."""
     frame = frame.filter(pl.col(group_by).is_not_null())
-    if dense:
-        rows = []
-        for (group_value,), group_frame in frame.group_by(group_by):
-            points = group_frame.select(x, y).to_numpy()
-            center = _label_center(points)
-            rows.append({group_by: group_value, x: float(center[0]), y: float(center[1])})
-        return pl.DataFrame(
-            rows,
-            schema={group_by: frame.schema[group_by], x: pl.Float64, y: pl.Float64},
-        )
     return frame.group_by(group_by).agg(
-        pl.col(x).mean(), pl.col(y).mean(), pl.selectors.categorical().mode().first()
+        pl.col(x).median(),
+        pl.col(y).median(),
+        pl.selectors.categorical().mode().first(),
     )
 
 
@@ -88,12 +42,11 @@ def ondata_legend(
     family: str = "sans",
     alpha: float = 1,
     label: bool = False,
-    dense: bool = True,
     repel: bool = False,
     **geom_kwargs,
 ) -> DeferredLayer:
     """
-    Layer of `geom_text` that places per-group labels at the center of each cluster.
+    Layer of `geom_text` that places per-group labels at median coordinates.
 
     Parameters
     ----------
@@ -124,9 +77,6 @@ def ondata_legend(
         Alpha (transparency) of the legend text.
     label : bool, default=False
         If True, draw labels with a filled background using `geom_label`.
-    dense : bool, default=True
-        Whether to place the label at the cluster's density peak (KDE-based).
-        If False, the arithmetic mean of the group's 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`,
@@ -204,9 +154,7 @@ def ondata_legend(
             raise MissingAestheticError(msg)
 
         frame = retrieve(source)
-        grouped = _compute_label_positions(
-            frame, x=x, y=y, group_by=group_by, dense=dense
-        )
+        grouped = _compute_label_positions(frame, x=x, y=y, group_by=group_by)
         layer_kwargs = dict(geom_kwargs)
         if label:
             geom = geom_label_repel if repel else geom_label