Replace axis_name with coordinate_space in spatial dataframes (#237)

Directly use the `CoordinateSpace` class instead of a tuple of "axis names" in the creation methods for the `PointCloudDataFrame` and `GeometryDataFrame` classes.
single-cell-data · Oct 16, 2024 · aba232b · aba232b
1 parent 9a31492
commit aba232b
Showing 1 changed file with 17 additions and 29 deletions.
diff --git a/python-spec/src/somacore/spatial.py b/python-spec/src/somacore/spatial.py
@@ -56,8 +56,11 @@ def create(
         uri: str,
         *,
         schema: pa.Schema,
-        index_column_names: Sequence[str] = (options.SOMA_JOINID, "x", "y"),
-        axis_names: Sequence[str] = ("x", "y"),
+        coordinate_space: Union[Sequence[str], coordinates.CoordinateSpace] = (
+            "x",
+            "y",
+        ),
+        index_column_names: Optional[Sequence[str]] = None,
         domain: Optional[Sequence[Optional[Tuple[Any, Any]]]] = None,
         platform_config: Optional[options.PlatformConfig] = None,
         context: Optional[Any] = None,
@@ -77,12 +80,13 @@ def create(
                 must define all columns, including columns to be named as index
                 columns.  If the schema includes types unsupported by the SOMA
                 implementation, an error will be raised.
+            coordinate_space: Either the coordinate space or the axis names for the
+                coordinate space the point cloud is defined on.
             index_column_names: A list of column names to use as user-defined index
-                columns (e.g., ``['x', 'y']``). All named columns must exist in the
-                schema, and at least one index column name is required.
-            axis_names: An ordered list of axis column names that correspond to the
-                names of axes of the the coordinate space the points are defined on.
-                Must be the name of index columns.
+                columns (e.g., ``['x', 'y']``). Must include the axis names for all
+                axes in the coordinate space. May include the ``soma_joinid``.
+                Defaults to ``None`` which sets the index column names to be the
+                ``soma_joinid`` followed by the axis names for the coordinate space.
             domain: An optional sequence of tuples specifying the domain of each
                 index column. Each tuple should be a pair consisting of the minimum
                 and maximum values storable in the index column. If omitted entirely,
@@ -242,15 +246,6 @@ def coordinate_space(self, value: coordinates.CoordinateSpace) -> None:
         """
         raise NotImplementedError()
 
-    @property
-    @abc.abstractmethod
-    def axis_names(self) -> Tuple[str, ...]:
-        """The names of the axes of the coordinate space the data is defined on.
-
-        Lifecycle: experimental
-        """
-        raise NotImplementedError()
-
     @property
     @abc.abstractmethod
     def domain(self) -> Tuple[Tuple[Any, Any], ...]:
@@ -285,11 +280,14 @@ def create(
         uri: str,
         *,
         schema: pa.Schema,
+        coordinate_space: Union[Sequence[str], coordinates.CoordinateSpace] = (
+            "x",
+            "y",
+        ),
         index_column_names: Sequence[str] = (
             options.SOMA_JOINID,
             options.SOMA_GEOMETRY,
         ),
-        axis_names: Sequence[str] = ("x", "y"),
         domain: Optional[Sequence[Optional[Tuple[Any, Any]]]] = None,
         platform_config: Optional[options.PlatformConfig] = None,
         context: Optional[Any] = None,
@@ -311,13 +309,12 @@ def create(
                 must define all columns, including columns to be named as index
                 columns.  If the schema includes types unsupported by the SOMA
                 implementation, an error will be raised.
+            coordinate_space: Either the coordinate space or the axis names for the
+                coordinate space the point cloud is defined on.
             index_column_names: A list of column names to use as user-defined
                 index columns (e.g., ``['cell_type', 'tissue_type']``).
                 All named columns must exist in the schema, and at least one
                 index column name is required.
-            axis_names: An ordered list of axis column names that correspond to the
-                names of the axes of the coordinate space the geometries are defined
-                on.
             domain: An optional sequence of tuples specifying the domain of each
                 index column. Two tuples must be provided for the ``soma_geometry``
                 column which store the width followed by the height. Each tuple should
@@ -461,15 +458,6 @@ def index_column_names(self) -> Tuple[str, ...]:
         """
         raise NotImplementedError()
 
-    @property
-    @abc.abstractmethod
-    def axis_names(self) -> Tuple[str, ...]:
-        """The names of the axes of the coordinate space the data is defined on.
-
-        Lifecycle: experimental
-        """
-        raise NotImplementedError()
-
     @property
     @abc.abstractmethod
     def coordinate_space(self) -> coordinates.CoordinateSpace: