Rename PointCloud -> PointCloudDataFrame (#232)

single-cell-data · Sep 30, 2024 · e92ecb4 · e92ecb4
1 parent aff0f0f
commit e92ecb4
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 33 deletions.
diff --git a/python-spec/src/somacore/__init__.py b/python-spec/src/somacore/__init__.py
@@ -41,7 +41,7 @@
 from .spatial import GeometryDataFrame
 from .spatial import ImageProperties
 from .spatial import MultiscaleImage
-from .spatial import PointCloud
+from .spatial import PointCloudDataFrame
 from .spatial import SpatialRead
 from .types import ContextBase
 
@@ -72,7 +72,7 @@
     "ImageProperties",
     "MultiscaleImage",
     "GeometryDataFrame",
-    "PointCloud",
+    "PointCloudDataFrame",
     "BatchSize",
     "IOfN",
     "ResultOrder",

diff --git a/python-spec/src/somacore/ephemeral/collections.py b/python-spec/src/somacore/ephemeral/collections.py
@@ -136,7 +136,7 @@ class Collection(  # type: ignore[misc]  # __eq__ false positive
 
 _BasicAbstractScene = scene.Scene[
     spatial.MultiscaleImage,
-    spatial.PointCloud,
+    spatial.PointCloudDataFrame,
     spatial.GeometryDataFrame,
     base.SOMAObject,
 ]
@@ -200,7 +200,7 @@ def add_multiscale_image(
     ) -> spatial.MultiscaleImage:
         raise NotImplementedError()
 
-    def add_new_point_cloud(
+    def add_new_point_cloud_dataframe(
         self,
         key: str,
         subcollection: Union[str, Sequence[str]],
@@ -212,7 +212,7 @@ def add_new_point_cloud(
         axis_names: Sequence[str] = ("x", "y"),
         domain: Optional[Sequence[Optional[Tuple[Any, Any]]]] = None,
         platform_config: Optional[options.PlatformConfig] = None,
-    ) -> spatial.PointCloud:
+    ) -> spatial.PointCloudDataFrame:
         raise NotImplementedError()
 
     def set_transform_to_geometry_dataframe(
@@ -235,14 +235,14 @@ def set_transform_to_multiscale_image(
     ) -> spatial.MultiscaleImage:
         raise NotImplementedError()
 
-    def set_transform_to_point_cloud(
+    def set_transform_to_point_cloud_dataframe(
         self,
         key: str,
         transform: coordinates.CoordinateTransform,
         *,
         subcollection: Union[str, Sequence[str]] = "obsl",
         coordinate_space: Optional[coordinates.CoordinateSpace] = None,
-    ) -> spatial.PointCloud:
+    ) -> spatial.PointCloudDataFrame:
         raise NotImplementedError()
 
     def get_transform_from_geometry_dataframe(
@@ -259,7 +259,7 @@ def get_transform_from_multiscale_image(
     ) -> coordinates.CoordinateTransform:
         raise NotImplementedError()
 
-    def get_transform_from_point_cloud(
+    def get_transform_from_point_cloud_dataframe(
         self, key: str, *, subcollection: str = "obsl"
     ) -> coordinates.CoordinateTransform:
         raise NotImplementedError()
@@ -278,7 +278,7 @@ def get_transform_to_multiscale_image(
     ) -> coordinates.CoordinateTransform:
         raise NotImplementedError()
 
-    def get_transform_to_point_cloud(
+    def get_transform_to_point_cloud_dataframe(
         self, key: str, *, subcollection: str = "obsl"
     ) -> coordinates.CoordinateTransform:
         raise NotImplementedError()

diff --git a/python-spec/src/somacore/scene.py b/python-spec/src/somacore/scene.py
@@ -16,7 +16,9 @@
 _MultiscaleImage = TypeVar("_MultiscaleImage", bound=spatial.MultiscaleImage)
 """A particular implementation of a multiscale image."""
 
-_PointCloud = TypeVar("_PointCloud", bound=spatial.PointCloud)
+_PointCloudDataFrame = TypeVar(
+    "_PointCloudDataFrame", bound=spatial.PointCloudDataFrame
+)
 """A particular implementation of a point cloud."""
 
 _GeometryDataFrame = TypeVar("_GeometryDataFrame", bound=spatial.GeometryDataFrame)
@@ -28,7 +30,7 @@
 
 class Scene(
     collection.BaseCollection[_RootSO],
-    Generic[_MultiscaleImage, _PointCloud, _GeometryDataFrame, _RootSO],
+    Generic[_MultiscaleImage, _PointCloudDataFrame, _GeometryDataFrame, _RootSO],
 ):
     """A collection subtype representing spatial assets that can all be stored
     on a single coordinate space.
@@ -45,7 +47,7 @@ class Scene(
     #         ImplBaseCollection[ImplSOMAObject],
     #         somacore.Scene[
     #             ImplMultiscaleImage,
-    #             ImplPointCloud,
+    #             ImplPointCloudDataFrame,
     #             ImplGeometryDataFrame,
     #             ImplSOMAObject,
     #         ],
@@ -61,19 +63,21 @@ class Scene(
     Lifecycle: experimental
     """
 
-    obsl = _mixin.item[collection.Collection[Union[_PointCloud, _GeometryDataFrame]]]()
+    obsl = _mixin.item[
+        collection.Collection[Union[_PointCloudDataFrame, _GeometryDataFrame]]
+    ]()
     """A collection of observation location data.
 
     This collection exists to store any spatial data in the scene that joins on the obs
-    ``soma_joinid``. Each dataframe in ``obsl`` can be either a PointCloud
+    ``soma_joinid``. Each dataframe in ``obsl`` can be either a PointCloudDataFrame
     or a GeometryDataFrame.
 
     Lifecycle: experimental
     """
 
     varl = _mixin.item[
         collection.Collection[
-            collection.Collection[Union[_PointCloud, _GeometryDataFrame]]
+            collection.Collection[Union[_PointCloudDataFrame, _GeometryDataFrame]]
         ]
     ]()
     """A collection of collections of variable location data.
@@ -83,7 +87,7 @@ class Scene(
     collection maps from measurement name to a collection of dataframes.
 
     Each dataframe in a ``varl`` subcollection can be either a GeometryDataFrame or a
-    PointCloud.
+    PointCloudDataFrame.
 
     Lifecycle: experimental
     """
@@ -161,7 +165,7 @@ def add_multiscale_image(
         """Adds a ``MultiscaleImage`` to the scene and sets a coordinate transform
         between the scene and the dataframe.
 
-        Parameters are as in :meth:`spatial.PointCloud.create`.
+        Parameters are as in :meth:`spatial.PointCloudDataFrame.create`.
         See :meth:`add_new_collection` for details about child URIs.
 
         Args:
@@ -178,7 +182,7 @@ def add_multiscale_image(
         raise NotImplementedError()
 
     @abc.abstractmethod
-    def add_new_point_cloud(
+    def add_new_point_cloud_dataframe(
         self,
         key: str,
         subcollection: Union[str, Sequence[str]],
@@ -190,11 +194,11 @@ def add_new_point_cloud(
         axis_names: Sequence[str] = ("x", "y"),
         domain: Optional[Sequence[Optional[Tuple[Any, Any]]]] = None,
         platform_config: Optional[options.PlatformConfig] = None,
-    ) -> _PointCloud:
+    ) -> _PointCloudDataFrame:
         """Adds a point cloud to the scene and sets a coordinate transform
         between the scene and the dataframe.
 
-        Parameters are as in :meth:`spatial.PointCloud.create`.
+        Parameters are as in :meth:`spatial.PointCloudDataFrame.create`.
         See :meth:`add_new_collection` for details about child URIs.
 
         Args:
@@ -204,7 +208,7 @@ def add_new_point_cloud(
                 dataframe is stored in. Defaults to ``'obsl'``.
 
         Returns:
-            The newly created ``PointCloud``, opened for writing.
+            The newly created ``PointCloudDataFrame``, opened for writing.
 
         Lifecycle: experimental
         """
@@ -279,14 +283,14 @@ def set_transform_to_multiscale_image(
         raise NotImplementedError()
 
     @abc.abstractmethod
-    def set_transform_to_point_cloud(
+    def set_transform_to_point_cloud_dataframe(
         self,
         key: str,
         transform: coordinates.CoordinateTransform,
         *,
         subcollection: Union[str, Sequence[str]] = "obsl",
         coordinate_space: Optional[coordinates.CoordinateSpace] = None,
-    ) -> _PointCloud:
+    ) -> _PointCloudDataFrame:
         """Adds the coordinate transform for the scene coordinate space to
         a point cloud stored in the scene.
 
@@ -295,7 +299,7 @@ def set_transform_to_point_cloud(
         to set a transform for  a point named `transcripts` in the `var/RNA`
         collection::
 
-            scene.set_transformation_for_point_cloud(
+            scene.set_transformation_for_point_cloud_dataframe(
                 'transcripts', transform, subcollection=['var', 'RNA'],
             )
 
@@ -361,7 +365,7 @@ def get_transform_from_multiscale_image(
         raise NotImplementedError()
 
     @abc.abstractmethod
-    def get_transform_from_point_cloud(
+    def get_transform_from_point_cloud_dataframe(
         self, key: str, *, subcollection: str = "obsl"
     ) -> coordinates.CoordinateTransform:
         """Returns the coordinate transformation from the requested point cloud to
@@ -425,7 +429,7 @@ def get_transform_to_multiscale_image(
         raise NotImplementedError()
 
     @abc.abstractmethod
-    def get_transform_to_point_cloud(
+    def get_transform_to_point_cloud_dataframe(
         self, key: str, *, subcollection: str = "obsl"
     ) -> coordinates.CoordinateTransform:
         """Returns the coordinate transformation from the scene to a requested

diff --git a/python-spec/src/somacore/spatial.py b/python-spec/src/somacore/spatial.py
@@ -34,18 +34,20 @@
 _ReadData = TypeVar("_ReadData")
 
 
-class PointCloud(base.SOMAObject, metaclass=abc.ABCMeta):
-    """A specialized SOMA DataFrame for storing collections of points in multi-dimensional space.
+class PointCloudDataFrame(base.SOMAObject, metaclass=abc.ABCMeta):
+    """A specialized SOMA DataFrame for storing collections of points in
+    multi-dimensional space.
 
-    The ``PointCloud`` class is designed to efficiently store and query point data, where each
-    point is represented by coordinates in one or more spatial dimensions (e.g., x, y, z) and
-    may have additional columns for associated attributes.
+    The ``PointCloudDataFrame`` class is designed to efficiently store and query point
+    data, where each point is represented by coordinates in one or more spatial
+    dimensions (e.g., x, y, z) and may have additional columns for associated
+    attributes.
 
     Lifecycle: experimental
     """
 
     __slots__ = ()
-    soma_type: Final = "SOMAPointCloud"  # type: ignore[misc]
+    soma_type: Final = "SOMAPointCloudDataFrame"  # type: ignore[misc]
 
     @classmethod
     @abc.abstractmethod
@@ -60,7 +62,7 @@ def create(
         platform_config: Optional[options.PlatformConfig] = None,
         context: Optional[Any] = None,
     ) -> Self:
-        """Creates a new ``PointCloud`` at the given URI.
+        """Creates a new ``PointCloudDataFrame`` at the given URI.
 
         The schema of the created point cloud  will include a column named
         ``soma_joinid`` of type ``pyarrow.int64``, with negative values disallowed, and