cellestial 0.45.0__tar.gz → 0.46.0__tar.gz

{cellestial-0.45.0 → cellestial-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellestial
-Version: 0.45.0
+Version: 0.46.0
 Summary: 
 License-Expression: Apache-2.0
 License-File: LICENSE

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/single/core/dimensional.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import warnings
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Literal
 
@@ -27,6 +26,7 @@ from cellestial.util import (
     _is_variable_key,
     _resolve_tooltips,
     _validate_tooltips,
+    _warn,
 )
 from cellestial.util.errors import UnsupportedDataTypeError
 
@@ -335,6 +335,6 @@ def dimensional(
             )
         elif frame[key].dtype != pl.Categorical:
             msg = f"key `{key}` is not categorical, legend on data will not be added"
-            warnings.warn(msg, stacklevel=1)
+            _warn(msg)
 
     return scttr

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/single/core/distribution.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any, Literal
-from warnings import warn
 
 import polars as pl
 from anndata import AnnData
@@ -27,6 +26,7 @@ from cellestial.util import (
     _resolve_tooltips,
     _select_variable_keys,
     _validate_tooltips,
+    _warn,
 )
 from cellestial.util.errors import UnsupportedDataTypeError
 
@@ -131,11 +131,10 @@ def _distribution(
     if group_by is None:
         group_by = variable_column
     elif len(keys) > 1 and group_by != variable_column:
-        warn(
+        _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.",
-            stacklevel=3,
+            f"`group_by={variable_column!r}`. For a per-key panel, use the plural variant."
         )
         group_by = variable_column
 

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/single/heatmap/_rank_genes_groups.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
-from warnings import warn
 
 from anndata import AnnData
 
+from cellestial.util import _warn
 from cellestial.util.errors import KeyNotFoundError, UnsupportedDataTypeError
 
 if TYPE_CHECKING:
@@ -124,13 +124,12 @@ def _extract_rank_genes_groups(
                 for gene, first, later in dropped[:3]
             )
             suffix = f" and {len(dropped) - 3} more" if len(dropped) > 3 else ""
-            warn(
+            _warn(
                 "Some genes ranked highly in multiple groups; "
                 "keeping the first occurrence and dropping the rest "
                 f"({examples}{suffix}). "
                 "Increase `n_genes`, restrict `groups`, "
-                "or pass an explicit `keys` mapping to control this.",
-                stacklevel=2,
+                "or pass an explicit `keys` mapping to control this."
             )
 
         params = record["params"]

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/single/heatmap/dotplot.py

@@ -35,6 +35,7 @@ from cellestial.util import (
     _get_dendrogram_path_frame,
     _resolve_tooltips,
     _validate_tooltips,
+    _warn,
 )
 from cellestial.util.errors import UnsupportedDataTypeError
 
@@ -49,7 +50,7 @@ def dotplot(
     keys: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
     group_by: str | None = None,
     *,
-    rank_genes_groups: bool | str = False,
+    markers: bool | str = False,
     n_genes: int = 5,
     groups: Sequence[str] | None = None,
     mapping: FeatureSpec | None = None,
@@ -90,22 +91,20 @@ def dotplot(
     data : AnnData
         The AnnData object of the single cell data.
     keys : Sequence[str] | Mapping[str, Sequence[str]] | None, default=None
-        The variable keys to include in the dotplot. When a mapping is
-        provided, each entry maps a group label to the keys belonging to that
-        group; the keys are placed on the x-axis in mapping order. The same
-        key cannot appear in more than one group. Must be ``None`` when
-        ``rank_genes_groups`` is set.
+        Variable keys to include, placed on the x-axis. A mapping assigns
+        keys to group labels (no key in more than one group). Must be
+        ``None`` when ``markers`` is set.
     group_by : str | None, default=None
         The key to group the data by. Inferred from a precomputed ranking
-        when ``rank_genes_groups`` is set.
-    rank_genes_groups : bool | str, default=False
+        when ``markers`` is set.
+    markers : bool | str, default=False
         Derive ``keys`` from a precomputed ranking. Pass ``True`` to use the
         default ranking key, or a string to read a custom key (e.g.
         ``"rank_genes_groups_wilcoxon"``).
     n_genes : int, default=5
-        Number of top genes to take per group when ``rank_genes_groups`` is set.
+        Number of top genes to take per group when ``markers`` is set.
     groups : Sequence[str] | None, default=None
-        Subset of groups to include when ``rank_genes_groups`` is set;
+        Subset of groups to include when ``markers`` is set;
         ``None`` keeps all groups in their stored order.
     mapping : FeatureSpec | None, default=None
         Aesthetic mappings for the plot, the result of `aes()`.
@@ -187,12 +186,12 @@ def dotplot(
     UnsupportedDataTypeError
         If `data` is not a supported single-cell data object.
     KeyNotFoundError
-        If `rank_genes_groups` is enabled and the requested ranking result or
+        If `markers` is enabled and the requested ranking result or
         group is missing.
     DuplicateKeysError
         If a mapping passed to `keys` assigns the same key to multiple groups.
     ValueError
-        If `keys` and `group_by` are missing while `rank_genes_groups` is
+        If `keys` and `group_by` are missing while `markers` is
         disabled.
 
     Examples
@@ -253,7 +252,7 @@ def dotplot(
     .. jupyter-execute::
 
         sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
-        cl.dotplot(data, rank_genes_groups=True, n_genes=5)
+        cl.dotplot(data, markers=True, n_genes=5)
 
     """
     # HANDLE: Data types
@@ -261,10 +260,10 @@ def dotplot(
         msg = f"Unsupported data type: `{type(data)}`"
         raise UnsupportedDataTypeError(msg)
 
-    if rank_genes_groups:
+    if markers:
         keys, group_by = _resolve_rank_genes_groups_args(
             data,
-            rank_genes_groups=rank_genes_groups,
+            rank_genes_groups=markers,
             n_genes=n_genes,
             groups=groups,
             keys=keys,
@@ -273,7 +272,7 @@ def dotplot(
     elif keys is None or group_by is None:
         msg = (
             "`keys` and `group_by` are required "
-            "(or enable `rank_genes_groups` to derive them)."
+            "(or enable `markers` to derive them)."
         )
         raise ValueError(msg)
 
@@ -288,6 +287,15 @@ def dotplot(
         axis=0,
         variable_keys=keys,
     )
+    # WARN: negative expression makes the percent-expressed (dot size) misleading
+    overall_min = frame.select(pl.min_horizontal(pl.col(keys).min())).item()
+    if overall_min is not None and overall_min < 0:
+        _warn(
+            "Expression matrix contains negative values, which suggests scaled data. "
+            "Dot size (percentage of cells above `threshold`, default 0) assumes "
+            "non-negative expression and may be misleading here; pass raw or "
+            "log-normalized expression, or set `threshold` explicitly."
+        )
     # DROP: rows with null group_by to avoid null labels downstream
     frame = frame.filter(pl.col(group_by).is_not_null())
     index_columns = [x for x in frame.columns if x not in keys]

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/single/heatmap/heatmap.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
-from warnings import warn
 
 import polars as pl
 from anndata import AnnData
@@ -29,7 +28,12 @@ from cellestial.single.heatmap._key_groups import (
 )
 from cellestial.single.heatmap._rank_genes_groups import _resolve_rank_genes_groups_args
 from cellestial.themes import _THEME_HEATMAP
-from cellestial.util import _fill_gradient, _get_dendrogram, _get_dendrogram_path_frame
+from cellestial.util import (
+    _fill_gradient,
+    _get_dendrogram,
+    _get_dendrogram_path_frame,
+    _warn,
+)
 from cellestial.util.errors import UnsupportedDataTypeError
 
 if TYPE_CHECKING:
@@ -188,7 +192,7 @@ def heatmap(
     keys: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
     group_by: str | None = None,
     *,
-    rank_genes_groups: bool | str = False,
+    markers: bool | str = False,
     n_genes: int = 5,
     groups: Sequence[str] | None = None,
     mapping: FeatureSpec | None = None,
@@ -233,21 +237,20 @@ def heatmap(
     data : AnnData
         The AnnData object of the single cell data.
     keys : Sequence[str] | Mapping[str, Sequence[str]] | None, default=None
-        Variable keys to include. When a mapping is provided, each entry maps a
-        group label to the keys belonging to that group; the keys are placed
-        on the x-axis in mapping order. The same key cannot appear in more
-        than one group. Must be ``None`` when ``rank_genes_groups`` is set.
+        Variable keys to include, placed on the x-axis. A mapping assigns
+        keys to group labels (no key in more than one group). Must be
+        ``None`` when ``markers`` is set.
     group_by : str | None, default=None
         The key to group the data by. Inferred from a precomputed ranking
-        when ``rank_genes_groups`` is set.
-    rank_genes_groups : bool | str, default=False
+        when ``markers`` is set.
+    markers : bool | str, default=False
         Derive ``keys`` from a precomputed ranking. Pass ``True`` to use the
         default ranking key, or a string to read a custom key (e.g.
         ``"rank_genes_groups_wilcoxon"``).
     n_genes : int, default=5
-        Number of top genes to take per group when ``rank_genes_groups`` is set.
+        Number of top genes to take per group when ``markers`` is set.
     groups : Sequence[str] | None, default=None
-        Subset of groups to include when ``rank_genes_groups`` is set;
+        Subset of groups to include when ``markers`` is set;
         ``None`` keeps all groups in their stored order.
     mapping : FeatureSpec | None, default=None
         Aesthetic mappings for the plot, the result of `aes()`.
@@ -338,12 +341,12 @@ def heatmap(
     UnsupportedDataTypeError
         If `data` is not a supported single-cell data object.
     KeyNotFoundError
-        If `rank_genes_groups` is enabled and the requested ranking result or
+        If `markers` is enabled and the requested ranking result or
         group is missing.
     DuplicateKeysError
         If a mapping passed to `keys` assigns the same key to multiple groups.
     ValueError
-        If `keys` and `group_by` are missing while `rank_genes_groups` is
+        If `keys` and `group_by` are missing while `markers` is
         disabled.
 
     Examples
@@ -426,7 +429,7 @@ def heatmap(
         )
 
     To plot the top genes from a precomputed ranking, set
-    ``rank_genes_groups`` and ``n_genes`` (``keys`` and ``group_by`` are
+    ``markers`` and ``n_genes`` (``keys`` and ``group_by`` are
     inferred):
 
     .. jupyter-execute::
@@ -434,17 +437,17 @@ def heatmap(
         import scanpy as sc
 
         sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
-        cl.heatmap(data, rank_genes_groups=True, n_genes=5, aggregate=True)
+        cl.heatmap(data, markers=True, n_genes=5, aggregate=True)
 
     """
     if not isinstance(data, AnnData):
         msg = f"Unsupported data type: `{type(data)}`"
         raise UnsupportedDataTypeError(msg)
 
-    if rank_genes_groups:
+    if markers:
         keys, group_by = _resolve_rank_genes_groups_args(
             data,
-            rank_genes_groups=rank_genes_groups,
+            rank_genes_groups=markers,
             n_genes=n_genes,
             groups=groups,
             keys=keys,
@@ -453,17 +456,16 @@ def heatmap(
     elif keys is None or group_by is None:
         msg = (
             "`keys` and `group_by` are required "
-            "(or enable `rank_genes_groups` to derive them)."
+            "(or enable `markers` to derive them)."
         )
         raise ValueError(msg)
 
     mapping = mapping or aes()
 
     if "tooltips" in geom_kwargs and geom == "raster":
-        warn(
+        _warn(
             "\nWarning: tooltips are not supported for 'raster' geom and will be ignored."
-            "\nUse 'tile' geom to enable tooltips.",
-            stacklevel=1,
+            "\nUse 'tile' geom to enable tooltips."
         )
         geom_kwargs.pop("tooltips")
 
@@ -649,7 +651,7 @@ def matrixplot(
     keys: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
     group_by: str | None = None,
     *,
-    rank_genes_groups: bool | str = False,
+    markers: bool | str = False,
     n_genes: int = 5,
     groups: Sequence[str] | None = None,
     mapping: FeatureSpec | None = None,
@@ -692,21 +694,20 @@ def matrixplot(
     data : AnnData
         The AnnData object of the single cell data.
     keys : Sequence[str] | Mapping[str, Sequence[str]] | None, default=None
-        Variable keys to include. When a mapping is provided, each entry maps
-        a group label to the keys belonging to that group; the keys are placed
-        on the x-axis in mapping order. The same key cannot appear in more
-        than one group. Must be ``None`` when ``rank_genes_groups`` is set.
+        Variable keys to include, placed on the x-axis. A mapping assigns
+        keys to group labels (no key in more than one group). Must be
+        ``None`` when ``markers`` is set.
     group_by : str | None, default=None
         The key to group the data by. Inferred from a precomputed ranking
-        when ``rank_genes_groups`` is set.
-    rank_genes_groups : bool | str, default=False
+        when ``markers`` is set.
+    markers : bool | str, default=False
         Derive ``keys`` from a precomputed ranking. Pass ``True`` to use the
         default ranking key, or a string to read a custom key (e.g.
         ``"rank_genes_groups_wilcoxon"``).
     n_genes : int, default=5
-        Number of top genes to take per group when ``rank_genes_groups`` is set.
+        Number of top genes to take per group when ``markers`` is set.
     groups : Sequence[str] | None, default=None
-        Subset of groups to include when ``rank_genes_groups`` is set;
+        Subset of groups to include when ``markers`` is set;
         ``None`` keeps all groups in their stored order.
     mapping : FeatureSpec | None, default=None
         Aesthetic mappings for the plot, the result of `aes()`.
@@ -817,13 +818,13 @@ def matrixplot(
     .. jupyter-execute::
 
         sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
-        cl.matrixplot(data, rank_genes_groups=True, n_genes=5)
+        cl.matrixplot(data, markers=True, n_genes=5)
     """
     return heatmap(
         data,
         keys=keys,
         group_by=group_by,
-        rank_genes_groups=rank_genes_groups,
+        markers=markers,
         n_genes=n_genes,
         groups=groups,
         mapping=mapping,

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/single/heatmap/stacked_violin.py

@@ -179,7 +179,7 @@ def stacked_violin(
     keys: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
     group_by: str | None = None,
     *,
-    rank_genes_groups: bool | str = False,
+    markers: bool | str = False,
     n_genes: int = 5,
     groups: Sequence[str] | None = None,
     mapping: FeatureSpec | None = None,
@@ -227,22 +227,20 @@ def stacked_violin(
     data : AnnData
         The AnnData object of the single cell data.
     keys : Sequence[str] | Mapping[str, Sequence[str]] | None, default=None
-        Variable keys laid out along the x-axis. One column of violins per
-        key. When a mapping is provided, each entry maps a group label to the
-        keys belonging to that group; the keys are placed on the x-axis in
-        mapping order. The same key cannot appear in more than one group.
-        Must be ``None`` when ``rank_genes_groups`` is set.
+        Variable keys laid out along the x-axis, one column of violins per
+        key. A mapping assigns keys to group labels (no key in more than one
+        group). Must be ``None`` when ``markers`` is set.
     group_by : str | None, default=None
         The key used to group observations along the y-axis. Inferred from a
-        precomputed ranking when ``rank_genes_groups`` is set.
-    rank_genes_groups : bool | str, default=False
+        precomputed ranking when ``markers`` is set.
+    markers : bool | str, default=False
         Derive ``keys`` from a precomputed ranking. Pass ``True`` to use the
         default ranking key, or a string to read a custom key (e.g.
         ``"rank_genes_groups_wilcoxon"``).
     n_genes : int, default=5
-        Number of top genes to take per group when ``rank_genes_groups`` is set.
+        Number of top genes to take per group when ``markers`` is set.
     groups : Sequence[str] | None, default=None
-        Subset of groups to include when ``rank_genes_groups`` is set;
+        Subset of groups to include when ``markers`` is set;
         ``None`` keeps all groups in their stored order.
     mapping : FeatureSpec | None, default=None
         Aesthetic mappings for the plot, the result of `aes()`.
@@ -349,12 +347,12 @@ def stacked_violin(
     UnsupportedDataTypeError
         If `data` is not a supported single-cell data object.
     KeyNotFoundError
-        If `rank_genes_groups` is enabled and the requested ranking result or
+        If `markers` is enabled and the requested ranking result or
         group is missing.
     DuplicateKeysError
         If a mapping passed to `keys` assigns the same key to multiple groups.
     ValueError
-        If `keys` and `group_by` are missing while `rank_genes_groups` is
+        If `keys` and `group_by` are missing while `markers` is
         disabled.
 
     Examples
@@ -407,17 +405,17 @@ def stacked_violin(
     .. jupyter-execute::
 
         sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
-        cl.stacked_violin(data, rank_genes_groups=True, n_genes=5)
+        cl.stacked_violin(data, markers=True, n_genes=5)
     """
     # HANDLE: Data types
     if not isinstance(data, AnnData):
         msg = f"Unsupported data type: `{type(data)}`"
         raise UnsupportedDataTypeError(msg)
 
-    if rank_genes_groups:
+    if markers:
         keys, group_by = _resolve_rank_genes_groups_args(
             data,
-            rank_genes_groups=rank_genes_groups,
+            rank_genes_groups=markers,
             n_genes=n_genes,
             groups=groups,
             keys=keys,
@@ -426,7 +424,7 @@ def stacked_violin(
     elif keys is None or group_by is None:
         msg = (
             "`keys` and `group_by` are required "
-            "(or enable `rank_genes_groups` to derive them)."
+            "(or enable `markers` to derive them)."
         )
         raise ValueError(msg)
 

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/spatial/spatial.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import warnings
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
@@ -30,6 +29,7 @@ from cellestial.util import (
     _is_variable_key,
     _resolve_tooltips,
     _validate_tooltips,
+    _warn,
 )
 from cellestial.util.errors import UnsupportedDataTypeError
 
@@ -113,7 +113,7 @@ def _spatial_components(
             image_array = images.get(image_key)
             if image_array is None:
                 msg = f"image `{image_key}` not found for library `{library_id}`"
-                warnings.warn(msg, stacklevel=2)
+                _warn(msg)
         return image_array, spot_coordinates, None, data
 
     msg = f"Unsupported data type: `{type(data)}`"
@@ -408,7 +408,7 @@ def spatial(
             frame = frame.filter(pl.col(key).is_in(list(groups)))
         else:
             msg = f"key `{key}` is not categorical, `groups` filter ignored"
-            warnings.warn(msg, stacklevel=1)
+            _warn(msg)
 
     # HANDLE: standard scaling (numeric keys only)
     if scale_axis is not None and key is not None and frame[key].dtype.is_numeric():

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/util/__init__.py

@@ -18,6 +18,7 @@ from cellestial.util.utilities import (
     _share_ticks,
     _tooltip_fields,
     _validate_tooltips,
+    _warn,
 )
 
 __all__ = [
@@ -36,6 +37,7 @@ __all__ = [
     "_share_ticks",
     "_tooltip_fields",
     "_validate_tooltips",
+    "_warn",
     "get_mapping",
     "get_slice",
     "retrieve",

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/util/errors.py

@@ -59,3 +59,7 @@ class SpatialLibraryError(Exception):
 
     def __init__(self, message: str):
         super().__init__(message)
+
+
+class CellestialWarning(UserWarning):
+    """Base category for warnings raised by cellestial."""

{cellestial-0.45.0 → cellestial-0.46.0}/cellestial/util/utilities.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
+import inspect
 import re
+import warnings
 from collections.abc import Sequence
 from math import ceil, log10
+from pathlib import Path
 from typing import Literal
 
 import polars as pl
@@ -21,6 +24,44 @@ from lets_plot import (
 from lets_plot.plot.core import FeatureSpec
 from lets_plot.plot.subplots import SupPlotsSpec
 
+from cellestial.util.errors import CellestialWarning
+
+_PACKAGE_ROOT = str(Path(__file__).parents[1])
+
+
+def _format_warning(
+    message: Warning | str, category: type[Warning], *_args: object
+) -> str:
+    """Render a cellestial warning as one line, dropping the source location."""
+    return f"{category.__name__}: {message}\n"
+
+
+def _warn(message: str) -> None:
+    """
+    Emit a ``CellestialWarning`` rendered without the source location.
+
+    The warning is still attributed to the first caller outside cellestial so
+    ``warnings`` filters and per-location de-duplication behave sensibly, but
+    it is displayed as a single clean line.
+
+    Parameters
+    ----------
+    message : str
+        The warning message.
+    """
+    caller = inspect.currentframe()
+    caller = caller.f_back if caller is not None else None
+    stacklevel = 2
+    while caller is not None and caller.f_code.co_filename.startswith(_PACKAGE_ROOT):
+        stacklevel += 1
+        caller = caller.f_back
+    original_format = warnings.formatwarning
+    warnings.formatwarning = _format_warning
+    try:
+        warnings.warn(message, CellestialWarning, stacklevel=stacklevel)
+    finally:
+        warnings.formatwarning = original_format
+
 
 def _build_tooltips(
     *,

{cellestial-0.45.0 → cellestial-0.46.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cellestial"
-version = "0.45.0"
+version = "0.46.0"
 description = ""
 authors = [
     { name = "Zaf4", email = "zafermolbio@gmail.com" },