cellestial 0.58.2__tar.gz → 0.60.0__tar.gz

{cellestial-0.58.2 → cellestial-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellestial
-Version: 0.58.2
+Version: 0.60.0
 Summary: Interactive single-cell and spatial omics visualization library
 License-Expression: Apache-2.0
 License-File: LICENSE

{cellestial-0.58.2 → cellestial-0.60.0}/cellestial/complex/annotated_heatmap.py

@@ -26,12 +26,14 @@ from lets_plot import (
     scale_y_continuous,
     theme,
 )
+from mudata import MuData
 
 from cellestial.frames import build_frame
 from cellestial.single.heatmap.utilities import _scale_values
 from cellestial.themes import _THEME_HEATMAP
 from cellestial.util import _fill_gradient, _get_dendrogram, _warn
 from cellestial.util.errors import _unsupported_data_type
+from cellestial.util.utilities import _modality_source
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -330,10 +332,11 @@ def _dendrogram_panel(
 
 
 def annotated_heatmap(
-    data: AnnData,
+    data: AnnData | MuData,
     keys: Sequence[str],
     group_by: str | None = None,
     *,
+    modality: str | None = None,
     column_annotations: str | Sequence[str] | None = None,
     row_annotations: str | Sequence[str] | None = None,
     annotation_colors: Mapping[str, AnnotationColors] | None = None,
@@ -359,7 +362,7 @@ def annotated_heatmap(
     color_low: str = "#0000ff",
     color_mid: str = "#ffffff",
     color_high: str = "#ff0000",
-    mid_point: Literal["mean", "median", "mid"] | float = "mid",
+    midpoint: Literal["mean", "median", "mid"] | float = "mid",
     max_rows: int | None = 1000,
     value_column: str = "value",
     variable_column: str = "variable",
@@ -377,6 +380,10 @@ def annotated_heatmap(
         The AnnData object of the single cell data.
     keys : Sequence[str]
         Variable keys to include, placed on the x-axis.
+    modality : str | None, default=None
+        Which modality's stored analysis results to use when `markers` or
+        `dendrogram` is enabled. Required for a multimodal object holding more
+        than one modality, and not accepted otherwise.
     group_by : str | None, default=None
         The observation key to group the rows by. When `None`, rows keep their
         original order and no group separators are drawn.
@@ -446,7 +453,7 @@ def annotated_heatmap(
         Color for mid values in the heatmap gradient.
     color_high : str, default='#ff0000'
         Color for high values in the heatmap gradient.
-    mid_point : {'mean', 'median', 'mid'} | float, default='mid'
+    midpoint : {'mean', 'median', 'mid'} | float, default='mid'
         Midpoint for the heatmap color gradient.
     max_rows : int | None, default=1000
         Cap the number of plotted rows by averaging contiguous observations
@@ -495,7 +502,7 @@ def annotated_heatmap(
 
         import cellestial as cl
 
-        data = cl.datasets.pbmc3k(cache_directory="data")
+        data = cl.datasets.pbmc3k()
         markers = ["C1QA", "PSAP", "CD79A", "CD79B", "CST3", "LYZ"]
 
         cl.annotated_heatmap(
@@ -507,8 +514,8 @@ def annotated_heatmap(
             scale_axis=0,
         )
     """
-    if not isinstance(data, AnnData):
-        raise _unsupported_data_type(data, AnnData)
+    if not isinstance(data, (AnnData, MuData)):
+        raise _unsupported_data_type(data, AnnData, MuData)
 
     keys = list(keys)
     column_annotations = _as_list(column_annotations)
@@ -524,7 +531,7 @@ def annotated_heatmap(
     if dendrogram:
         assert group_by is not None  # guaranteed by the guard above
         dendrogram_order, dendrogram_paths = _get_dendrogram(
-            data, group_by, use_key=dendrogram_key
+            *_modality_source(data, modality, group_by), use_key=dendrogram_key
         )
     else:
         dendrogram_order, dendrogram_paths = None, None
@@ -608,7 +615,7 @@ def annotated_heatmap(
             color_low=color_low,
             color_mid=color_mid,
             color_high=color_high,
-            mid_point=mid_point,
+            midpoint=midpoint,
         )
         + key_scale
         + observation_scale

{cellestial-0.58.2 → cellestial-0.60.0}/cellestial/datasets/__init__.py

@@ -5,6 +5,7 @@ from cellestial.datasets.datasets import (
     human_lymph_node,
     pancreas,
     pbmc3k,
+    pbmc_cite,
 )
 
 __all__ = [
@@ -14,4 +15,5 @@ __all__ = [
     "human_lymph_node",
     "pancreas",
     "pbmc3k",
+    "pbmc_cite",
 ]

{cellestial-0.58.2 → cellestial-0.60.0}/cellestial/datasets/datasets.py

@@ -2,8 +2,10 @@ import re
 import shutil
 from os import PathLike
 from pathlib import Path
+from typing import cast
 
 from anndata import AnnData, read_h5ad
+from mudata import MuData
 
 _GLOBAL_CACHE = Path.home() / ".cache" / "cellestial" / "datasets"
 
@@ -81,11 +83,14 @@ def pbmc3k(
     OSError
         If the downloaded file size does not match the expected size.
     """
-    return from_url(
-        "https://huggingface.co/datasets/datavil/pbmc3k/resolve/main/pbmc3k_pped.h5ad",
-        cache_directory=cache_directory,
-        use_cache=use_cache,
-        bring=bring,
+    return cast(
+        "AnnData",
+        from_url(
+            "https://huggingface.co/datasets/datavil/pbmc3k/resolve/main/pbmc3k_pped.h5ad",
+            cache_directory=cache_directory,
+            use_cache=use_cache,
+            bring=bring,
+        ),
     )
 
 
@@ -120,14 +125,70 @@ def pancreas(
     OSError
         If the downloaded file size does not match the expected size.
     """
-    return from_url(
-        "https://huggingface.co/datasets/datavil/pancreas/resolve/main/endocrinogenesis_day15_pped.h5ad",
-        cache_directory=cache_directory,
-        use_cache=use_cache,
-        bring=bring,
+    return cast(
+        "AnnData",
+        from_url(
+            "https://huggingface.co/datasets/datavil/pancreas/resolve/main/endocrinogenesis_day15_pped.h5ad",
+            cache_directory=cache_directory,
+            use_cache=use_cache,
+            bring=bring,
+        ),
     )
 
 
+def pbmc_cite(
+    cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
+    *,
+    use_cache: bool = True,
+    bring: bool = True,
+) -> MuData:
+    """
+    Download and load a small multimodal CITE-seq PBMC dataset.
+
+    Parameters
+    ----------
+    cache_directory : str | Path | PathLike
+        Directory where the `.h5mu` file is cached.
+    use_cache : bool, default=True
+        If True, load from the cached file when present. If False, remove any
+        existing cached file and re-download.
+    bring : bool, default=True
+        If True and `cache_directory` is not the default global cache, copy the
+        file from the global cache when it already exists there. Set to False
+        to disable this behavior.
+
+    Returns
+    -------
+    MuData
+        411 cells with paired gene expression (`rna`) and surface protein
+        (`prot`) modalities, carrying joint WNN and MOFA embeddings.
+
+    Raises
+    ------
+    OSError
+        If the downloaded file size does not match the expected size.
+    """
+    return cast(
+        "MuData",
+        from_url(
+            "https://github.com/gtca/h5xx-datasets/raw/main/datasets/minipbcite.h5mu",
+            cache_directory=cache_directory,
+            use_cache=use_cache,
+            bring=bring,
+            extension=".h5mu",
+        ),
+    )
+
+
+def _read_dataset(path: Path) -> AnnData | MuData:
+    """Read a cached dataset, dispatching on the file extension."""
+    if path.suffix == ".h5mu":
+        from mudata import read_h5mu
+
+        return read_h5mu(path)
+    return read_h5ad(path)
+
+
 def from_url(
     url: str,
     *,
@@ -135,14 +196,15 @@ def from_url(
     cache_directory: str | Path | PathLike = _GLOBAL_CACHE,
     use_cache: bool = True,
     bring: bool = True,
-) -> AnnData:
+    extension: str = ".h5ad",
+) -> AnnData | MuData:
     """
-    Download and load an `.h5ad` dataset from a direct HTTP(S) URL.
+    Download and load a dataset from a direct HTTP(S) URL.
 
     Parameters
     ----------
     url : str
-        Direct URL to a downloadable `.h5ad` file.
+        Direct URL to a downloadable `.h5ad` or `.h5mu` file.
     name : str, optional
         Name for the cached file (without extension). If omitted, the cache
         filename is derived from the URL's last path segment.
@@ -155,10 +217,13 @@ def from_url(
         If True and `cache_directory` is not the default global cache, copy the
         file from the global cache when it already exists there. Set to False
         to disable this behavior.
+    extension : str, default='.h5ad'
+        File extension used when `name` is given, and the format the downloaded
+        file is read as. Pass '.h5mu' for a multimodal dataset.
 
     Returns
     -------
-    AnnData
+    AnnData | MuData
         The downloaded dataset.
 
     Raises
@@ -170,7 +235,7 @@ def from_url(
 
     Notes
     -----
-    Generic loader for any host that serves an AnnData `.h5ad` file at a
+    Generic loader for any host that serves an `.h5ad` or `.h5mu` file at a
     stable URL (CELLxGENE, Zenodo, Figshare, S3 buckets, etc.).
     """
     from urllib.parse import urlparse
@@ -179,7 +244,7 @@ def from_url(
     from tqdm import tqdm
 
     if name is not None:
-        filename = f"{name}.h5ad"
+        filename = f"{name}{extension}"
     else:
         filename = Path(urlparse(url).path).name
         if not filename:
@@ -189,7 +254,7 @@ def from_url(
     cache_file = _resolve_cache_file(cache_directory, filename, use_cache=use_cache, bring=bring)
 
     if cache_file.exists():
-        return read_h5ad(cache_file)
+        return _read_dataset(cache_file)
 
     print(f"No cache at {cache_file} !")
     print(f"Downloading from {url} ...")
@@ -227,7 +292,7 @@ def from_url(
 
     print(f"Saved to {cache_file}")
 
-    return read_h5ad(cache_file)
+    return _read_dataset(cache_file)
 
 
 def from_cellxgene(
@@ -291,12 +356,15 @@ def from_cellxgene(
         else f"https://datasets.cellxgene.cziscience.com/{uuid}.h5ad"
     )
 
-    return from_url(
-        url,
-        name=name or uuid,
-        cache_directory=cache_directory,
-        use_cache=use_cache,
-        bring=bring,
+    return cast(
+        "AnnData",
+        from_url(
+            url,
+            name=name or uuid,
+            cache_directory=cache_directory,
+            use_cache=use_cache,
+            bring=bring,
+        ),
     )
 
 
@@ -375,9 +443,12 @@ def human_lymph_node(
     OSError
         If the downloaded file size does not match the expected size.
     """
-    return from_url(
-        "https://huggingface.co/datasets/datavil/human_lymph_node/resolve/main/V1_Human_Lymph_Node_pped.h5ad",
-        cache_directory=cache_directory,
-        use_cache=use_cache,
-        bring=bring,
+    return cast(
+        "AnnData",
+        from_url(
+            "https://huggingface.co/datasets/datavil/human_lymph_node/resolve/main/V1_Human_Lymph_Node_pped.h5ad",
+            cache_directory=cache_directory,
+            use_cache=use_cache,
+            bring=bring,
+        ),
     )

{cellestial-0.58.2 → cellestial-0.60.0}/cellestial/frames/__init__.py

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