cellestial 0.49.1__tar.gz → 0.49.2__tar.gz

{cellestial-0.49.1 → cellestial-0.49.2}/PKG-INFO

@@ -1,17 +1,23 @@
 Metadata-Version: 2.4
 Name: cellestial
-Version: 0.49.1
-Summary: 
+Version: 0.49.2
+Summary: Interactive single-cell and spatial omics visualization library
 License-Expression: Apache-2.0
 License-File: LICENSE
+Keywords: anndata,bioinformatics,data-visualization,lets-plot,polars,single-cell,spatial-omics
 Author: Zaf4
 Author-email: zafermolbio@gmail.com
 Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 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
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
 Provides-Extra: extras
 Requires-Dist: anndata (>=0.10.8,<1.0)
 Requires-Dist: lets-plot (>=4.9.0,<5.0.0)
@@ -23,6 +29,10 @@ 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,<5)
+Project-URL: Documentation, https://cellestial.datavil.org
+Project-URL: Homepage, https://cellestial.datavil.org
+Project-URL: Issues, https://github.com/DataVil/Cellestial/issues
+Project-URL: Repository, https://github.com/DataVil/Cellestial
 Description-Content-Type: text/markdown
 
 # Cellestial
@@ -250,14 +260,14 @@ Cellestial mirrors most of `scanpy.pl` with a few naming shifts:
 - `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.
+See the [migration guide](https://cellestial.datavil.org/migrating_from_scanpy.html) 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).
+- [Quickstart](https://cellestial.datavil.org/quickstart.html) — guided tour of the API.
+- [Features](https://cellestial.datavil.org/features.html) — tooltips, layers, grids, colors, faceting.
+- [API reference](https://cellestial.datavil.org/API.html) — every function.
+- [Migrating from Scanpy](https://cellestial.datavil.org/migrating_from_scanpy.html).
 
 ## License
 

{cellestial-0.49.1 → cellestial-0.49.2}/README.md

@@ -223,14 +223,14 @@ Cellestial mirrors most of `scanpy.pl` with a few naming shifts:
 - `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.
