lamindb 1.9.1__py3-none-any.whl → 1.10.1__py3-none-any.whl

lamindb/__init__.py

@@ -108,7 +108,7 @@ Backwards compatibility.
 
 # ruff: noqa: I001
 # denote a release candidate for 0.1.0 with 0.1rc1, 0.1a1, 0.1b1, etc.
-__version__ = "1.9.1"
+__version__ = "1.10.1"
 
 import warnings
 

lamindb/core/__init__.py

@@ -28,7 +28,6 @@ Modules:
 .. autosummary::
    :toctree: .
 
-   datasets
    storage
    logger
 
@@ -38,7 +37,8 @@ from lamin_utils import logger
 from lamin_utils._inspect import InspectResult
 
 from .. import errors as exceptions
-from . import datasets, loaders, subsettings, types
+from ..examples import datasets  # backward compat
+from . import loaders, subsettings, types
 from ._context import Context
 from ._mapped_collection import MappedCollection
 from ._settings import Settings

lamindb/core/storage/__init__.py

@@ -13,12 +13,13 @@ Array accessors.
    :toctree: .
 
    AnnDataAccessor
+   SpatialDataAccessor
    BackedAccessor
 """
 
 from lamindb_setup.core.upath import LocalPathClasses, UPath, infer_filesystem
 
-from ._backed_access import AnnDataAccessor, BackedAccessor
+from ._backed_access import AnnDataAccessor, BackedAccessor, SpatialDataAccessor
 from ._tiledbsoma import save_tiledbsoma_experiment
 from ._valid_suffixes import VALID_SUFFIXES
 from .objects import infer_suffix, write_to_disk

lamindb/core/storage/_anndata_accessor.py

@@ -340,6 +340,12 @@ if ZARR_INSTALLED:
                 ds = sparse_dataset(elem)
                 return _subset_sparse(ds, indices)
             else:
+                indices = tuple(
+                    idim.tolist()
+                    if isinstance(idim, np.ndarray) and idim.dtype == "bool"
+                    else idim
+                    for idim in indices
+                )
                 return read_elem_partial(elem, indices=indices)
 
     # this is needed because accessing zarr.Group.keys() directly is very slow
@@ -353,7 +359,16 @@ if ZARR_INSTALLED:
         attrs_keys: dict[str, list] = {}
         obs_var_arrays = []
 
-        for path in paths:
+        prefix = storage.path
+        if prefix == "":
+            paths_iter = (path for path in paths)
+        else:
+            prefix += "/"
+            paths_iter = (
+                path.removeprefix(prefix) for path in paths if path.startswith(prefix)
+            )
+
+        for path in paths_iter:
             if path in (".zattrs", ".zgroup"):
                 continue
             parts = path.split("/")

lamindb/core/storage/_backed_access.py

@@ -9,6 +9,7 @@ from anndata._io.specs.registry import get_spec
 from ._anndata_accessor import AnnDataAccessor, StorageType, registry
 from ._polars_lazy_df import POLARS_SUFFIXES, _open_polars_lazy_df
 from ._pyarrow_dataset import PYARROW_SUFFIXES, _open_pyarrow_dataset
+from ._spatialdata_accessor import SpatialDataAccessor
 from ._tiledbsoma import _open_tiledbsoma
 from .paths import filepath_from_artifact
 
@@ -80,6 +81,7 @@ def backed_access(
     **kwargs,
 ) -> (
     AnnDataAccessor
+    | SpatialDataAccessor
     | BackedAccessor
     | SOMACollection
     | SOMAExperiment
@@ -110,6 +112,8 @@ def backed_access(
         conn, storage = registry.open("h5py", objectpath, mode=mode, **kwargs)
     elif suffix == ".zarr":
         conn, storage = registry.open("zarr", objectpath, mode=mode, **kwargs)
+        if "spatialdata_attrs" in storage.attrs:
+            return SpatialDataAccessor(storage, name)
     elif len(df_suffixes := _flat_suffixes(objectpath)) == 1 and (
         df_suffix := df_suffixes.pop()
     ) in set(PYARROW_SUFFIXES).union(POLARS_SUFFIXES):

lamindb/core/storage/_spatialdata_accessor.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from ._anndata_accessor import AnnDataAccessor
+
+if TYPE_CHECKING:
+    from zarr import Group
+
+
+class _TablesAccessor:
+    def __init__(self, tables: Group):
+        self._tables = tables
+
+    def __getitem__(self, key: str) -> AnnDataAccessor:
+        return AnnDataAccessor(connection=None, storage=self._tables[key], filename=key)
+
+    def keys(self) -> list[str]:
+        return list(self._tables.keys())
+
+    def __repr__(self) -> str:
+        """Description of the _TablesAccessor object."""
+        descr = (
+            f"Accessor for the SpatialData attribute tables\n  with keys: {self.keys()}"
+        )
+        return descr
+
+
+class SpatialDataAccessor:
+    """Cloud-backed SpatialData.
+
+    For now only allows to access `tables`.
+    """
+
+    def __init__(self, storage: Group, name: str):
+        self.storage = storage
+        self._name = name
+
+    @cached_property
+    def tables(self) -> _TablesAccessor:
+        """tables of the underlying SpatialData object."""
+        return _TablesAccessor(self.storage["tables"])
+
+    def __repr__(self):
+        """Description of the SpatialDataAccessor object."""
+        descr = (
+            "SpatialDataAccessor object"
+            f"\n  constructed for the SpatialData object {self._name}"
+            f"\n    with tables: {self.tables.keys()}"
+        )
+        return descr

lamindb/examples/__init__.py

@@ -3,27 +3,12 @@
 .. autosummary::
    :toctree: .
 
-   ingest_mini_immuno_datasets
    schemas
+   datasets
    cellxgene
+   croissant
 
 """
 
