Add Visium ingestor and sample spatial notebook (#3123)

* Add ingestor script and sample spatial notebook
* Explicitly set coord space after transform for tissue and loc

apis/python/src/tiledbsoma/__init__.py

@@ -175,7 +175,7 @@
 )
 from ._indexer import IntIndexer, tiledbsoma_build_index
 from ._measurement import Measurement
-from ._multiscale_image import MultiscaleImage
+from ._multiscale_image import ImageProperties, MultiscaleImage
 from ._point_cloud_dataframe import PointCloudDataFrame
 from ._scene import Scene
 from ._sparse_nd_array import SparseNDArray, SparseNDArrayRead
@@ -210,6 +210,7 @@
     "get_SOMA_version",
     "get_storage_engine",
     "IntIndexer",
+    "ImageProperties",
     "Measurement",
     "MultiscaleImage",
     "NotCreateableError",

apis/python/src/tiledbsoma/_multiscale_image.py

@@ -601,7 +601,7 @@ def level_count(self) -> int:
         """
         return len(self._levels)
 
-    def level_properties(self, level: Union[int, str]) -> somacore.ImageProperties:
+    def level_properties(self, level: Union[int, str]) -> ImageProperties:
         """The properties of an image at the specified level.
 
         Lifecycle:

apis/python/src/tiledbsoma/experimental/__init__.py

@@ -0,0 +1,9 @@
+"""Experimental SOMA features
+
+This module is for experimental features. Support for these features
+may be dropped.
+"""
+
+from .ingest import VisiumPaths, from_visium
+
+__all__ = ["from_visium", "VisiumPaths"]

apis/python/src/tiledbsoma/experimental/_util.py

@@ -0,0 +1,56 @@
+# Copyright (c) 2024 The Chan Zuckerberg Initiative Foundation
+# Copyright (c) 2024 TileDB, Inc
+#
+# Licensed under the MIT License.
+from pathlib import Path
+from typing import Tuple, Union
+
+import h5py
+
+from .._exception import SOMAError
+
+
+def _str_to_int(value: str) -> int:
+    if not value.isdigit():
+        raise ValueError("{value} is not an integer.")
+    return int(value)
+
+
+def _read_visium_software_version(
+    gene_expression_path: Union[str, Path]
+) -> Tuple[int, int, int]:
+    with h5py.File(gene_expression_path) as dataset:
+        try:
+            version = dataset.attrs["software_version"]
+        except KeyError as ke:
+            raise SOMAError(
+                f"Unable to read software version from gene expression file "
+                f"{gene_expression_path}."
+            ) from ke
+    if not isinstance(version, str):
+        raise SOMAError(
+            f"Unexpected type {type(version)!r} for software version in gene "
+            f"expression file {gene_expression_path}. Expected a string."
+        )
+    version_prefix = "spaceranger-"
+    if not version.startswith(version_prefix):
+        raise SOMAError(
+            f"Unexpected value {version} for software version in gene expresion "
+            f"file {gene_expression_path}."
+        )
+    version = version[len(version_prefix) :].split(".")
+    if len(version) not in {3, 4}:
+        raise SOMAError(
+            f"Unexpected value {version} for software version in gene expresion "
+            f"file {gene_expression_path}."
+        )
+    try:
+        major = _str_to_int(version[0])
+        minor = _str_to_int(version[1])
+        patch = _str_to_int(version[2])
+    except ValueError:
+        raise SOMAError(
+            f"Unexpected value {version} for software version in gene expresion "
+            f"file {gene_expression_path}."
+        )
+    return (major, minor, patch)