cellestial 0.48.0__tar.gz → 0.48.2__tar.gz

{cellestial-0.48.0 → cellestial-0.48.2}/PKG-INFO

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

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/frames/operations.py

@@ -50,15 +50,13 @@ def _pca_variance_frame(
     n_pcs: int | None = None,
     component_column: str = "Principal Component",
     variance_column: str = "Variance Ratio",
+    use_key: str = "pca",
 ) -> DataFrame:
     """Get PCA variance ratio per principal component as a polars DataFrame."""
     if isinstance(data, AnnData):
-        pca_uns = data.uns.get("pca")
+        pca_uns = data.uns.get(use_key)
         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)`)."
-            )
+            msg = f"PCA variance ratio not found under `{use_key}`. Run PCA first."
             raise ValueError(msg)
         variance_ratio = np.asarray(pca_uns["variance_ratio"]).ravel()
         n_available = variance_ratio.size

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/single/core/dimensional.py

@@ -24,6 +24,7 @@ from cellestial.themes import _THEME_DIMENSION
 from cellestial.util import (
     _color_gradient,
     _is_variable_key,
+    _resolve_embedding_key,
     _resolve_tooltips,
     _validate_tooltips,
     _warn,
@@ -228,12 +229,9 @@ def dimensional(
     if len(xy) != 2:
         msg = f"xy MUST be of length 2, (len(xy)=={len(xy)})"
         raise KeyError(msg)
-    if use_key is None:
-        x = f"X_{dimensions.upper()}{xy[0]}"  # e.g. X_UMAP1
-        y = f"X_{dimensions.upper()}{xy[1]}"  # e.g. X_UMAP2
-    else:
-        x = f"{use_key}{xy[0]}"  # e.g. X_UMAP1
-        y = f"{use_key}{xy[1]}"  # e.g. X_UMAP2
+    prefix = _resolve_embedding_key(data=data, dimensions=dimensions, use_key=use_key, xy=xy)
+    x = f"{prefix}{xy[0]}"  # e.g. X_UMAP1
+    y = f"{prefix}{xy[1]}"  # e.g. X_UMAP2
 
     # HANDLE: variable_keys
     if variable_keys is None:

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/single/heatmap/dotplot.py

@@ -69,6 +69,7 @@ def dotplot(
     dendrogram: bool = False,
     dendrogram_color: str = "black",
     dendrogram_size: float = 0.5,
+    dendrogram_key: str | None = None,
     dendrogram_kwargs: dict | None = None,
     rectangle_size: float = 0.8,
     rectangle_color: str = "#3f3f3f",
@@ -144,6 +145,9 @@ def dotplot(
         Color of the dendrogram segments.
     dendrogram_size : float, default=0.5
         Size (thickness) of the dendrogram segments.
+    dendrogram_key : str | None, default=None
+        Specific key holding the precomputed dendrogram.
+        By default, `dendrogram_{group_by}` is used.
     dendrogram_kwargs : dict | None, default=None
         Additional parameters to pass to the dendrogram geom_segment.
     rectangle_size : float, default=0.8
@@ -339,7 +343,7 @@ def dotplot(
 
     # DETERMINE: y order of groups
     if dendrogram:
-        y_order_groups, paths = _get_dendrogram(data, group_by)
+        y_order_groups, paths = _get_dendrogram(data, group_by, use_key=dendrogram_key)
     else:
         y_order_groups = (
             frame.select(group_by).unique(maintain_order=True)[group_by].cast(pl.String).to_list()

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/single/heatmap/heatmap.py

@@ -209,6 +209,7 @@ def heatmap(
     group_lines_size: float = 0.6,
     dendrogram_color: str = "black",
     dendrogram_size: float = 0.5,
+    dendrogram_key: str | None = None,
     group_lines_kwargs: dict | None = None,
     dendrogram_kwargs: dict | None = None,
     key_labels: bool = True,
@@ -284,6 +285,9 @@ def heatmap(
         Color of the dendrogram segments.
     dendrogram_size : float, default=0.5
         Size (thickness) of the dendrogram segments.
+    dendrogram_key : str | None, default=None
+        Specific key holding the precomputed dendrogram.
+        By default, `dendrogram_{group_by}` is used.
     group_lines_kwargs : dict | None, default=None
         Additional parameters to pass to the group separator lines geom_segment.
     dendrogram_kwargs : dict | None, default=None
@@ -499,7 +503,7 @@ def heatmap(
 
     # DETERMINE: y order of groups
     if dendrogram:
-        y_order_groups, paths = _get_dendrogram(data, group_by)
+        y_order_groups, paths = _get_dendrogram(data, group_by, use_key=dendrogram_key)
     else:
         y_order_groups = (
             frame.select(group_by).unique(maintain_order=True)[group_by].cast(pl.String).to_list()
@@ -662,6 +666,7 @@ def matrixplot(
     group_lines_size: float = 0.6,
     dendrogram_color: str = "black",
     dendrogram_size: float = 0.5,
+    dendrogram_key: str | None = None,
     group_lines_kwargs: dict | None = None,
     dendrogram_kwargs: dict | None = None,
     key_labels: bool = True,
@@ -731,6 +736,9 @@ def matrixplot(
         Color of the dendrogram segments.
     dendrogram_size : float, default=0.5
         Size (thickness) of the dendrogram segments.
+    dendrogram_key : str | None, default=None
+        Specific key holding the precomputed dendrogram.
+        By default, `dendrogram_{group_by}` is used.
     group_lines_kwargs : dict | None, default=None
         Additional parameters to pass to the group separator lines geom_segment.
     dendrogram_kwargs : dict | None, default=None
@@ -842,6 +850,7 @@ def matrixplot(
         group_lines_size=group_lines_size,
         dendrogram_color=dendrogram_color,
         dendrogram_size=dendrogram_size,
+        dendrogram_key=dendrogram_key,
         group_lines_kwargs=group_lines_kwargs,
         dendrogram_kwargs=dendrogram_kwargs,
         value_column=value_column,

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/single/heatmap/stacked_violin.py

@@ -199,6 +199,7 @@ def stacked_violin(
     dendrogram: bool = False,
     dendrogram_color: str = "black",
     dendrogram_size: float = 0.5,
+    dendrogram_key: str | None = None,
     dendrogram_kwargs: dict | None = None,
     rectangle: bool = True,
     rectangle_size: float = 0.8,
@@ -292,6 +293,9 @@ def stacked_violin(
         Color of the dendrogram segments.
     dendrogram_size : float, default=0.5
         Size (thickness) of the dendrogram segments.
+    dendrogram_key : str | None, default=None
+        Specific key holding the precomputed dendrogram.
+        By default, `dendrogram_{group_by}` is used.
     dendrogram_kwargs : dict | None, default=None
         Additional parameters to pass to the dendrogram geom_path.
     rectangle : bool, default=True
@@ -456,7 +460,7 @@ def stacked_violin(
 
     # DETERMINE: y order of groups (dendrogram or first-seen order)
     if dendrogram:
-        y_order_groups, paths = _get_dendrogram(data, group_by)
+        y_order_groups, paths = _get_dendrogram(data, group_by, use_key=dendrogram_key)
     else:
         y_order_groups = (
             frame.select(group_by).unique(maintain_order=True)[group_by].cast(pl.String).to_list()

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/single/quick/elbow.py

@@ -36,6 +36,7 @@ def elbow(
     label: bool = False,
     label_size: float = 4.0,
     label_every: int = 5,
+    pca_key: str = "pca",
     **geom_kwargs,
 ) -> PlotSpec:
     """
@@ -73,6 +74,8 @@ def elbow(
     label_every : int, default=5
         Only components whose number is a multiple of this value are labeled
         (used when `label=True`). For example, `5` labels PC5, PC10, PC15, ...
+    pca_key : str, default='pca'
+        Specific key holding the PCA results.
     **geom_kwargs
         Additional parameters for the `geom_point` layer.
         For more information on geom_point parameters, see:
@@ -124,6 +127,7 @@ def elbow(
         n_pcs=n_pcs,
         component_column=component_column,
         variance_column=variance_column,
+        use_key=pca_key,
     )
 
     # HANDLE: mapping

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/spatial/spatial.py

@@ -104,7 +104,15 @@ def _spatial_components(
 
         library = spatial_uns[library_id]
         scale_factors = library.get("scalefactors", {})
-        scale_factor = scale_factors.get(f"tissue_{image_key}_scalef", 1.0)
+        scalef_key = f"tissue_{image_key}_scalef"
+        scale_factor = scale_factors.get(scalef_key)
+        if scale_factor is None:
+            if image:
+                _warn(
+                    f"Scale factor `{scalef_key}` missing; "
+                    "spots may not align with the image."
+                )
+            scale_factor = 1.0
         spot_coordinates = data.obsm[spatial_key] * scale_factor
 
         image_array = None

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/util/__init__.py

@@ -11,6 +11,7 @@ from cellestial.util.utilities import (
     _is_observation_key,
     _is_variable_key,
     _range_inclusive,
+    _resolve_embedding_key,
     _resolve_tooltips,
     _select_variable_keys,
     _share_axis,
@@ -30,6 +31,7 @@ __all__ = [
     "_is_observation_key",
     "_is_variable_key",
     "_range_inclusive",
+    "_resolve_embedding_key",
     "_resolve_tooltips",
     "_select_variable_keys",
     "_share_axis",

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/util/dendrogram.py

@@ -4,22 +4,21 @@ import polars as pl
 from anndata import AnnData
 
 
-def _get_dendrogram(data: AnnData, group_by: str) -> tuple[list[str], pl.DataFrame]:
-    """
-    Get or compute the dendrogram for a group_by key and extract paths.
-
-    Checks ``data.uns[f'dendrogram_{group_by}']``.
-    For AnnData, if not present, runs ``scanpy.tl.dendrogram`` to compute it.
-    Extracts the icoord/dcoord arrays into a Polars DataFrame of paths with normalized positions.
-    """
+def _get_dendrogram(
+    data: AnnData,
+    group_by: str,
+    *,
+    use_key: str | None = None,
+) -> tuple[list[str], pl.DataFrame]:
+    """Get or compute the dendrogram for `group_by` and extract paths."""
     import numpy as np
 
     if isinstance(data, AnnData):
-        key = f"dendrogram_{group_by}"
+        key = use_key if use_key is not None else f"dendrogram_{group_by}"
         if key not in data.uns:
             import scanpy as sc
 
-            sc.tl.dendrogram(data, groupby=group_by)
+            sc.tl.dendrogram(data, groupby=group_by, key_added=key)
 
         dendro = data.uns[key]
         categories_ordered = list(dendro["categories_ordered"])

{cellestial-0.48.0 → cellestial-0.48.2}/cellestial/util/utilities.py

@@ -24,7 +24,7 @@ from lets_plot import (
 from lets_plot.plot.core import FeatureSpec
 from lets_plot.plot.subplots import SupPlotsSpec
 
-from cellestial.util.errors import CellestialWarning
+from cellestial.util.errors import CellestialWarning, KeyNotFoundError, UnsupportedDataTypeError
 
 _PACKAGE_ROOT = str(Path(__file__).parents[1])
 
@@ -532,6 +532,97 @@ def _are_variable_features(data: AnnData, keys: Sequence[str] | None) -> bool:
     return result
 
 
+def _resolve_embedding_key(
+    data: AnnData,
+    dimensions: str,
+    use_key: str | None,
+    xy: Sequence[int],
+) -> str:
+    """
+    Resolve the column-name prefix used to index an embedding in the built frame.
+
+    `build_frame` emits embedding columns as ``f"{KEY.upper()}{n}"``, so callers
+    compose axis names like ``X_UMAP1`` / ``X_UMAP2`` by appending the axis
+    index to the prefix returned here.
+
+    Resolution rules
+    ----------------
+    1. If ``use_key`` is given, return it uppercased.
+    2. Otherwise, against ``f"X_{dimensions.upper()}"``:
+       - exact (case-insensitive) match -> return it silently.
+       - no exact, but prefix matches exist -> pick the candidate whose
+         dimensionality is sufficient for ``max(xy)`` (shortest name on ties),
+         warn the user, and suggest ``use_key`` to silence.
+       - no candidate -> raise ``KeyNotFoundError``.
+
+    Parameters
+    ----------
+    data : AnnData
+        Single-cell data object providing the embedding store.
+    dimensions : str
+        Embedding family, e.g. ``"umap"``, ``"pca"``, ``"tsne"``.
+    use_key : str | None
+        Explicit embedding key. When provided, no search is performed.
+    xy : Sequence[int]
+        Axis indices requested (1-based); used to filter shape-eligible
+        candidates during fallback.
+
+    Returns
+    -------
+    str
+        Uppercase column-name prefix.
+
+    Raises
+    ------
+    UnsupportedDataTypeError
+        If `data` is not a supported single-cell data object.
+    KeyNotFoundError
+        If no embedding matches the requested family.
+    """
+    if use_key is not None:
+        return use_key.upper()
+
+    if isinstance(data, AnnData):
+        candidates = list(data.obsm.keys())
+        shapes = {key: data.obsm[key].shape[1] for key in candidates}
+    else:
+        msg = f"Unsupported data type: `{type(data)}`"
+        raise UnsupportedDataTypeError(msg)
+
+    target = f"X_{dimensions.upper()}"
+    needed = max(xy)
+    search_targets = (target, dimensions.upper())  # accept bare `UMAP` too, not only `X_UMAP`
+
+    for key in candidates:
+        if key.upper() in search_targets:
+            return key.upper()
+
+    prefix_matches = [
+        key for key in candidates
+        if any(key.upper().startswith(t) for t in search_targets)
+    ]
+    if not prefix_matches:
+        msg = (
+            f"No embedding found for `dimensions='{dimensions}'`\n"
+            f"(looked for `{target}` or any key starting with it).\n"
+            f"Available embeddings: {candidates}."
+        )
+        raise KeyNotFoundError(msg)
+
+    eligible = [key for key in prefix_matches if shapes[key] >= needed]
+    pool = eligible or prefix_matches
+    chosen = sorted(pool, key=lambda key: (len(key), key))[0]
+
+    alternatives = sorted(prefix_matches)
+    _warn(
+        f"No embedding named `{target}` found; "
+        f"using `{chosen}` with (shape={shapes[chosen]})\n"
+        f"Alternatives: {alternatives}, Rest: {list(set(candidates) - set(alternatives))}.\n"
+        "Pass `use_key='...'` to use a specific key."
+    )
+    return chosen.upper()
+
+
 def _determine_axis(
     data: AnnData,
     keys: str | Sequence[str],

{cellestial-0.48.0 → cellestial-0.48.2}/pyproject.toml

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