Support modifying/filtering labels elements via join operations (#946)

* init

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix mypy linterrors

* update the location and the design

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* update docs

* make coverage 100/100 because why not

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixed type annotation

* dont compute eagerly use. delete other instance key for consistency

* update the tests and make sure we use match_element_to_table

* wip rewrite tests using existing APIs

* test passing without using subset_sdata_by_table_mask()

* Remove _filter_by_instance_ids and _get_scale_factors; refactor tests to use existing API

- Remove _get_scale_factors (duplicated logic already in transformations/_utils.py)
- Remove _filter_by_instance_ids and subset_sdata_by_table_mask (superseded by match_sdata_to_table / filter_by_table_query)
- Parametrize test_subset_sdata_by_table_mask over both API functions
- Replace test_filter_2d_labels_by_instance_ids with test_filter_out_instances, parametrized over both API functions and element types (2D / multiscale labels)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add filter_label_pixels flag to match_sdata_to_table and filter_by_table_query

Threads a filter_label_pixels: bool = False parameter through the full join
stack (filter_by_table_query → match_sdata_to_table → join_spatialelement_table
→ _call_join → _right/_inner_join_spatialelement_table).

When True, label pixels for removed instances are zeroed via a new
_filter_labels_element helper (handles both DataArray and multiscale DataTree).
When False (default), the existing warning is preserved but now also hints at
the new flag.

Tests no longer need manual _set_instance_ids_in_labels_to_zero calls or
warnings suppression.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Change filter_label_pixels default to None; False silences the warning

- None (default): warn that label pixels are not filtered, hint at the flag
- True: filter label pixels (set removed instance pixels to zero)
- False: skip silently, no warning

Updated docstrings in join_spatialelement_table, match_sdata_to_table,
and filter_by_table_query to document all three states.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Move and consolidate label-filtering tests into test_relational_query_match_sdata_to_table

- Replace test_match_sdata_to_table_match_labels_error with
  test_filter_out_instances: parametrized over both API functions and
  element types; tests all three filter_label_pixels states (None→warn,
  False→nullcontext noop, True→pixels filtered)
- Add test_subset_sdata_by_table_mask for mixed-element subsetting
- Delete test_relational_query_subset_sdata_by_table_mask.py

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add 3D labels guard to _filter_labels_element; fix annsel list predicate in tests

- Raise NotImplementedError in _filter_labels_element when element is Labels3DModel
- Add test_filter_out_instances_3d_labels_not_supported parametrized over both API functions
- Use an.col().is_in() instead of == [list] in 3D test (narwhals does not support nested literals)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Luca Marconato <m.lucalmer@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 4 people

src/spatialdata/_core/query/relational_query.py

@@ -11,6 +11,7 @@
 import dask.array as da
 import numpy as np
 import pandas as pd
+import xarray as xr
 from anndata import AnnData
 from annsel.core.typing import Predicates
 from dask.dataframe import DataFrame as DaskDataFrame
@@ -311,7 +312,10 @@ def _get_masked_element(
 
 
 def _right_exclusive_join_spatialelement_table(
-    element_dict: dict[str, dict[str, Any]], table: AnnData, match_rows: Literal["left", "no", "right"]
+    element_dict: dict[str, dict[str, Any]],
+    table: AnnData,
+    match_rows: Literal["left", "no", "right"],
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData | None]:
     regions, region_column_name, instance_key = get_table_keys(table)
     if isinstance(regions, str):
@@ -349,7 +353,10 @@ def _right_exclusive_join_spatialelement_table(
 
 
 def _right_join_spatialelement_table(
-    element_dict: dict[str, dict[str, Any]], table: AnnData, match_rows: Literal["left", "no", "right"]
+    element_dict: dict[str, dict[str, Any]],
+    table: AnnData,
+    match_rows: Literal["left", "no", "right"],
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData]:
     if match_rows == "left":
         warnings.warn("Matching rows 'left' is not supported for 'right' join.", UserWarning, stacklevel=2)
@@ -365,11 +372,18 @@ def _right_join_spatialelement_table(
                 if element_type in ["points", "shapes"]:
                     element_indices = element.index
                 else:
-                    warnings.warn(
-                        f"Element type `labels` not supported for 'right' join. Skipping `{name}`",
-                        UserWarning,
-                        stacklevel=2,
-                    )
+                    if filter_label_pixels is True:
+                        element_dict[element_type][name] = _filter_labels_element(
+                            element, table_instance_key_column.tolist()
+                        )
+                    elif filter_label_pixels is None:
+                        warnings.warn(
+                            f"Element type `labels` not supported for 'right' join, pixels are not filtered;"
+                            f" pass `filter_label_pixels=True` to filter or `filter_label_pixels=False` to silence"
+                            f" this warning. Skipping `{name}`",
+                            UserWarning,
+                            stacklevel=2,
+                        )
                     continue
 
                 masked_element = _get_masked_element(element_indices, element, table_instance_key_column, match_rows)
@@ -383,7 +397,10 @@ def _right_join_spatialelement_table(
 
 
 def _inner_join_spatialelement_table(
-    element_dict: dict[str, dict[str, Any]], table: AnnData, match_rows: Literal["left", "no", "right"]
+    element_dict: dict[str, dict[str, Any]],
+    table: AnnData,
+    match_rows: Literal["left", "no", "right"],
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData]:
     regions, region_column_name, instance_key = get_table_keys(table)
     if isinstance(regions, str):
@@ -399,11 +416,18 @@ def _inner_join_spatialelement_table(
                 if element_type in ["points", "shapes"]:
                     element_indices = element.index
                 else:
-                    warnings.warn(
-                        f"Element type `labels` not supported for 'inner' join. Skipping `{name}`",
-                        UserWarning,
-                        stacklevel=2,
-                    )
+                    if filter_label_pixels is True:
+                        element_dict[element_type][name] = _filter_labels_element(
+                            element, table_instance_key_column.tolist()
+                        )
+                    elif filter_label_pixels is None:
+                        warnings.warn(
+                            f"Element type `labels` not supported for 'inner' join, pixels are not filtered;"
+                            f" pass `filter_label_pixels=True` to filter or `filter_label_pixels=False` to silence"
+                            f" this warning. Skipping `{name}`",
+                            UserWarning,
+                            stacklevel=2,
+                        )
                     continue
 
                 masked_element = _get_masked_element(element_indices, element, table_instance_key_column, match_rows)
@@ -429,7 +453,10 @@ def _inner_join_spatialelement_table(
 
 
 def _left_exclusive_join_spatialelement_table(
-    element_dict: dict[str, dict[str, Any]], table: AnnData, match_rows: Literal["left", "no", "right"]
+    element_dict: dict[str, dict[str, Any]],
+    table: AnnData,
+    match_rows: Literal["left", "no", "right"],
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData | None]:
     regions, region_column_name, instance_key = get_table_keys(table)
     if isinstance(regions, str):
@@ -462,7 +489,10 @@ def _left_exclusive_join_spatialelement_table(
 
 
 def _left_join_spatialelement_table(
-    element_dict: dict[str, dict[str, Any]], table: AnnData, match_rows: Literal["left", "no", "right"]
+    element_dict: dict[str, dict[str, Any]],
+    table: AnnData,
+    match_rows: Literal["left", "no", "right"],
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData]:
     if match_rows == "right":
         warnings.warn("Matching rows 'right' is not supported for 'left' join.", UserWarning, stacklevel=2)
@@ -586,6 +616,7 @@ def join_spatialelement_table(
     table: AnnData | None = None,
     how: Literal["left", "left_exclusive", "inner", "right", "right_exclusive"] = "left",
     match_rows: Literal["no", "left", "right"] = "no",
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData]:
     """
     Join SpatialElement(s) and table together in SQL like manner.
@@ -629,6 +660,11 @@ def join_spatialelement_table(
     match_rows
         Whether to match the indices of the element and table and if so how. If ``'left'``, element_indices take
         priority and if ``'right'`` table instance ids take priority.
+    filter_label_pixels
+        Controls pixel-level filtering of label elements for ``'right'`` and ``'inner'`` joins.
+        If ``True``, pixels whose instance id is not present in the table are set to zero.
+        If ``None`` (default), label elements are returned unfiltered and a warning is issued.
+        If ``False``, label elements are returned unfiltered silently (no warning).
 
     Returns
     -------
@@ -694,12 +730,16 @@ def join_spatialelement_table(
             for name, element in getattr(derived_sdata, element_type).items():
                 elements_dict[element_type][name] = element
 
-    elements_dict_joined, table = _call_join(elements_dict, table, how, match_rows)
+    elements_dict_joined, table = _call_join(elements_dict, table, how, match_rows, filter_label_pixels)
     return elements_dict_joined, table
 
 
 def _call_join(
-    elements_dict: dict[str, dict[str, Any]], table: AnnData, how: str, match_rows: Literal["no", "left", "right"]
+    elements_dict: dict[str, dict[str, Any]],
+    table: AnnData,
+    how: str,
+    match_rows: Literal["no", "left", "right"],
+    filter_label_pixels: bool | None = None,
 ) -> tuple[dict[str, Any], AnnData]:
     assert any(key in elements_dict for key in ["labels", "shapes", "points"]), (
         "No valid element to join in spatial_element_name. Must provide at least one of either `labels`, `points` or "
@@ -714,7 +754,7 @@ def _call_join(
     # if how in JoinTypes.__dict__["_member_names_"]:
     # hotfix for bug with Python 3.13:
     if how in JoinTypes.__dict__:
-        elements_dict, table = getattr(JoinTypes, how)(elements_dict, table, match_rows)
+        elements_dict, table = getattr(JoinTypes, how)(elements_dict, table, match_rows, filter_label_pixels)
     else:
         raise TypeError(f"`{how}` is not a valid type of join.")
 
@@ -797,6 +837,7 @@ def match_sdata_to_table(
     table_name: str,
     table: AnnData | None = None,
     how: Literal["left", "left_exclusive", "inner", "right", "right_exclusive"] = "right",
+    filter_label_pixels: bool | None = None,
 ) -> SpatialData:
     """
     Filter the elements of a SpatialData object to match only the rows present in the table.
@@ -812,6 +853,10 @@ def match_sdata_to_table(
         `table_name` is used to name the table in the returned `SpatialData` object.
     how
         The type of join to perform. See :func:`spatialdata.join_spatialelement_table`. Default is "right".
+    filter_label_pixels
+        Controls pixel-level filtering of label elements. ``True`` filters pixels, ``None`` (default) leaves them
+        unfiltered and warns, ``False`` leaves them unfiltered silently. See
+        :func:`spatialdata.join_spatialelement_table` for details.
 
     Notes
     -----
@@ -823,7 +868,7 @@ def match_sdata_to_table(
     _, region_key, instance_key = get_table_keys(table)
     annotated_regions = SpatialData.get_annotated_regions(table)
     filtered_elements, filtered_table = join_spatialelement_table(
-        sdata, spatial_element_names=annotated_regions, table=table, how=how
+        sdata, spatial_element_names=annotated_regions, table=table, how=how, filter_label_pixels=filter_label_pixels
     )
     filtered_table = TableModel.parse(
         filtered_table,
@@ -847,6 +892,7 @@ def filter_by_table_query(
     var_names_expr: Predicates | None = None,
     layer: str | None = None,
     how: Literal["left", "left_exclusive", "inner", "right", "right_exclusive"] = "right",
+    filter_label_pixels: bool | None = None,
 ) -> SpatialData:
     """Filter the SpatialData object based on a set of table queries.
 
@@ -875,6 +921,10 @@ def filter_by_table_query(
         The layer of the :class:`anndata.AnnData` to filter the SpatialData object by, only used with `x_expr`.
     how
         The type of join to perform. See :func:`spatialdata.join_spatialelement_table`. Default is "right".
+    filter_label_pixels
+        Controls pixel-level filtering of label elements. ``True`` filters pixels, ``None`` (default) leaves them
+        unfiltered and warns, ``False`` leaves them unfiltered silently. See
+        :func:`spatialdata.join_spatialelement_table` for details.
 
     Returns
     -------
@@ -899,7 +949,13 @@ def filter_by_table_query(
         obs=obs_expr, var=var_expr, x=x_expr, obs_names=obs_names_expr, var_names=var_names_expr, layer=layer
     )
 
-    return match_sdata_to_table(sdata=sdata_subset, table_name=table_name, table=filtered_table, how=how)
+    return match_sdata_to_table(
+        sdata=sdata_subset,
+        table_name=table_name,
+        table=filtered_table,
+        how=how,
+        filter_label_pixels=filter_label_pixels,
+    )
 
 
 @dataclass
@@ -1099,3 +1155,50 @@ def get_values(
         return df
 
     raise ValueError(f"Unknown origin {origin}")
+
+
+def _mask_block(block: xr.DataArray, ids_to_remove: list[int]) -> xr.DataArray:
+    # Use apply_ufunc for efficient processing
+    # Create a copy to avoid modifying read-only array
+    result = block.copy()
+    result[np.isin(result, ids_to_remove)] = 0
+    return result
+
+
+def _set_instance_ids_in_labels_to_zero(image: xr.DataArray, ids_to_remove: list[int]) -> xr.DataArray:
+    processed = xr.apply_ufunc(
+        partial(_mask_block, ids_to_remove=ids_to_remove),
+        image,
+        input_core_dims=[["y", "x"]],
+        output_core_dims=[["y", "x"]],
+        vectorize=True,
+        dask="parallelized",
+        output_dtypes=[image.dtype],
+        dataset_fill_value=0,
+        dask_gufunc_kwargs={"allow_rechunk": True},
+    )
+
+    # Create a new DataArray to ensure persistence
+    return xr.DataArray(
+        data=processed.data,
+        coords=image.coords,
+        dims=image.dims,
+        attrs=image.attrs.copy(),  # Preserve all attributes
+    )
+
+
+def _filter_labels_element(element: DataArray | DataTree, ids_to_keep: list[int]) -> DataArray | DataTree:
+    if get_model(element) is Labels3DModel:
+        raise NotImplementedError("Pixel-level filtering of 3D labels is not supported.")
+    element_instances = get_element_instances(element)
+    ids_to_remove = [i for i in element_instances if i not in set(ids_to_keep)]
+    if isinstance(element, DataArray):
+        return Labels2DModel.parse(_set_instance_ids_in_labels_to_zero(element, ids_to_remove))
+    scales = list(element.keys())
+    scale_factors = [
+        round(element[scales[i]].image.shape[0] / element[scales[i + 1]].image.shape[0]) for i in range(len(scales) - 1)
+    ]
+    return Labels2DModel.parse(
+        _set_instance_ids_in_labels_to_zero(element[scales[0]].image, ids_to_remove),
+        scale_factors=scale_factors,
+    )