-from . import schemas
+from . import croissant, datasets, schemas
 from .cellxgene import _cellxgene
-
-
-def ingest_mini_immuno_datasets():
-    """Ingest mini immuno datasets.
-
-    .. literalinclude:: scripts/ingest_mini_immuno_datasets.py
-        :language: python
-    """
-    import sys
-    from pathlib import Path
-
-    docs_path = Path(__file__).parent.parent.parent / "docs" / "scripts"
-    if str(docs_path) not in sys.path:
-        sys.path.append(str(docs_path))
-
-    import ingest_mini_immuno_datasets  # noqa

lamindb/examples/cellxgene/_cellxgene.py

@@ -1,12 +1,16 @@
-from typing import Collection, Literal, NamedTuple
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Collection, Literal, NamedTuple
 
 import pandas as pd
 from lamindb_setup.core.upath import UPath
 
-from lamindb.base.types import FieldAttr
-from lamindb.models import Feature, Schema, SQLRecord, ULabel
 from lamindb.models._from_values import _format_values
 
+if TYPE_CHECKING:
+    from lamindb.base.types import FieldAttr
+    from lamindb.models import Schema, SQLRecord
+
 CELLxGENESchemaVersions = Literal["4.0.0", "5.0.0", "5.1.0", "5.2.0", "5.3.0"]
 FieldType = Literal["ontology_id", "name"]
 
@@ -25,6 +29,8 @@ def save_cxg_defaults() -> None:
     """
     import bionty as bt
 
+    from lamindb.models import ULabel
+
     # "normal" in Disease
     normal = bt.Phenotype.from_source(
         ontology_id="PATO:0000461",
@@ -135,6 +141,8 @@ def get_cxg_schema(
     """
     import bionty as bt
 
+    from lamindb.models import Feature, Schema, ULabel
+
     class CategorySpec(NamedTuple):
         field: str | FieldAttr
         default: str | None

lamindb/examples/croissant/__init__.py

