add static set annotation (scverse#510)

* add static set annotation

* adjust docstring

* fix categorical not hashable

* update changelog

* change name add tests

CHANGELOG.md

@@ -38,6 +38,8 @@ and this project adheres to [Semantic Versioning][].
 -   Added function get_instance_key_column in SpatialData to get the instance_key column in table.obs.
 -   Added function set_table_annotates_spatialelement in SpatialData to either set or change the annotation metadata of
     a table in a given SpatialData object.
+-   Added function table_annotates_spatialelement which slightly differs from function above as it takes the table object
+    as argument instead of the table_name.
 -   Added table_name parameter to the aggregate function to allow users to give a custom table name to table resulting
     from aggregation.
 -   Added table_name parameter to the get_values function.

src/spatialdata/_core/spatialdata.py

@@ -396,6 +396,37 @@ def _change_table_annotation_target(
         check_target_region_column_symmetry(table, table_region_key, region)
         attrs[TableModel.REGION_KEY] = region
 
+    @staticmethod
+    def update_annotated_regions_metadata(table: AnnData, region_key: str | None = None) -> AnnData:
+        """
+        Update the annotation target of the table using the region_key column in table.obs.
+
+        The table must already contain annotation metadata, e.g. the region, region_key and instance_key
+        must already be specified for the table. If this is not the case please use TableModel.parse instead
+        and specify the annotation metadata by passing the correct arguments to that function.
+
+        Parameters
+        ----------
+        table
+            The AnnData table for which to set the annotation target.
+        region_key
+            The column in table.obs containing the rows specifying the SpatialElements being annotated.
+            If None the current value for region_key in the annotation metadata of the table is used. If
+            specified but different from the current region_key, the current region_key is overwritten.
+
+        Returns
+        -------
+        The table for which the annotation target has been set.
+        """
+        attrs = table.uns.get(TableModel.ATTRS_KEY)
+        if attrs is None:
+            raise ValueError("The table has no annotation metadata. Please parse the table using `TableModel.parse`.")
+        region_key = region_key if region_key else attrs[TableModel.REGION_KEY_KEY]
+        if attrs[TableModel.REGION_KEY_KEY] != region_key:
+            attrs[TableModel.REGION_KEY_KEY] = region_key
+        attrs[TableModel.REGION_KEY] = table.obs[region_key].unique().tolist()
+        return table
+
     def set_table_annotates_spatialelement(
         self,
         table_name: str,

tests/io/test_multi_table.py

@@ -246,3 +246,24 @@ def test_concatenate_sdata_multitables():
     assert merged_sdata.tables["table2"].n_obs == 300
     assert all(merged_sdata.tables["table"].obs.region.unique() == ["poly_1", "poly_2", "poly_3"])
     assert all(merged_sdata.tables["table2"].obs.region.unique() == ["multipoly_1", "multipoly_2", "multipoly_3"])
+
+
+def test_static_set_annotation_target():
+    test_sdata = SpatialData(
+        shapes={
+            "test_shapes": test_shapes["poly"],
+        }
+    )
+    table = _get_table(region="test_non_shapes")
+    table_target = table.copy()
+    table_target.obs["region"] = "test_shapes"
+    table_target = SpatialData.update_annotated_regions_metadata(table_target)
+    assert table_target.uns[TableModel.ATTRS_KEY][TableModel.REGION_KEY] == ["test_shapes"]
+
+    test_sdata["another_table"] = table_target
+
+    table.obs["diff_region"] = "test_shapes"
+    table = SpatialData.update_annotated_regions_metadata(table, region_key="diff_region")
+    assert table.uns[TableModel.ATTRS_KEY][TableModel.REGION_KEY] == ["test_shapes"]
+
+    test_sdata["yet_another_table"] = table