cellestial 0.48.4__tar.gz → 0.49.0__tar.gz

{cellestial-0.48.4 → cellestial-0.49.0}/PKG-INFO

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

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/datasets/datasets.py

@@ -487,7 +487,7 @@ def from_url(
     print(f"No cache at {cache_file} !")
     print(f"Downloading from {url} ...")
 
-    block_size = 1024
+    block_size = 1024 * 1024
     # Stream to a .part file and atomically rename on success, so an interrupted
     # download cannot poison the cache.
     partial_file = cache_file.with_name(cache_file.name + ".part")

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/frames/build.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
 
+import numpy as np
 import pandas as pd
 import polars as pl
 from anndata import AnnData
+from scipy.sparse import issparse
 from spatialdata import SpatialData
 
 from cellestial.util.errors import UnsupportedDataTypeError, VariableNotFoundError
@@ -29,17 +31,23 @@ def anndata_variable_columns(
     columns = []
     if isinstance(keys, str):
         keys = [keys]
-    for key in keys:
-        if key in column_names:  # check for repeats
-            continue
-        elif key in data.var_names:
-            values = data.obs_vector(key)
-            # add the variable column to the list of columns
-            columns.append(pl.Series(key, values).cast(pl.Float32))
-            column_names.append(key)
-        else:
-            msg = f"Key `{key}` not found in data."
-            raise VariableNotFoundError(msg)
+    # remove keys that are already in column_names to avoid repeats
+    keys = [key for key in keys if key not in column_names]
+    # check that all keys are in data.var_names
+    available_names = set(data.var_names)
+    missing = [key for key in keys if key not in available_names]
+    if missing:
+        msg = f"Keys not found in data.var_names: {missing}"
+        raise VariableNotFoundError(msg)
+
+    # subset X
+    X = data[:, keys].X
+
+    if issparse(X):
+        X = X.toarray()  # ty:ignore[unresolved-attribute]
+    else:
+        X = np.asarray(X)
+    columns = [pl.Series(key, X[:, i]) for i, key in enumerate(keys)]
 
     return columns
 
@@ -210,7 +218,7 @@ def anndata_variables_frame(
 
 
 def build_frame(
-    data: AnnData,
+    data: AnnData | SpatialData,
     *,
     variable_keys: str | Sequence[str] | None = None,
     axis: Literal[0, 1] | None = None,
@@ -223,8 +231,8 @@ def build_frame(
 
     Parameters
     ----------
-    data : AnnData
-        The AnnData object containing the variables.
+    data : AnnData | SpatialData
+        The AnnData or SpatialData object containing the variables.
     variable_keys : str | Sequence[str] | None
         Variable keys to add to the DataFrame. If None, no additional keys are added.
     axis : {0,1} | None
@@ -282,6 +290,7 @@ def build_frame(
     if isinstance(data, SpatialData):
         tables = list(data.tables.keys())
         if len(tables) == 1:
+            # retrieve an anndata
             data = data.tables[tables[0]]
         elif len(tables) == 0:
             msg = "No annotation tables found in the SpatialData object."

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/frames/operations.py

@@ -6,7 +6,6 @@ from anndata import AnnData
 from polars import DataFrame
 from scipy.sparse import issparse
 
-from cellestial.frames.build import anndata_variable_columns
 from cellestial.util.errors import UnsupportedDataTypeError
 
 
@@ -16,28 +15,44 @@ def _highest_expressed_genes_frame(
 ) -> DataFrame:
     """Get the top n highest expressed genes by mean percentage across all cells."""
     if isinstance(data, AnnData):
+        # VALIDATE: inputs
         if n > data.n_vars:
             msg = f"Requested n={n} genes, but only {data.n_vars} genes available in data."
             raise ValueError(msg)
         X = data.X
-        # normalize each cell to sum to 100 (percentage)
+        # matmul and fancy indexing below require an in-memory ndarray/sparse;
+        # fail fast on backed/dask/zappy rather than crashing deep in the math.
+        if not (isinstance(X, np.ndarray) or issparse(X)):
+            msg = (
+                f"Unsupported `X` type for this operation: {type(X).__name__}. "
+                "Load AnnData in non-backed mode or materialize `X` manually."
+            )
+            raise UnsupportedDataTypeError(msg)
+
+        # BUILD: per-cell normalizer so each cell's expression sums to 100
         if issparse(X):
-            row_sums = np.array(X.sum(axis=1)).ravel()
-            row_sums[row_sums == 0] = 1
-            X_normalized = X.multiply(100 / row_sums[:, np.newaxis])
-            mean_percent = np.array(X_normalized.mean(axis=0)).ravel()
+            row_sums = np.asarray(X.sum(axis=1)).ravel()
         else:
-            row_sums = X.sum(axis=1, keepdims=True)
-            row_sums[row_sums == 0] = 1
-            X_normalized = X / row_sums * 100
-            mean_percent = X_normalized.mean(axis=0)
+            row_sums = X.sum(axis=1)
+        row_sums[row_sums == 0] = 1  # guard cells with zero total to avoid div-by-zero
+        inv_rows = 100.0 / row_sums
 
+        # RANK: gene means via a single matvec instead of materializing the
+        # full normalized matrix. Identity: mean(X / row_sums * 100, axis=0)
+        # equals (inv_rows @ X) / n_cells, but uses O(n_vars) memory instead of O(n_obs * n_vars).
+        mean_percent = np.asarray(inv_rows @ X).ravel() / X.shape[0]
         top_idx = np.argsort(mean_percent)[::-1][:n]
         genes = data.var_names[top_idx].tolist()
-        if issparse(X_normalized):
-            X_normalized = X_normalized.tocsr()
-        norm_data = AnnData(X=X_normalized, var=data.var, obs=data.obs)
-        frame = pl.DataFrame(anndata_variable_columns(norm_data, keys=genes, column_names=[]))
+
+        # EXTRACT: normalize only the top n columns (small n_obs * n slice),
+        # skipping the full n_obs * n_vars materialization the naive path would do.
+        X_top = X[:, top_idx]
+        if issparse(X_top):
+            X_top = X_top.toarray()
+        X_top_normalized = X_top * inv_rows[:, np.newaxis]
+
+        # BUILD: polars frame keyed by gene name
+        frame = pl.DataFrame({gene: X_top_normalized[:, i] for i, gene in enumerate(genes)})
     else:
         msg = f"Unsupported data type: `{type(data)}`"
         raise UnsupportedDataTypeError(msg)

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/layers/bracket.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Literal
 import numpy as np
 import polars as pl
 from lets_plot import aes, geom_bracket
+from scipy.stats import mannwhitneyu, ttest_ind
 
 from cellestial.layers._deferred import DeferredLayer
 from cellestial.util import get_mapping, retrieve
@@ -134,8 +135,6 @@ def _compute_bracket_frame(
     y_padding: float,
 ) -> DataFrame:
     """Build a `geom_bracket` DataFrame from pairwise significance tests."""
-    from scipy.stats import mannwhitneyu, ttest_ind
-
     # determine which pairs to compare
     groups = frame[x].drop_nulls().unique(maintain_order=True).to_list()
     if comparisons is None:
@@ -238,10 +237,10 @@ def _compute_bracket_frame(
     brackets = brackets.with_columns(label=pl.Series(labels))
 
     # compute y positions so brackets stack above the data without overlapping
-    values = frame[y].to_numpy()
-    data_min = float(values.min())
-    data_max = float(values.max())
-    data_range = data_max - data_min
+
+    data_min = frame[y].min()
+    data_max = frame[y].max()
+    data_range = data_max - data_min  # ty:ignore[unsupported-operator]
     _y_position = data_max + data_range * y_padding if y_position is None else y_position
     _y_step = data_range * y_padding if y_step is None else y_step
     positions = [_y_position + _y_step * index for index in range(len(brackets))]

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/layers/outline.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Literal
 import numpy as np
 import polars as pl
 from lets_plot import aes, geom_path
+from scipy.stats import gaussian_kde
 
 from cellestial.layers._deferred import DeferredLayer
 from cellestial.util import get_mapping
@@ -28,7 +29,6 @@ def _get_density_boundaries(
     grid_size: int = 200,
 ) -> DataFrame:
     """Creates and Returns a DataFrame to encircle the cluster via `geom_path`."""
-    from scipy.stats import gaussian_kde
     from skimage import measure
 
     # 1. Normalize input to a Sequence of Sequences: List[List[str]]

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/single/heatmap/stacked_violin.py

@@ -18,6 +18,7 @@ from lets_plot import (
     theme,
 )
 from lets_plot.plot.core import FeatureSpec
+from scipy.stats import gaussian_kde
 
 from cellestial.frames import build_frame
 from cellestial.single.heatmap._key_groups import (
@@ -65,8 +66,6 @@ def _compute_violin_polygons(
     mapped to local y inside the row band and density mapped to local x around
     the column position.
     """
-    from scipy.stats import gaussian_kde
-
     var_stats = frame.group_by(variable_column).agg(
         pl.col(value_column).min().alias("_vmin"),
         pl.col(value_column).max().alias("_vmax"),

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/util/dendrogram.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import numpy as np
 import polars as pl
 from anndata import AnnData
 
@@ -11,8 +12,6 @@ def _get_dendrogram(
     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 = use_key if use_key is not None else f"dendrogram_{group_by}"
         if key not in data.uns:
@@ -57,8 +56,6 @@ def _get_dendrogram_path_frame(
     dendrogram_ratio: float = 0.15,
 ) -> pl.DataFrame:
     """Map normalized dendrogram paths into plot coordinates (right side along y-axis)."""
-    import numpy as np
-
     y_dendrogram_size = n_x * dendrogram_ratio
     leaf_xp = np.arange(n_groups, dtype=float)
     plot_y = np.interp(paths["x"].to_numpy(), leaf_xp, group_centers)

{cellestial-0.48.4 → cellestial-0.49.0}/cellestial/util/utilities.py

@@ -4,6 +4,7 @@ import inspect
 import re
 import warnings
 from collections.abc import Sequence
+from functools import lru_cache
 from math import ceil, log10
 from pathlib import Path
 from typing import Literal
@@ -286,19 +287,24 @@ def _fill_gradient(
             midpoint=mid_value,
         )
 
-
-def _share_labels(plot, i: int, keys: Sequence[str], ncol: int | None) -> SupPlotsSpec:
+# cache to avoid recomputing for every plot in a grid...
+@lru_cache(maxsize=32)
+def _grid_places(total: int, ncol: int | None) -> tuple[frozenset[int], frozenset[int]]:
     if ncol is None:
-        ncol = len(keys)
-    total = len(keys)
+        ncol = total
     nrow = ceil(total / ncol)
-    left_places = [i for i in range(total) if i % ncol == 0]
-    bottom_places = [i for i in range(total) if i >= ncol * (nrow - 1)]
+    left_places = {idx for idx in range(total) if idx % ncol == 0}
+    bottom_places = {idx for idx in range(total) if idx >= ncol * (nrow - 1)}
     # the last grid row may be incomplete; for the columns it does not cover,
     # the bottom-most plot lives in the penultimate row.
     last_row_count = total - ncol * (nrow - 1)
     if nrow >= 2 and last_row_count < ncol:
-        bottom_places.extend(ncol * (nrow - 2) + col for col in range(last_row_count, ncol))
+        bottom_places.update(ncol * (nrow - 2) + col for col in range(last_row_count, ncol))
+    return frozenset(left_places), frozenset(bottom_places)
+
+
+def _share_labels(plot, i: int, keys: Sequence[str], ncol: int | None) -> SupPlotsSpec:
+    left_places, bottom_places = _grid_places(len(keys), ncol)
     if i not in bottom_places:  # remove x axis title except for bottom row
         plot = plot + theme(axis_title_x=element_blank())
     if i not in left_places:  # remove y axis title except for left column
@@ -310,17 +316,7 @@ def _share_labels(plot, i: int, keys: Sequence[str], ncol: int | None) -> SupPlo
 def _share_axis(
     plot, i: int, keys: Sequence[str], ncol: int | None, axis_type: Literal["axis", "arrow"]
 ) -> SupPlotsSpec:
-    total = len(keys)
-    if ncol is None:
-        ncol = len(keys)
-    nrow = ceil(total / ncol)
-    left_places = [i for i in range(total) if i % ncol == 0]
-    bottom_places = [i for i in range(total) if i >= ncol * (nrow - 1)]
-    # the last grid row may be incomplete; for the columns it does not cover,
-    # the bottom-most plot lives in the penultimate row.
-    last_row_count = total - ncol * (nrow - 1)
-    if nrow >= 2 and last_row_count < ncol:
-        bottom_places.extend(ncol * (nrow - 2) + col for col in range(last_row_count, ncol))
+    left_places, bottom_places = _grid_places(len(keys), ncol)
 
     if axis_type == "axis":
         if i not in bottom_places:  # remove x axis title except for bottom row
@@ -347,17 +343,7 @@ def _share_axis(
 
 
 def _share_ticks(plot, i: int, keys: Sequence[str], ncol: int | None) -> SupPlotsSpec:
-    if ncol is None:
-        ncol = len(keys)
-    total = len(keys)
-    nrow = ceil(total / ncol)
-    left_places = [i for i in range(total) if i % ncol == 0]
-    bottom_places = [i for i in range(total) if i >= ncol * (nrow - 1)]
-    # the last grid row may be incomplete; for the columns it does not cover,
-    # the bottom-most plot lives in the penultimate row.
-    last_row_count = total - ncol * (nrow - 1)
-    if nrow >= 2 and last_row_count < ncol:
-        bottom_places.extend(ncol * (nrow - 2) + col for col in range(last_row_count, ncol))
+    left_places, bottom_places = _grid_places(len(keys), ncol)
     if i not in bottom_places:  # remove x axis title except for bottom row
         plot = plot + theme(axis_text_x=element_blank())
     if i not in left_places:  # remove y axis title except for left column

{cellestial-0.48.4 → cellestial-0.49.0}/pyproject.toml

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