@@ -0,0 +1,44 @@
+"""Example Croissant files.
+
+Examples for MLCommons Croissant files, which are used to store metadata about datasets.
+"""
+
+import json
+from pathlib import Path
+
+
+def mini_immuno(n_files: int = 1) -> list[Path]:
+    """Return paths to the mini immuno dataset and its metadata as a Croissant file.
+
+    Args:
+        n_files: Number of files inside the croissant file. Default is 1.
+    """
+    from ..datasets import file_mini_csv
+    from ..datasets.mini_immuno import get_dataset1
+
+    adata = get_dataset1(otype="AnnData")
+    dataset1_path = Path("mini_immuno.anndata.zarr")
+    adata.write_zarr(dataset1_path)
+    orig_croissant_path = (
+        Path(__file__).parent / "mini_immuno.anndata.zarr_metadata.json"
+    )
+    with open(orig_croissant_path, encoding="utf-8") as f:
+        data = json.load(f)
+    if n_files == 2:
+        dataset2_path = file_mini_csv()
+        data["distribution"].append(
+            {
+                "@type": "sc:FileObject",
+                "@id": "mini.csv",
+                "name": "mini.csv",
+                "encodingFormat": "text/csv",
+            }
+        )
+    croissant_path = Path("mini_immuno.anndata.zarr_metadata.json")
+    with open(croissant_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    result: list[Path] = [croissant_path, dataset1_path]
+    if n_files == 1:
+        return result
+    result.append(dataset2_path)
+    return result

lamindb/examples/croissant/mini_immuno.anndata.zarr_metadata.json

@@ -0,0 +1,73 @@
+{
+  "@context": {
+    "@vocab": "https://schema.org/",
+    "cr": "https://mlcommons.org/croissant/",
+    "ml": "http://ml-schema.org/",
+    "sc": "https://schema.org/",
+    "dct": "http://purl.org/dc/terms/",
+    "data": "https://mlcommons.org/croissant/data/",
+    "rai": "https://mlcommons.org/croissant/rai/",
+    "format": "https://mlcommons.org/croissant/format/",
+    "citeAs": "https://mlcommons.org/croissant/citeAs/",
+    "conformsTo": "https://mlcommons.org/croissant/conformsTo/",
+    "@language": "en",
+    "repeated": "https://mlcommons.org/croissant/repeated/",
+    "field": "https://mlcommons.org/croissant/field/",
+    "examples": "https://mlcommons.org/croissant/examples/",
+    "recordSet": "https://mlcommons.org/croissant/recordSet/",
+    "fileObject": "https://mlcommons.org/croissant/fileObject/",
+    "fileSet": "https://mlcommons.org/croissant/fileSet/",
+    "source": "https://mlcommons.org/croissant/source/",
+    "references": "https://mlcommons.org/croissant/references/",
+    "key": "https://mlcommons.org/croissant/key/",
+    "parentField": "https://mlcommons.org/croissant/parentField/",
+    "isLiveDataset": "https://mlcommons.org/croissant/isLiveDataset/",
+    "separator": "https://mlcommons.org/croissant/separator/",
+    "extract": "https://mlcommons.org/croissant/extract/",
+    "subField": "https://mlcommons.org/croissant/subField/",
+    "regex": "https://mlcommons.org/croissant/regex/",
+    "column": "https://mlcommons.org/croissant/column/",
+    "path": "https://mlcommons.org/croissant/path/",
+    "fileProperty": "https://mlcommons.org/croissant/fileProperty/",
+    "md5": "https://mlcommons.org/croissant/md5/",
+    "jsonPath": "https://mlcommons.org/croissant/jsonPath/",
+    "transform": "https://mlcommons.org/croissant/transform/",
+    "replace": "https://mlcommons.org/croissant/replace/",
+    "dataType": "https://mlcommons.org/croissant/dataType/",
+    "includes": "https://mlcommons.org/croissant/includes/",
+    "excludes": "https://mlcommons.org/croissant/excludes/"
+  },
+  "@type": "Dataset",
+  "name": "Mini immuno dataset",
+  "description": "A few samples from the immunology dataset",
+  "url": "https://lamin.ai/laminlabs/lamindata/artifact/tCUkRcaEjTjhtozp0000",
+  "creator": {
+    "@type": "Person",
+    "name": "falexwolf"
+  },
+  "dateCreated": "2025-07-16",
+  "cr:projectName": "Mini Immuno Project",
+  "datePublished": "2025-07-16",
+  "version": "1.0",
+  "license": "https://creativecommons.org/licenses/by/4.0/",
+  "citation": "Please cite this dataset as: mini immuno (2025)",
+  "encodingFormat": "zarr",
+  "distribution": [
+    {
+      "@type": "cr:FileSet",
+      "@id": "mini_immuno.anndata.zarr",
+      "containedIn": {
+        "@id": "directory"
+      },
+      "encodingFormat": "zarr"
+    }
+  ],
+  "cr:recordSet": [
+    {
+      "@type": "cr:RecordSet",
+      "@id": "#samples",
+      "name": "samples",
+      "description": "my sample"
+    }
+  ]
+}

lamindb/{core → examples}/datasets/__init__.py

@@ -1,4 +1,4 @@
-"""Test datasets.
+"""Example datasets.
 
 The mini immuno dataset.
 
@@ -36,11 +36,12 @@ Directories.
    dir_scrnaseq_cellranger
    dir_iris_images
 
-Dataframe, AnnData, MuData.
+Dictionary, Dataframe, AnnData, MuData, SpatialData.
 
 .. autosummary::
    :toctree: .
 
+   dict_cxg_uns
    df_iris
    df_iris_in_meter
    df_iris_in_meter_study1
@@ -55,6 +56,7 @@ Dataframe, AnnData, MuData.
    mudata_papalexi21_subset
    schmidt22_crispra_gws_IFNG
    schmidt22_perturbseq
+   spatialdata_blobs
 
 Other.
 
@@ -76,6 +78,7 @@ from ._core import (
     df_iris_in_meter,
     df_iris_in_meter_study1,
     df_iris_in_meter_study2,
+    dict_cxg_uns,
     dir_iris_images,
     dir_scrnaseq_cellranger,
     file_bam,

lamindb/{core → examples}/datasets/_core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from urllib.request import urlretrieve
 
 import anndata as ad
@@ -418,6 +418,38 @@ def mudata_papalexi21_subset() -> MuData:  # pragma: no cover
     return mdata
 
 
+def dict_cxg_uns() -> dict[str, Any]:
+    """An example CELLxGENE AnnData `.uns` dictionary."""
+    uns = {
+        "organism_ontology_term_id": "NCBITaxon:9606",
+        "spatial": {
+            "is_single": True,
+            "library_1": {  # Dynamic library_id key
+                "images": {
+                    "fullres": "path/to/fullres.jpg",
+                    "hires": "path/to/hires.jpg",
+                },
+                "scalefactors": {
+                    "spot_diameter_fullres": 89.43,
+                    "tissue_hires_scalef": 0.177,
+                },
+            },
+            "library_2": {  # Another dynamic library_id key
+                "images": {
+                    "fullres": "path/to/fullres_2.jpg",
+                    "hires": "path/to/hires_2.jpg",
+                },
+                "scalefactors": {
+                    "spot_diameter_fullres": 120.34,
+                    "tissue_hires_scalef": 0.355,
+                },
+            },
+        },
+    }
+
+    return uns
+
+
 def df_iris() -> pd.DataFrame:
     """The iris collection as in sklearn.
 

lamindb/{core → examples}/datasets/mini_immuno.py

@@ -1,16 +1,20 @@
-"""The mini immuno dataset.
+"""The two "mini immuno" datasets.
 
 .. autosummary::
    :toctree: .
 
-   define_features_labels
    get_dataset1
    get_dataset2
+   define_features_labels
+   define_mini_immuno_schema_flexible
+   save_mini_immuno_datasets
 
 """
 
 from __future__ import annotations
 
+import sys
+from pathlib import Path
 from typing import TYPE_CHECKING, Literal
 
 import anndata as ad
@@ -26,9 +30,6 @@ def define_features_labels() -> None:
     .. literalinclude:: scripts/define_mini_immuno_features_labels.py
         :language: python
     """
-    import sys
-    from pathlib import Path
-
     docs_path = Path(__file__).parent.parent.parent.parent / "docs" / "scripts"
     if str(docs_path) not in sys.path:
         sys.path.append(str(docs_path))
@@ -42,9 +43,6 @@ def define_mini_immuno_schema_flexible() -> Schema:
     .. literalinclude:: scripts/define_mini_immuno_schema_flexible.py
         :language: python
     """
-    import sys
-    from pathlib import Path
-
     from lamindb.models import Schema
 
     docs_path = Path(__file__).parent.parent.parent.parent / "docs" / "scripts"
@@ -57,6 +55,19 @@ def define_mini_immuno_schema_flexible() -> Schema:
     return Schema.get(name="Mini immuno schema")
 
 
+def save_mini_immuno_datasets():
+    """Save the two "mini immuno" datasets.
+
+    .. literalinclude:: scripts/save_mini_immuno_datasets.py
+        :language: python
+    """
+    docs_path = Path(__file__).parent.parent.parent.parent / "docs" / "scripts"
+    if str(docs_path) not in sys.path:
+        sys.path.append(str(docs_path))
+
+    import save_mini_immuno_datasets  # noqa
+
+
 def get_dataset1(
     otype: Literal["DataFrame", "AnnData"] = "DataFrame",
     gene_symbols_in_index: bool = False,

lamindb/examples/schemas/_anndata.py

@@ -1,25 +1,35 @@
-from ... import Schema
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ... import Schema
 
 
 def anndata_ensembl_gene_ids_and_valid_features_in_obs() -> Schema:
-    """Return a schema for an AnnData with Ensembl gene IDs and valid features in obs.
+    """An `AnnData` schema validating Ensembl gene IDs and valid features in obs.
 
     .. literalinclude:: scripts/define_schema_anndata_ensembl_gene_ids_and_valid_features_in_obs.py
         :language: python
     """
-    import subprocess
-    from pathlib import Path
+    from ... import Schema
 
     docs_path = Path(__file__).parent.parent.parent.parent / "docs" / "scripts"
-    subprocess.run(
-        [
-            "python",
-            str(
-                docs_path
-                / "define_schema_anndata_ensembl_gene_ids_and_valid_features_in_obs.py"
-            ),
-        ],
-        check=True,
-    )
-
-    return Schema.get(name="anndata_ensembl_gene_ids_and_valid_features_in_obs")
+    if str(docs_path) not in sys.path:
+        sys.path.append(str(docs_path))
+
+    try:
+        return Schema.get(name="anndata_ensembl_gene_ids_and_valid_features_in_obs")
+    except Schema.DoesNotExist:
+        import define_schema_anndata_ensembl_gene_ids_and_valid_features_in_obs  # noqa
+
+        try:
+            return Schema.get(name="anndata_ensembl_gene_ids_and_valid_features_in_obs")
+        except Schema.DoesNotExist:
+            importlib.reload(
+                define_schema_anndata_ensembl_gene_ids_and_valid_features_in_obs
+            )
+            return Schema.get(name="anndata_ensembl_gene_ids_and_valid_features_in_obs")

lamindb/examples/schemas/_simple.py

@@ -1,19 +1,33 @@
-from ... import Schema
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ... import Schema
 
 
 def valid_features() -> Schema:
-    """Return a schema for an AnnData with Ensembl gene IDs and valid features in obs.
+    """A `DataFrame` schema that validates that columns map on existing features.
 
-    .. literalinclude:: scripts/define_schema_anndata_ensembl_gene_ids_and_valid_features_in_obs.py
+    .. literalinclude:: scripts/define_valid_features.py
         :language: python
     """
-    import subprocess
-    from pathlib import Path
+    from ... import Schema
 
     docs_path = Path(__file__).parent.parent.parent.parent / "docs" / "scripts"
-    subprocess.run(
-        ["python", str(docs_path / "define_valid_features.py")],
-        check=True,
-    )
+    if str(docs_path) not in sys.path:
+        sys.path.append(str(docs_path))
+
+    try:
+        return Schema.get(name="valid_features")
+    except Schema.DoesNotExist:
+        try:
+            import define_valid_features  # noqa
 
-    return Schema.get(name="valid_features")
+            return Schema.get(name="valid_features")
+        except Schema.DoesNotExist:
+            importlib.reload(define_valid_features)
+            return Schema.get(name="valid_features")

lamindb/integrations/__init__.py

@@ -5,8 +5,10 @@
 
    save_vitessce_config
    save_tiledbsoma_experiment
+   curate_from_croissant
 """
 
 from lamindb.core.storage import save_tiledbsoma_experiment
 
+from ._croissant import curate_from_croissant
 from ._vitessce import save_vitessce_config