diff --git a/python-spec/src/somacore/base.py b/python-spec/src/somacore/base.py index 2931a7c..e71e6f6 100644 --- a/python-spec/src/somacore/base.py +++ b/python-spec/src/somacore/base.py @@ -35,7 +35,10 @@ def open( context: The Context value to use when opening the object. platform_config: Platform configuration options specific to this open operation. - Returns: The SOMA object, opened for reading. + + Returns: + The SOMA object, opened for reading. + Lifecycle: maturing """ ... @@ -50,6 +53,7 @@ def exists(cls, uri: str, *, context: Any | None = None) -> bool: Returns: True if the object exists and is of the correct type. False if the object does not exist, or is of a different type. + Lifecycle: maturing """ ... diff --git a/python-spec/src/somacore/collection.py b/python-spec/src/somacore/collection.py index cc0209b..13d537b 100644 --- a/python-spec/src/somacore/collection.py +++ b/python-spec/src/somacore/collection.py @@ -58,8 +58,10 @@ def create( Args: uri: The URI where the collection will be created. + Returns: The newly created collection, opened for writing. + Lifecycle: maturing """ ... @@ -99,6 +101,7 @@ def add_new_collection( platform_config: options.PlatformConfig | None = None, ) -> "BaseCollection": """Creates a new sub-collection of this collection. + To add an existing collection as a sub-element of this collection, use :meth:`set` or indexed access (``coll[name] = value``) instead. @@ -140,7 +143,6 @@ def add_new_collection( kind: The type of child that should be added. uri: If provided, overrides the default URI that would be used to create this object. This may be absolute or relative. - If not provided, platform_config: Platform-specific configuration options used when creating the child. @@ -247,7 +249,8 @@ def set(self, key: str, value: _Elem, *, use_relative_uri: bool | None = None) - is not possible at all, the collection should raise an error. If ``False``, will always use an absolute URI. - Returns: ``self``, to enable method chaining. + Returns: + ``self``, to enable method chaining. Lifecycle: maturing """ diff --git a/python-spec/src/somacore/coordinates.py b/python-spec/src/somacore/coordinates.py index b440828..77af930 100644 --- a/python-spec/src/somacore/coordinates.py +++ b/python-spec/src/somacore/coordinates.py @@ -26,7 +26,7 @@ def unit(self) -> str | None: class CoordinateSpace(Protocol): """A coordinate space for spatial data. - Args: + Attributes: axes: The axes of the coordinate system in order. Lifecycle: experimental @@ -58,7 +58,7 @@ def axis_names(self) -> tuple[str, ...]: class CoordinateTransform(Protocol): """A coordinate transformation from one coordinate space to another. - Args: + Attributes: input_axes: The names of the axes for the input coordinate space. output_axes: The names of the axes for the output coordinate space. diff --git a/python-spec/src/somacore/data.py b/python-spec/src/somacore/data.py index 5a3cd0c..65e9021 100644 --- a/python-spec/src/somacore/data.py +++ b/python-spec/src/somacore/data.py @@ -53,26 +53,22 @@ def create( Args: uri: The URI where the dataframe will be created. - schema: Arrow schema defining the per-column schema. This schema 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. - + domain: A sequence of tuples specifying the domain of each index + column. Each tuple must be a pair consisting of the minimum + and maximum values storable in the index column. This sequence + must have the same length as ``index_column_names``. Use + ``None`` for string index columns when the implementation does + not support string domains. 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. - - domain: - A sequence of tuples specifying the domain of each index - column. Each tuple must be a pair consisting of the minimum - and maximum values storable in the index column. This sequence - must have the same length as ``index_column_names``. Use ``None`` for string - index columns when the implementation does not support string domains. platform_config: platform-specific configuration; keys are SOMA implementation names. - context: Other implementation-specific configuration. Returns: @@ -110,10 +106,10 @@ def read( The default of ``None`` represents no filter. Value filter syntax is implementation-defined; see the documentation for the particular SOMA implementation for details. + Returns: A :class:`ReadIter` of :class:`pa.Table`s. - **Indexing:** Indexing is performed on a per-column basis for each indexed column. @@ -203,7 +199,8 @@ def write( the index columns. The schema for the values must match the schema for the ``DataFrame``. - Returns: ``self``, to enable method chaining. + Returns: + ``self``, to enable method chaining. Lifecycle: maturing """ @@ -231,7 +228,8 @@ def index_column_names(self) -> tuple[str, ...]: def domain(self) -> tuple[tuple[Any, Any], ...]: """The allowable range of values in each index column. - Returns: a tuple of minimum and maximum values, inclusive, + Returns: + A tuple of minimum and maximum values, inclusive, storable on each index column of the dataframe. Lifecycle: maturing @@ -266,7 +264,8 @@ def create( All lengths must be in the positive int64 range. The shape can be increased after creation using :meth:`resize`. - Returns: The newly created array, opened for writing. + Returns: + The newly created array, opened for writing. Lifecycle: maturing """ @@ -308,8 +307,7 @@ def schema(self) -> pa.Schema: @runtime_checkable class DenseNDArray(NDArray, Protocol): - """ - An N-dimensional array stored densely. + """An N-dimensional array stored densely. Lifecycle: maturing """ @@ -340,7 +338,8 @@ def read( platform_config: platform-specific configuration; keys are SOMA implementation names. - Returns: The data over the requested range as a tensor. + Returns: + The data over the requested range as a tensor. **Indexing:** @@ -386,7 +385,10 @@ def write( See :meth:`read` for details about indexing. values: The values to be written to the subarray. Must have the same shape as ``coords``, and matching type to the array. - Returns: ``self``, to enable method chaining. + + Returns: + ``self``, to enable method chaining. + Lifecycle: maturing """ ... @@ -420,7 +422,7 @@ def read( coords: A per-dimension sequence of coordinates defining the range to be read. batch_size: The size of batches that should be returned from a read. - See :class:`options.BatchSize` for details. + See :class:`options.BatchSize` for details. partitions: Specifies that this is part of a partitioned read, and which partition to include, if present. result_order: the order to return results, specified as a @@ -428,7 +430,8 @@ def read( platform_config: platform-specific configuration; keys are SOMA implementation names. - Returns: The data that was requested in a :class:`SparseRead`, + Returns: + The data that was requested in a :class:`SparseRead`, allowing access in any supported format. **Indexing:** @@ -483,7 +486,8 @@ def write( platform_config: platform-specific configuration; keys are SOMA implementation names. - Returns: ``self``, to enable method chaining. + Returns: + ``self``, to enable method chaining. Lifecycle: maturing """ diff --git a/python-spec/src/somacore/query/query.py b/python-spec/src/somacore/query/query.py index 0f96c46..743c6b7 100644 --- a/python-spec/src/somacore/query/query.py +++ b/python-spec/src/somacore/query/query.py @@ -29,8 +29,7 @@ class AxisColumnNames(TypedDict, total=False): - """ - Specifies column names for experiment axis query read operations. + """Specifies column names for experiment axis query read operations. Lifecycle: maturing """ @@ -170,12 +169,14 @@ def varp(self, layer: str) -> SparseRead: def obsm(self, layer: str) -> SparseRead: """Returns an ``obsm`` layer as a sparse read. + Lifecycle: maturing """ ... def varm(self, layer: str) -> SparseRead: """Returns a ``varm`` layer as a sparse read. + Lifecycle: maturing """ ... @@ -208,8 +209,7 @@ def to_anndata( varp_layers: Sequence[str] = (), drop_levels: bool = False, ) -> AnnData: - """ - Executes the query and return result as an ``AnnData`` in-memory object. + """Executes the query and return result as an ``AnnData`` in-memory object. Args: X_name: The X layer to read and return in the ``X`` slot. @@ -217,16 +217,11 @@ def to_anndata( to read. X_layers: Additional X layers to read and return in the ``layers`` slot. - obsm_layers: - Additional obsm layers to read and return in the obsm slot. - obsp_layers: - Additional obsp layers to read and return in the obsp slot. - varm_layers: - Additional varm layers to read and return in the varm slot. - varp_layers: - Additional varp layers to read and return in the varp slot. - drop_levels: - Indicate whether unused categories on axis frames should be + obsm_layers: Additional obsm layers to read and return in the obsm slot. + obsp_layers: Additional obsp layers to read and return in the obsp slot. + varm_layers: Additional varm layers to read and return in the varm slot. + varp_layers: Additional varp layers to read and return in the varp slot. + drop_levels: Indicate whether unused categories on axis frames should be dropped. By default, False, the categories which are present in the SOMA Experiment and not present in the query output are not dropped. @@ -257,8 +252,7 @@ def __exit__(self, *_: Any) -> None: ... @runtime_checkable class AxisIndexer(Protocol): - """ - Given a query, provides index-building services for obs/var axis. + """Given a query, provides index-building services for obs/var axis. Lifecycle: maturing """ diff --git a/python-spec/src/somacore/scene.py b/python-spec/src/somacore/scene.py index 2398cf5..d34bb5a 100644 --- a/python-spec/src/somacore/scene.py +++ b/python-spec/src/somacore/scene.py @@ -128,9 +128,9 @@ def add_new_geometry_dataframe( subcollection: The name, or sequence of names, of the subcollection the dataframe is stored in. transform: The coordinate transformation from the scene to the dataframe. - uri: If provided, overrides the default URI what would be used to create - this object. This may be aboslution or relative. - kwargs: Additional keyword arugments as specified in + uri: If provided, overrides the default URI that would be used to create + this object. This may be absolute or relative. + kwargs: Additional keyword arguments as specified in :meth:`spatial.GeometryDataFrame.create`. Returns: @@ -159,9 +159,9 @@ def add_new_multiscale_image( subcollection: The name, or sequence of names, of the subcollection the dataframe is stored in. transform: The coordinate transformation from the scene to the dataframe. - uri: If provided, overrides the default URI what would be used to create - this object. This may be aboslution or relative. - kwargs: Additional keyword arugments as specified in + uri: If provided, overrides the default URI that would be used to create + this object. This may be absolute or relative. + kwargs: Additional keyword arguments as specified in :meth:`spatial.MultiscaleImage.create`. Returns: @@ -192,7 +192,6 @@ def add_new_point_cloud_dataframe( 'transcripts', subcollection=['var', 'RNA'], **kwargs ) - See :meth:`add_new_collection` for details about child URIs. Args: @@ -200,9 +199,9 @@ def add_new_point_cloud_dataframe( subcollection: The name, or sequence of names, of the subcollection the dataframe is stored in. transform: The coordinate transformation from the scene to the dataframe. - uri: If provided, overrides the default URI what would be used to create - this object. This may be aboslution or relative. - kwargs: Additional keyword arugments as specified in + uri: If provided, overrides the default URI that would be used to create + this object. This may be absolute or relative. + kwargs: Additional keyword arguments as specified in :meth:`spatial.PointCloudDataFrame.create`. Returns: @@ -234,9 +233,9 @@ def set_transform_to_geometry_dataframe( Args: key: The name of the geometry dataframe. - transform: The coordinate transformation from the scene to the dataframe. subcollection: The name, or sequence of names, of the subcollection the dataframe is stored in. Defaults to ``'obsl'``. + transform: The coordinate transformation from the scene to the dataframe. coordinate_space: Optional coordinate space for the dataframe. This will replace the existing coordinate space of the dataframe. diff --git a/python-spec/src/somacore/spatial.py b/python-spec/src/somacore/spatial.py index 099aaa4..4991fff 100644 --- a/python-spec/src/somacore/spatial.py +++ b/python-spec/src/somacore/spatial.py @@ -61,11 +61,11 @@ 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. domain: A sequence of tuples specifying the domain of each index column. Each tuple must be a pair consisting of the minimum and maximum values storable in the index column. + coordinate_space: Either the coordinate space or the axis names for the + coordinate space the point cloud is defined on. platform_config: platform-specific configuration; keys are SOMA implementation names. context: Other implementation-specific configuration. @@ -132,7 +132,6 @@ def read_spatial_region( """Reads data intersecting an user-defined region of space into a :class:`SpatialRead` with data in Arrow tables. - Args: region: The region to query. May be a box in the form [x_min, y_min, x_max, y_max] (for 2D images), a box in the form @@ -183,7 +182,8 @@ def write( platform_config: platform-specific configuration; keys are SOMA implementation names. - Returns: ``self``, to enable method chaining. + Returns: + ``self``, to enable method chaining. Lifecycle: experimental """ @@ -227,7 +227,8 @@ def coordinate_space(self, value: coordinates.CoordinateSpace) -> None: def domain(self) -> tuple[tuple[Any, Any], ...]: """The allowable range of values in each index column. - Returns: a tuple of minimum and maximum values, inclusive, + Returns: + A tuple of minimum and maximum values, inclusive, storable on each index column of the dataframe. Lifecycle: experimental @@ -277,14 +278,14 @@ 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. domain: A 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. Two tuples must be provided for the ``soma_geometry`` column with the first tuple specifying the minimum and maximum values of the width and the second tuple specifying the minimum and maximum values of the height. + coordinate_space: Either the coordinate space or the axis names for the + coordinate space the point cloud is defined on. platform_config: platform-specific configuration; keys are SOMA implementation names. context: Other implementation-specific configuration. @@ -328,6 +329,7 @@ def read( for the particular SOMA implementation for details. platform_config: platform-specific configuration; keys are SOMA implementation names. + Returns: A :class:`ReadIter` of :class:`pa.Table`s. @@ -351,7 +353,6 @@ def read_spatial_region( """Reads data intersecting an user-defined region of space into a :class:`SpatialRead` with data in Arrow tables. - Args: region: The region to query. May be a box in the form [x_min, y_min, x_max, y_max] (for 2D images), a box in the form @@ -402,7 +403,8 @@ def write( platform_config: platform-specific configuration; keys are SOMA implementation names. - Returns: ``self``, to enable method chaining. + Returns: + ``self``, to enable method chaining. Lifecycle: experimental """ @@ -446,7 +448,8 @@ def coordinate_space(self, value: coordinates.CoordinateSpace) -> None: def domain(self) -> tuple[tuple[Any, Any], ...]: """The allowable range of values in each index column. - Returns: a tuple of minimum and maximum values, inclusive, + Returns: + A tuple of minimum and maximum values, inclusive, storable on each index column of the dataframe. Lifecycle: experimental @@ -569,7 +572,8 @@ def set( is not possible at all, the collection should raise an error. If ``False``, will always use an absolute URI. - Returns: ``self``, to enable method chaining. + Returns: + ``self``, to enable method chaining. Lifecycle: experimental """ @@ -611,18 +615,20 @@ def read_spatial_region( region_coord_space: An optional coordinate space for the region being read. The axis names must match the input axis names of the transform. Defaults to ``None``, coordinate space will be inferred from transform. - data_axis_order: The order to return the data axes in. Use ``soma_channel`` - to specify the location of the channel coordinate. result_order: The order data to return results, specified as a :class:`~options.ResultOrder` or its string value. This is the result order the data is read from disk. It may be permuted if ``data_axis_order`` is not the default order. + data_axis_order: The order to return the data axes in. Use ``soma_channel`` + to specify the location of the channel coordinate. platform_config: platform-specific configuration; keys are SOMA implementation names. Returns: The data bounding the requested region as a :class:`SpatialRead` with :class:`pa.Tensor` data. + + Lifecycle: experimental """ ... @@ -706,7 +712,7 @@ def nchannels(self) -> int: class SpatialRead(Protocol[_T]): """Reader for spatial data. - Args: + Attributes: data: The data accessor. data_coordinate_space: The coordinate space the read data is defined on. output_coordinate_space: The requested output coordinate space.