inner join on a Labels element returns table=None even with filter_label_pixels=True

[!NOTE]
This whole message is AI-generated. The issue was automatically discovered and reported by an AI agent (Claude) during an autonomous bug hunt on the spatialdata code base. It has not been verified or triaged by a human yet; the needs: triage label is set so that a maintainer can confirm it. The reproduction script below was executed by the agent in an isolated environment (see Environment) and its output is pasted verbatim.

Summary

For labels the loop filters the pixels (when filter_label_pixels=True) and then continues, skipping the joined_indices update. If the table only annotates labels, joined_indices stays None → joined_table = None; if it annotates labels and shapes, all rows for the labels are dropped. Labels {1,2,3,4}, table ids [1, 2, 9]: how="inner", filter_label_pixels=True → labels filtered to {1, 2} but table None (expected ids [1, 2]).

Severity (agent's assessment): medium — match_sdata_to_table(how="inner") / filter_by_table_query(how="inner") on labels-annotating tables then crash in TableModel.parse(None, ...)

Where: src/spatialdata/_core/query/relational_query.py::_inner_join_spatialelement_table (labels branch continues before _get_joined_table_indices)

Expected behaviour

Inner join filters both sides: labels to {1, 2}, table to instance ids [1, 2].

Reproduction

Save as repro.py and run uv run repro.py (the PEP 723 header pins spatialdata to the commit the bug was found on; replace the URL fragment with @main to test the current main branch).

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "spatialdata @ git+https://github.com/scverse/spatialdata.git@ccf1ea048d054b6624214bf618008a9f9ae223e0",
# ]
# ///
"""inner join on a labels element returns table=None even with filter_label_pixels=True."""
import warnings
import numpy as np
import pandas as pd
from anndata import AnnData
from spatialdata import SpatialData, join_spatialelement_table
from spatialdata.models import Labels2DModel, TableModel

warnings.simplefilter("ignore")
labels = Labels2DModel.parse(np.array([[0, 1, 1], [2, 2, 3], [4, 4, 0]], dtype=np.uint16))
obs = pd.DataFrame({"region": pd.Categorical(["lab"] * 3), "instance_id": [1, 2, 9]})  # 9 is not in the labels
table = TableModel.parse(AnnData(X=np.zeros((3, 1)), obs=obs), region="lab", region_key="region", instance_key="instance_id")
sdata = SpatialData(labels={"lab": labels}, tables={"t": table})
bug = False
for how in ["left", "inner", "right"]:
    elements, joined = join_spatialelement_table(sdata=sdata, spatial_element_names="lab", table_name="t", how=how, filter_label_pixels=True)
    ids = None if joined is None else joined.obs.instance_id.tolist()
    uniques = np.unique(elements["lab"].data.compute()).tolist()
    print(f"how={how:5s} filter_label_pixels=True -> label ids kept {uniques}, table instance ids {ids}")
    if how == "inner":
        bug = ids != [1, 2]
print("expected for inner: label ids [0, 1, 2] and table instance ids [1, 2]")
print("VERDICT:", "BUG REPRODUCED" if bug else "NOT REPRODUCED")

Observed output

how=left  filter_label_pixels=True -> label ids kept [0, 1, 2, 3, 4], table instance ids [1, 2]
how=inner filter_label_pixels=True -> label ids kept [0, 1, 2], table instance ids None
how=right filter_label_pixels=True -> label ids kept [0, 1, 2], table instance ids [1, 2, 9]
expected for inner: label ids [0, 1, 2] and table instance ids [1, 2]
VERDICT: BUG REPRODUCED

Possible fix direction (unverified)

In the labels branch compute element_indices = get_element_instances(element) and fall through to _get_joined_table_indices (as _left_join_spatialelement_table does) instead of continue.

Environment

uv run repro.py with the PEP 723 metadata in the script (fresh, isolated environment; spatialdata built from main @ ccf1ea0 (2026-08-28); Python 3.13, latest releases of the dependencies at run time: pandas 3.0, anndata 0.13, zarr 3.3, dask 2026.8, numpy 2.5, geopandas 1.1, shapely 2.1). macOS (arm64). Also reproduced in a second environment with pandas 2.3.3 / anndata 0.12.11 / numpy 2.4.4 / zarr 3.2.1.

Automatically generated; discovered by an AI agent (Claude) and not yet reviewed by a human.

Start in src/spatialdata/_core/query/relational_query.py at _inner_join_spatialelement_table and run the supplied repro.py with uv run. Check the labels branch alongside _left_join_spatialelement_table; done means an inner join with filter_label_pixels=True keeps label ids [0, 1, 2] and returns table instance ids [1, 2] rather than None.