Add new spatial foundational types

pyproject.toml

@@ -22,6 +22,7 @@ dependencies = [
   # Remove this once we can specify a recent pyarrow.
   "pyarrow-hotfix",
   "scipy",
+  "shapely",
   "typing-extensions>=4.1", # For LiteralString (py3.11)
 ]
 requires-python = ">=3.9"
@@ -62,5 +63,5 @@ python_version = 3.9
 
 [[tool.mypy.overrides]]
 # These dependencies do not currently have canonical type stubs.
-module = ["anndata", "pyarrow", "pyarrow_hotfix", "scipy"]
+module = ["anndata", "pyarrow", "pyarrow.compute", "pyarrow_hotfix", "scipy", "shapely"]
 ignore_missing_imports = true

python-spec/requirements-py3.10.txt

@@ -14,6 +14,7 @@ pyarrow-hotfix==0.6
 python-dateutil==2.9.0.post0
 pytz==2024.1
 scipy==1.13.1
+shapely==2.0.4
 six==1.16.0
 typing_extensions==4.12.2
 tzdata==2024.1

python-spec/requirements-py3.11.txt

@@ -12,6 +12,7 @@ pyarrow==16.1.0
 pyarrow-hotfix==0.6
 python-dateutil==2.9.0.post0
 pytz==2024.1
+shapely==2.0.4
 scipy==1.13.1
 six==1.16.0
 typing_extensions==4.12.2

python-spec/requirements-py3.12.txt

@@ -14,6 +14,7 @@ python-dateutil==2.9.0.post0
 pytz==2024.1
 scipy==1.13.1
 setuptools==70.0.0
+shapely==2.0.4
 six==1.16.0
 typing_extensions==4.12.2
 tzdata==2024.1

python-spec/requirements-py3.9.txt

@@ -18,6 +18,7 @@ pytz==2024.1
 rsa==4.7.2
 s3transfer==0.6.0
 scipy==1.13.1
+shapely==2.0.4
 six==1.16.0
 typing_extensions==4.12.2
 tzdata==2024.1

python-spec/src/somacore/__init__.py

@@ -37,6 +37,11 @@
 from .query import AxisColumnNames
 from .query import AxisQuery
 from .query import ExperimentAxisQuery
+from .spatial import GeometryDataFrame
+from .spatial import ImageProperties
+from .spatial import MultiscaleImage
+from .spatial import PointCloud
+from .spatial import SpatialRead
 from .types import ContextBase
 
 try:
@@ -59,8 +64,14 @@
     "ReadIter",
     "SparseNDArray",
     "SparseRead",
+    "SpatialRead",
     "Experiment",
     "Measurement",
+    "ImageProperties",
+    "MultiscaleImage",
+    "SpatialDataFrame",
+    "GeometryDataFrame",
+    "PointCloud",
     "BatchSize",
     "IOfN",
     "ResultOrder",

python-spec/src/somacore/options.py

@@ -11,13 +11,17 @@
 import numpy as np
 import numpy.typing as npt
 import pyarrow as pa
+import shapely
 from typing_extensions import Final, Literal
 
 from . import types
 
 SOMA_JOINID: Final = "soma_joinid"
 """Global constant for the SOMA join ID."""
 
+SOMA_GEOMETRY: Final = "soma_geometry"
+"""Global constant for SOMA spatial geometry type."""
+
 OpenMode = Literal["r", "w"]
 """How to open a SOMA object: read or write."""
 
@@ -177,5 +181,11 @@ class ResultOrder(enum.Enum):
     pa.ChunkedArray,
 ]
 """A single coordinate range for one dimension of a sparse ndarray."""
+
 SparseNDCoords = Sequence[SparseNDCoord]
 """A sequence of coordinate ranges for reading sparse ndarrays."""
+
+SpatialRegion = Union[
+    Sequence[int], Sequence[float], shapely.geometry.base.BaseGeometry
+]
+"""A spatial region used for reading spatial dataframes and multiscale images."""