Add new spatial foundational types (#219)

New classes: * PointCloud: A spatial data frame for point data * GeometryDataFrame: A spatial data for polygon data * MultiscaleImage: An image class that can contain multiple image levels. * ImageProperties: A protocol with the required properties for image levels. * SpatialRead: New dataclass for returning read data with coordinate space information. Co-authored-by: nguyenv <[email protected]> Co-authored-by: Aaron Wolen <[email protected]>
single-cell-data · Sep 26, 2024 · 3d9e34f · 3d9e34f
1 parent d41bbb1
commit 3d9e34f
Show file tree

Hide file tree

Showing 8 changed files with 809 additions and 1 deletion.
diff --git a/pyproject.toml b/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
diff --git a/python-spec/requirements-py3.10.txt b/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
diff --git a/python-spec/requirements-py3.11.txt b/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

diff --git a/python-spec/requirements-py3.12.txt b/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

diff --git a/python-spec/requirements-py3.9.txt b/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
diff --git a/python-spec/src/somacore/__init__.py b/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",

diff --git a/python-spec/src/somacore/options.py b/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."""