From 916066dd3276845d723d679ceafe81d8d0205b46 Mon Sep 17 00:00:00 2001 From: jp-dark Date: Thu, 12 Mar 2026 14:46:46 -0400 Subject: [PATCH 1/3] Add Scene operation docs to abstract spec --- abstract_specification.md | 120 +++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 3 deletions(-) diff --git a/abstract_specification.md b/abstract_specification.md index 963c294..84a90b8 100644 --- a/abstract_specification.md +++ b/abstract_specification.md @@ -230,7 +230,7 @@ In addition to the `soma_joinid`, every `SOMAGeometryDataFrame` must contain a c names of other columns in the table. The `soma_geometry` must be an index column, but the user may also specify other additional columns as index columns. Multiple items with the same geometry may be stored in the `SOMAGeometryDataFrame`. -SOMADataFrame`is the zero or null value of the respective column data type (e.g.,`Arrow.float32`defaults to 0.0,`Arrow.string`to`""\`, etc). +`SOMADataFrame` is the zero or null value of the respective column data type (e.g., `Arrow.float32` defaults to 0.0, `Arrow.string` to `""`, etc). ### SOMADenseNDArray @@ -282,7 +282,7 @@ The `SOMAExperiment`, `SOMAMeasurement`, and `SOMAScene` types comprise [foundat - `SOMAMeasurement`: for all observables, a common set of annotated variables (defined by a `SOMADataFrame`) for which values (e.g., measurements, calculations) are stored in `SOMADenseNDArray` and `SOMASparseNDArray`. - `SOMAScene`: images and spatially indexed data stored on a fixed coordinate system that relate back to the observables and measurements. -In other words, every `SOMAMeasurement` has a distinct set of variables (features), and inherits common observables from its parent `SOMAExperiment`. The `obs` and `var` dataframes define the axis annotations, and their respective `soma_joinid` values are the indices for all matrixes stored in the `SOMAMeasurement`. Each `SOMAScene` stores images and spatial dataframes that join on the `obs` and var\` dataframes. +In other words, every `SOMAMeasurement` has a distinct set of variables (features), and inherits common observables from its parent `SOMAExperiment`. The `obs` and `var` dataframes define the axis annotations, and their respective `soma_joinid` values are the indices for all matrixes stored in the `SOMAMeasurement`. Each `SOMAScene` stores images and spatial dataframes that join on the `obs` and `var` dataframes.
SOMAExperiment @@ -648,7 +648,121 @@ add_new_collection(string key, CollectionType kind, string uri = "", PlatformCon ## SOMAScene - +`SOMAScene` is a specialization of `SOMACollection` that stores spatially resolved data registered to a single coordinate space. All [SOMACollection operations](#somacollection) apply. In addition, `SOMAScene` provides a coordinate space, three fixed sub-collections (`img` for multiscale images, `obsl` for observation data at a given location, and `varl` for variable data at a given locatino), and operations to create and query coordinate transforms between elements in those sub-collections and the scene. + +Summary of additional operations on a `SOMAScene`: + +| Operation | Description | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------- | +| static create(uri, ...) -> SOMAScene | Create a `SOMAScene`. | +| get soma_type | Returns the constant "SOMAScene". | +| get coordinate_space -> CoordinateSpace | Return the coordinate space for this scene. | +| set coordinate_space | Set the coordinate space for this scene. | +| add_new\_``(key, subcollection, transform, ...) | Create a new spatial object in a sub-collection and register its transform. | +| set_transform_to\_``(key, subcollection, transform, ...) | Set the coordinate transform to an existing spatial object. | +| get_transform_to\_``(key, subcollection, ...) -> CoordinateTransform | Return the transform from the scene to a spatial object. | +| get_transform_from\_``(key, subcollection, ...) -> CoordinateTransform | Return the transform from a spatial object to the scene. | + +Where `` is one of `geometry_dataframe`, `multiscale_image`, or `point_cloud_dataframe`. + +### Operation: create() + +Create a new `SOMAScene` with user-specified URI. + +``` +SOMAScene.create(string uri, CoordinateSpace coordinate_space = NULL, platform_config, context) -> SOMAScene +``` + +Parameters: + +- `uri`: location at which to create the object. +- `coordinate_space`: the coordinate space for the scene, or a list of axis names from which to construct one. If `NULL`, no coordinate space is set at creation time. +- [`platform_config`](#platform-specific-configuration): optional storage-engine-specific configuration. +- [`context`](#long-lived-context-data): optional context to use for this new object. + +Returns: The newly created `SOMAScene`, opened in write mode. + +### get coordinate_space + +Return the `CoordinateSpace` for the scene. Returns `NULL` if no coordinate space has been set. + +### set coordinate_space + +Set the coordinate space for the scene. The provided value must be a `CoordinateSpace`. + +### Operation: add_new\_spatial_type + +Each add_new\_spatial_type method creates a new spatial SOMA object in storage, adds it to the specified sub-collection, registers a coordinate transform between the scene and the new object, and returns it to the user. The newly created entry has the same `context` value as the scene and is [owned by the scene](#operation-close-collection-types). + +``` +add_new_geometry_dataframe(string key, string|string[] subcollection, CoordinateTransform transform, string uri = "", ...) -> SOMAGeometryDataFrame +add_new_multiscale_image(string key, string|string[] subcollection, CoordinateTransform transform, string uri = "", ...) -> SOMAMultiscaleImage +add_new_point_cloud_dataframe(string key, string|string[] subcollection, CoordinateTransform transform, string uri = "", ...) -> SOMAPointCloudDataFrame +``` + +Parameters: + +- `key`: The name for the new object within its sub-collection. +- `subcollection`: The name of the sub-collection (`"img"`, `"obsl"`, or `"varl"`) in which to store the object. If the target is more than one level deep (e.g., a measurement-specific collection within `varl`), provide a sequence of names. +- `transform`: The coordinate transform from the scene coordinate space to the new object. May be `NULL` to leave the transform unregistered at creation time. +- `uri`: An optional URI for the new object. Follows the same semantics as [`add_new_object_type`](#operation-add_new_object_type). + +The remaining parameters are passed directly to the respective type's `create` static method, except for `context`, which is always set to the scene's context. + +### Operation: set_transform_to\_spatial_type + +Each set_transform_to\_spatial_type method sets (or replaces) the coordinate transform from the scene coordinate space to an existing spatial object stored in the scene. + +``` +set_transform_to_geometry_dataframe(string key, string|string[] subcollection = "obsl", CoordinateTransform transform, CoordinateSpace coordinate_space = NULL) -> SOMAGeometryDataFrame +set_transform_to_multiscale_image(string key, string|string[] subcollection = "img", CoordinateTransform transform, CoordinateSpace coordinate_space = NULL) -> SOMAMultiscaleImage +set_transform_to_point_cloud_dataframe(string key, string|string[] subcollection = "obsl", CoordinateTransform transform, CoordinateSpace coordinate_space = NULL) -> SOMAPointCloudDataFrame +``` + +Parameters: + +- `key`: The name of the spatial object within its sub-collection. +- `subcollection`: The name, or sequence of names, of the sub-collection the object is stored in. Defaults to `"obsl"` for dataframes and `"img"` for images. +- `transform`: The coordinate transform from the scene coordinate space to the spatial object. For `SOMAMultiscaleImage`, the transform must be to the reference level of the image. +- `coordinate_space`: If provided, replaces the existing coordinate space of the spatial object. + +Returns: The spatial object, opened for writing. + +### Operation: get_transform_to\_spatial_type + +Each get_transform_to\_spatial_type method returns the coordinate transform from the scene coordinate space to the requested spatial object. + +``` +get_transform_to_geometry_dataframe(string key, string|string[] subcollection = "obsl") -> CoordinateTransform +get_transform_to_multiscale_image(string key, string|string[] subcollection = "img", string|int level = NULL) -> CoordinateTransform +get_transform_to_point_cloud_dataframe(string key, string|string[] subcollection = "obsl") -> CoordinateTransform +``` + +Parameters: + +- `key`: The name of the spatial object within its sub-collection. +- `subcollection`: The name, or sequence of names, of the sub-collection the object is stored in. +- `level` (multiscale image only): The image level to get the transform to. Defaults to `NULL`, which returns the transform to the reference level. + +Returns: A `CoordinateTransform` from the scene coordinate space to the requested object. + +### Operation: get_transform_from\_spatial_type + +Each get_transform_from\_spatial_type method returns the coordinate transform from the requested spatial object to the scene coordinate space (the inverse direction of get_transform_to\_spatial_type). + +``` +get_transform_from_geometry_dataframe(string key, string|string[] subcollection = "obsl") -> CoordinateTransform +get_transform_from_multiscale_image(string key, string|string[] subcollection = "img", string|int level = NULL) -> CoordinateTransform +get_transform_from_point_cloud_dataframe(string key, string|string[] subcollection = "obsl") -> CoordinateTransform +``` + +Parameters: + +- `key`: The name of the spatial object within its sub-collection. +- `subcollection`: The name, or sequence of names, of the sub-collection the object is stored in. +- `level` (multiscale image only): The image level to get the transform from. Defaults to `NULL`, which returns the transform from the reference level. + +Returns: A `CoordinateTransform` from the requested object to the scene coordinate space. ## SOMADataFrame From 2987a3f85ce566dbe2ef2c88c2261e36193f5340 Mon Sep 17 00:00:00 2001 From: Julia Dark <24235303+jp-dark@users.noreply.github.com> Date: Thu, 12 Mar 2026 16:54:51 -0400 Subject: [PATCH 2/3] Some edits Co-authored-by: Julia Dark <24235303+jp-dark@users.noreply.github.com> --- abstract_specification.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/abstract_specification.md b/abstract_specification.md index 84a90b8..f63aabf 100644 --- a/abstract_specification.md +++ b/abstract_specification.md @@ -230,7 +230,7 @@ In addition to the `soma_joinid`, every `SOMAGeometryDataFrame` must contain a c names of other columns in the table. The `soma_geometry` must be an index column, but the user may also specify other additional columns as index columns. Multiple items with the same geometry may be stored in the `SOMAGeometryDataFrame`. -`SOMADataFrame` is the zero or null value of the respective column data type (e.g., `Arrow.float32` defaults to 0.0, `Arrow.string` to `""`, etc). +`SOMADataFrame` is the zero or null value of the respective column data type (e.g., `Arrow.float32` defaults to 0.0, `Arrow.string` to `"\"`, etc). ### SOMADenseNDArray @@ -658,12 +658,19 @@ Summary of additional operations on a `SOMAScene`: | get soma_type | Returns the constant "SOMAScene". | | get coordinate_space -> CoordinateSpace | Return the coordinate space for this scene. | | set coordinate_space | Set the coordinate space for this scene. | -| add_new\_``(key, subcollection, transform, ...) | Create a new spatial object in a sub-collection and register its transform. | -| set_transform_to\_``(key, subcollection, transform, ...) | Set the coordinate transform to an existing spatial object. | -| get_transform_to\_``(key, subcollection, ...) -> CoordinateTransform | Return the transform from the scene to a spatial object. | -| get_transform_from\_``(key, subcollection, ...) -> CoordinateTransform | Return the transform from a spatial object to the scene. | +| add_new\_point_cloud_dataframe(key, subcollection, transform, ...) | Create a new `PointCloudDataFrame` in a sub-collection and register its transform. | +| add_new\_geometry_dataframe(key, subcollection, transform, ...) | Create a new `GeometryDataFrame` in a sub-collection and register its transform. | +| add_new\_multiscale_image(key, subcollection, transform, ...) | Create a new `MultiscaleImage` in a sub-collection and register its transform. | +| set_transform_to\_point_cloud_dataframe(key, subcollection, transform, ...) | Set the coordinate transform to an existing `PointCloudDataFrame` stored in a sub-collection in this `SOMAScene`. | +| set_transform_to\_geometry_dataframe(key, subcollection, transform, ...) | Set the coordinate transform to an existing `GeometryDataFrame` stored in a sub-collection in this `SOMAScene`. | +| set_transform_to\_MultiscaleImage(key, subcollection, transform, ...) | Set the coordinate transform to an existing `MultiscaleImage` stored in this `SOMAScene`. | +| get_transform_to\_point_cloud_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a PointCloudDataFrame contained in it. | +| get_transform_to\_geometry_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a `GeometryDataFrame` contained in it. | +| get_transform_to\_multiscale_image(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a `MultiscaleImage`. | +| get_transform_from\_point_cloud_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `PointCloudDataFrame` to the `SOMAScene`. | +| get_transform_from\_geometry_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `GeometryDataframe` to the `SOMAScene`. | +| get_transform_from\_multiscale_image(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `MultiscaleImage` to the `SOMAScene`. | -Where `` is one of `geometry_dataframe`, `multiscale_image`, or `point_cloud_dataframe`. ### Operation: create() From ced446f7275c2836ce07d81c3683534bea9946ad Mon Sep 17 00:00:00 2001 From: jp-dark Date: Fri, 13 Mar 2026 10:05:23 -0400 Subject: [PATCH 3/3] Run linters --- abstract_specification.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/abstract_specification.md b/abstract_specification.md index f63aabf..e03574f 100644 --- a/abstract_specification.md +++ b/abstract_specification.md @@ -658,19 +658,18 @@ Summary of additional operations on a `SOMAScene`: | get soma_type | Returns the constant "SOMAScene". | | get coordinate_space -> CoordinateSpace | Return the coordinate space for this scene. | | set coordinate_space | Set the coordinate space for this scene. | -| add_new\_point_cloud_dataframe(key, subcollection, transform, ...) | Create a new `PointCloudDataFrame` in a sub-collection and register its transform. | -| add_new\_geometry_dataframe(key, subcollection, transform, ...) | Create a new `GeometryDataFrame` in a sub-collection and register its transform. | -| add_new\_multiscale_image(key, subcollection, transform, ...) | Create a new `MultiscaleImage` in a sub-collection and register its transform. | -| set_transform_to\_point_cloud_dataframe(key, subcollection, transform, ...) | Set the coordinate transform to an existing `PointCloudDataFrame` stored in a sub-collection in this `SOMAScene`. | -| set_transform_to\_geometry_dataframe(key, subcollection, transform, ...) | Set the coordinate transform to an existing `GeometryDataFrame` stored in a sub-collection in this `SOMAScene`. | -| set_transform_to\_MultiscaleImage(key, subcollection, transform, ...) | Set the coordinate transform to an existing `MultiscaleImage` stored in this `SOMAScene`. | -| get_transform_to\_point_cloud_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a PointCloudDataFrame contained in it. | -| get_transform_to\_geometry_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a `GeometryDataFrame` contained in it. | -| get_transform_to\_multiscale_image(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a `MultiscaleImage`. | -| get_transform_from\_point_cloud_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `PointCloudDataFrame` to the `SOMAScene`. | -| get_transform_from\_geometry_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `GeometryDataframe` to the `SOMAScene`. | -| get_transform_from\_multiscale_image(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `MultiscaleImage` to the `SOMAScene`. | - +| add_new_point_cloud_dataframe(key, subcollection, transform, ...) | Create a new `PointCloudDataFrame` in a sub-collection and register its transform. | +| add_new_geometry_dataframe(key, subcollection, transform, ...) | Create a new `GeometryDataFrame` in a sub-collection and register its transform. | +| add_new_multiscale_image(key, subcollection, transform, ...) | Create a new `MultiscaleImage` in a sub-collection and register its transform. | +| set_transform_to_point_cloud_dataframe(key, subcollection, transform, ...) | Set the coordinate transform to an existing `PointCloudDataFrame` stored in a sub-collection in this `SOMAScene`. | +| set_transform_to_geometry_dataframe(key, subcollection, transform, ...) | Set the coordinate transform to an existing `GeometryDataFrame` stored in a sub-collection in this `SOMAScene`. | +| set_transform_to_MultiscaleImage(key, subcollection, transform, ...) | Set the coordinate transform to an existing `MultiscaleImage` stored in this `SOMAScene`. | +| get_transform_to_point_cloud_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a PointCloudDataFrame contained in it. | +| get_transform_to_geometry_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a `GeometryDataFrame` contained in it. | +| get_transform_to_multiscale_image(key, subcollection, ...) -> CoordinateTransform | Return the transform from the `SOMAScene` to a `MultiscaleImage`. | +| get_transform_from_point_cloud_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `PointCloudDataFrame` to the `SOMAScene`. | +| get_transform_from_geometry_dataframe(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `GeometryDataframe` to the `SOMAScene`. | +| get_transform_from_multiscale_image(key, subcollection, ...) -> CoordinateTransform | Return the transform from a `MultiscaleImage` to the `SOMAScene`. | ### Operation: create()