+See the [migration guide](https://cellestial.datavil.org/migrating_from_scanpy.html) 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).
+- [Quickstart](https://cellestial.datavil.org/quickstart.html) — guided tour of the API.
+- [Features](https://cellestial.datavil.org/features.html) — tooltips, layers, grids, colors, faceting.
+- [API reference](https://cellestial.datavil.org/API.html) — every function.
+- [Migrating from Scanpy](https://cellestial.datavil.org/migrating_from_scanpy.html).
 
 ## License
 

{cellestial-0.49.1 → cellestial-0.49.2}/cellestial/__init__.py

@@ -37,7 +37,15 @@ from cellestial.single import (
     xyplots,
 )
 from cellestial.spatial import spatial, spatials
-from cellestial.util import get_figure, get_figures, get_mapping, retrieve, save
+from cellestial.util import (
+    get_figure,
+    get_figures,
+    get_mapping,
+    marker_genes,
+    marker_genes_dict,
+    retrieve,
+    save,
+)
 from cellestial.util.colors import (
     BLUE,
     CHERRY,
@@ -84,6 +92,8 @@ __all__ = [
     "get_mapping",
     "heatmap",
     "highest_expressed_genes",
+    "marker_genes",
+    "marker_genes_dict",
     "markers",
     "matrixplot",
     "ondata_legend",

{cellestial-0.49.1 → cellestial-0.49.2}/cellestial/layers/arrow.py

@@ -250,6 +250,10 @@ def arrow_axis(
     MissingAestheticError
         If `x` or `y` cannot be inferred from the receiving plot.
 
+    Notes
+    -----
+    Uses `geom_path` to draw the axis lines and `geom_segment` for the arrowheads.
+
     Examples
     --------
     Without arrow.

{cellestial-0.49.1 → cellestial-0.49.2}/cellestial/single/core/utilities.py

@@ -136,8 +136,8 @@ def _distribution(
     elif len(keys) > 1 and group_by != variable_column:
         _warn(
             f"Multiple keys provided; `group_by={group_by!r}` cannot share the "
-            f"x-axis with the variable column. Falling back to "
-            f"`group_by={variable_column!r}`. For a per-key panel, use the plural variant."
+            f"x-axis with the variable column.\nFalling back to "
+            f"`group_by={variable_column!r}`. For a per-key panel, use the plural variant ({geom}s)."
         )
         group_by = variable_column
 

{cellestial-0.49.1 → cellestial-0.49.2}/cellestial/util/__init__.py

@@ -2,6 +2,7 @@ from cellestial.util.dendrogram import (
     _get_dendrogram,
     _get_dendrogram_path_frame,
 )
+from cellestial.util.markers import marker_genes, marker_genes_dict
 from cellestial.util.operations import get_figure, get_figures, get_mapping, retrieve
 from cellestial.util.save import save
 from cellestial.util.utilities import (
@@ -43,6 +44,8 @@ __all__ = [
     "get_figure",
     "get_figures",
     "get_mapping",
+    "marker_genes",
+    "marker_genes_dict",
     "retrieve",
     "save",
 ]

cellestial-0.49.2/cellestial/util/markers.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from anndata import AnnData
+
+from cellestial.util.errors import KeyNotFoundError, UnsupportedDataTypeError
+
+
+def _marker_names_per_group(
+    data: AnnData,
+    groups: Sequence[str] | None,
+    *,
+    key: str,
+    n_genes: int,
+) -> dict[str, list[str]]:
+    """
+    Read the top-`n_genes` gene names per group from a precomputed ranking.
+
+    Shared core for `marker_genes` and `marker_genes_dict`: validates inputs
+    and returns one full top-N list per selected group, in group order, with
+    no cross-group de-duplication.
+    """
+    if groups is not None and (not isinstance(groups, Sequence) or isinstance(groups, str)):
+        msg = "`groups` must be a Sequence of strings or None"
+        raise TypeError(msg)
+
+    if n_genes < 1:
+        msg = f"`n_genes` must be >= 1, got {n_genes}."
+        raise ValueError(msg)
+
+    if isinstance(data, AnnData):
+        if key not in data.uns:
+            msg = (
+                f"`adata.uns[{key!r}]` not found. "
+                "Run `scanpy.tl.rank_genes_groups` first "
+                "(or pass the correct `key_added` value as `key`)."
+            )
+            raise KeyNotFoundError(msg)
+
+        record = data.uns[key]
+        if "names" not in record:
+            msg = (
+                f"`adata.uns[{key!r}]` does not look like a "
+                "`rank_genes_groups` result (missing 'names')."
+            )
+            raise KeyNotFoundError(msg)
+
+        names = record["names"]
+        available_groups = list(names.dtype.names)
+
+        if groups is None:
+            selected = available_groups
+        else:
+            selected = list(groups)
+            unknown = [group for group in selected if group not in available_groups]
+            if unknown:
+                msg = (
+                    f"Groups {unknown!r} not found in "
+                    f"`adata.uns[{key!r}]`. Available: {available_groups!r}."
+                )
+                raise KeyNotFoundError(msg)
+
+        n_available = len(names)
+        if n_genes > n_available:
+            msg = (
+                f"`n_genes={n_genes}` exceeds the {n_available} ranked genes "
+                f"stored in `adata.uns[{key!r}]`."
+            )
+            raise ValueError(msg)
+
+        markers = {group: [str(gene) for gene in names[group][:n_genes]] for group in selected}
+    else:
+        msg = f"Unsupported data type: `{type(data)}`"
+        raise UnsupportedDataTypeError(msg)
+
+    return markers
+
+
+def marker_genes(
+    data: AnnData,
+    groups: Sequence[str] | None = None,
+    *,
+    key: str = "rank_genes_groups",
+    n_genes: int = 5,
+) -> list[str]:
+    """
+    Select the top-ranked marker gene names from a precomputed ranking.
+
+    The returned list is meant to be passed straight into the `keys` argument
+    of the dimensional and distribution plots (e.g. `umaps`, `violins`), so
+    each marker becomes one panel.
+
+    Parameters
+    ----------
+    data : AnnData
+        The single-cell data object holding the precomputed differential
+        expression ranking.
+    groups : Sequence[str] | None, default=None
+        Subset of groups to pull markers from, in order. `None` keeps all
+        groups in their stored order.
+    key : str, default='rank_genes_groups'
+        The key under which the precomputed ranking is stored on `data`.
+    n_genes : int, default=5
+        Number of top genes to pull per group.
+
+    Returns
+    -------
+    list[str]
+        Flattened, order-preserving list of marker gene names with duplicates
+        removed (a gene ranked highly in several groups is kept once, at its
+        first occurrence).
+
+    Raises
+    ------
+    UnsupportedDataTypeError
+        If `data` is not a supported single-cell data object.
+    KeyNotFoundError
+        If the ranking result or a requested group is missing.
+    ValueError
+        If `n_genes` is out of range.
+    TypeError
+        If `groups` is neither a Sequence of strings nor None.
+
+    Notes
+    -----
+    Reads only the gene names, not their scores; use `markers` to plot the
+    ranking itself. Use `marker_genes_dict` to keep the per-group grouping.
+
+    Examples
+    --------
+    Color a UMAP grid by the top markers of a single group.
+
+    .. jupyter-execute::
+
+        import scanpy as sc
+
+        import cellestial as cl
+
+        data = sc.datasets.pbmc68k_reduced()
+
+        cl.umaps(data, keys=cl.marker_genes(data, groups=["CD14+ Monocyte"]))
+
+    Violin the top markers across every group.
+
+    .. jupyter-execute::
+
+        cl.violins(data, keys=cl.marker_genes(data, n_genes=3))
+    """
+    per_group = _marker_names_per_group(data, groups, key=key, n_genes=n_genes)
+
+    # Flatten group by group, dropping any gene already seen so the list can
+    # feed `keys` without producing duplicate panels.
+    seen: set[str] = set()
+    marker_names: list[str] = []
+    for group_names in per_group.values():
+        for gene_name in group_names:
+            if gene_name in seen:
+                continue
+            seen.add(gene_name)
+            marker_names.append(gene_name)
+
+    return marker_names
+
+
+def marker_genes_dict(
+    data: AnnData,
+    groups: Sequence[str] | None = None,
+    *,
+    key: str = "rank_genes_groups",
+    n_genes: int = 5,
+) -> dict[str, list[str]]:
+    """
+    Select the top-ranked marker gene names per group from a precomputed ranking.
+
+    Like `marker_genes`, but keeps the grouping: each group maps to its own
+    full top-`n_genes` list.
+
+    Parameters
+    ----------
+    data : AnnData
+        The single-cell data object holding the precomputed differential
+        expression ranking.
+    groups : Sequence[str] | None, default=None
+        Subset of groups to pull markers from, in order. `None` keeps all
+        groups in their stored order.
+    key : str, default='rank_genes_groups'
+        The key under which the precomputed ranking is stored on `data`.
+    n_genes : int, default=5
+        Number of top genes to pull per group.
+
+    Returns
+    -------
+    dict[str, list[str]]
+        Mapping from group label to its top-`n_genes` gene names, in group
+        order. Each list is complete; a gene that ranks highly in several
+        groups appears under each of them.
+
+    Raises
+    ------
+    UnsupportedDataTypeError
+        If `data` is not a supported single-cell data object.
+    KeyNotFoundError
+        If the ranking result or a requested group is missing.
+    ValueError
+        If `n_genes` is out of range.
+    TypeError
+        If `groups` is neither a Sequence of strings nor None.
+
+    Notes
+    -----
+    Reads only the gene names, not their scores; use `markers` to plot the
+    ranking itself. Use `marker_genes` for a flat, de-duplicated list.
+
+    Examples
+    --------
+    Inspect the top markers of each group.
+
+    .. jupyter-execute::
+
+        import scanpy as sc
+
+        import cellestial as cl
+
+        data = sc.datasets.pbmc68k_reduced()
+
+        cl.marker_genes_dict(data, n_genes=3)
+    """
+    return _marker_names_per_group(data, groups, key=key, n_genes=n_genes)

{cellestial-0.49.1 → cellestial-0.49.2}/pyproject.toml

@@ -1,13 +1,34 @@
 [project]
 name = "cellestial"
-version = "0.49.1"
-description = ""
+version = "0.49.2"
+description = "Interactive single-cell and spatial omics visualization library"
 authors = [
     { name = "Zaf4", email = "zafermolbio@gmail.com" },
 ]
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.11,<4.0"
+keywords = [
+    "anndata",
+    "bioinformatics",
+    "data-visualization",
+    "lets-plot",
+    "polars",
+    "single-cell",
+    "spatial-omics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
 dependencies = [
     "anndata>=0.10.8,<1.0",
     "lets-plot>=4.9.0,<5.0.0",
@@ -17,6 +38,12 @@ dependencies = [
     "tqdm>=4,<5",
 ]
 
+[project.urls]
+Documentation = "https://cellestial.datavil.org"
+Homepage = "https://cellestial.datavil.org"
+Repository = "https://github.com/DataVil/Cellestial"
+Issues = "https://github.com/DataVil/Cellestial/issues"
+
 [project.optional-dependencies]
 extras = [
     "matplotlib>=3.9,<4.0",