fix: clear error on disjoint instance IDs in render_shapes/labels/points

Closes #603.

Signed-off-by: SAY-5 <say.apm35@gmail.com>

Author: SAY-5

src/spatialdata_plot/pl/render.py

@@ -311,6 +311,27 @@ def _add_legend_and_colorbar(
     )
 
 
+def _check_instance_ids_overlap(
+    sdata: sd.SpatialData,
+    table_name: str,
+    element_name: str,
+    element_index: abc.Iterable[Any],
+) -> None:
+    """Raise a clear error when a table annotates an element but no instance IDs overlap (#603).
+
+    Without this guard the downstream join/lookup crashes with an opaque ``KeyError: None`` from
+    deep inside pandas, giving no hint that the ``instance_key`` value sets are disjoint.
+    """
+    _, region_key, instance_key = get_table_keys(sdata[table_name])
+    annotating = sdata[table_name].obs[sdata[table_name].obs[region_key].isin([element_name])]
+    if len(annotating) > 0 and set(annotating[instance_key]).isdisjoint(set(element_index)):
+        raise ValueError(
+            f"No instance IDs overlap between table '{table_name}' (instance_key='{instance_key}') "
+            f"and element '{element_name}'. Check that the table's '{instance_key}' column matches the "
+            f"element's index."
+        )
+
+
 def _render_shapes(
     sdata: sd.SpatialData,
     render_params: ShapesRenderParams,
@@ -336,6 +357,10 @@ def _render_shapes(
         table = None
         shapes = sdata_filt[element]
     else:
+        # Guard against a disjoint instance_key (#603) *before* mutating obs.index.name below,
+        # so a failure here can never leave the index name in a half-restored state.
+        _check_instance_ids_overlap(sdata, table_name, element, sdata[element].index)
+
         # Workaround for upstream spatialdata bug (scverse/spatialdata#1099):
         # join_spatialelement_table calls table.obs.reset_index() which fails when
         # the obs index name matches an existing column (e.g. "EntityID" in Merfish data).
@@ -742,6 +767,10 @@ def _render_points(
 
     added_color_from_table = False
     if col_for_color is not None and col_for_color not in points.columns:
+        if table_name is not None:
+            # Guard against disjoint instance IDs (#603): without this the table lookup below
+            # crashes with an opaque `KeyError: None` instead of explaining the mismatch.
+            _check_instance_ids_overlap(sdata, table_name, element, points.index)
         color_values = get_values(
             value_key=col_for_color,
             sdata=sdata_filt,
@@ -1651,6 +1680,7 @@ def _render_labels(
         instance_id = np.unique(label)
         table = None
     else:
+        _check_instance_ids_overlap(sdata, table_name, element, np.unique(label.values))
         _, region_key, instance_key = get_table_keys(sdata[table_name])
         table = sdata[table_name][sdata[table_name].obs[region_key].isin([element])]
 

tests/pl/test_render_labels.py

@@ -490,3 +490,34 @@ def test_render_labels_rejects_float_dtype(dtype):
             sdata.pl.render_labels("lbl").pl.show(ax=ax)
     finally:
         plt.close(fig)
+
+
+def test_render_labels_disjoint_instance_ids_clear_error():
+    # Regression test for #603: when a table annotates the label (region key matches) but no
+    # instance_id values overlap with the label IDs, the call used to crash with a bare
+    # `KeyError: None` from deep inside spatialdata.  Replace with a clear ValueError.
+    arr = np.zeros((20, 20), dtype=np.int32)
+    arr[3:8, 3:8] = 1
+    arr[12:17, 12:17] = 2
+    obs = pd.DataFrame(
+        {
+            "instance_id": [99, 100],  # label has IDs 1, 2 -- no overlap
+            "region": pd.Categorical(["lbl"] * 2),
+            "cat": pd.Categorical(["A", "B"]),
+        }
+    )
+    obs.index = obs.index.astype(str)
+    table = TableModel.parse(
+        AnnData(X=np.zeros((2, 1)), obs=obs),
+        region=["lbl"],
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata = SpatialData(labels={"lbl": Labels2DModel.parse(arr, dims=["y", "x"])}, tables={"t": table})
+
+    fig, ax = plt.subplots()
+    try:
+        with pytest.raises(ValueError, match=r"No instance IDs overlap.*table 't'.*element 'lbl'"):
+            sdata.pl.render_labels("lbl", color="cat", table_name="t").pl.show(ax=ax)
+    finally:
+        plt.close(fig)

tests/pl/test_render_points.py

@@ -1004,3 +1004,32 @@ def test_no_table_fallback_warning_for_element_column(caplog):
     with logger_no_warns(caplog, logger, match="fallback for color mapping"):
         sdata.pl.render_points("pts", color="cell_type").pl.show()
     plt.close("all")
+
+
+def test_render_points_disjoint_instance_ids_clear_error():
+    # Regression test for #603: when a table annotates the points (region key matches) but no
+    # instance_id values overlap with the points index, the table lookup used to crash with a
+    # bare `KeyError: None` from deep inside spatialdata.  Replace with a clear ValueError.
+    points = PointsModel.parse(pd.DataFrame({"x": [1.0, 2.0, 3.0], "y": [1.0, 2.0, 3.0]}))
+    obs = pd.DataFrame(
+        {
+            "instance_id": [99, 100, 101],  # points index is 0, 1, 2 -- no overlap
+            "region": pd.Categorical(["pts"] * 3),
+            "cat": pd.Categorical(["A", "B", "C"]),
+        }
+    )
+    obs.index = obs.index.astype(str)
+    table = TableModel.parse(
+        AnnData(X=np.zeros((3, 1)), obs=obs),
+        region=["pts"],
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata = SpatialData(points={"pts": points}, tables={"t": table})
+
+    fig, ax = plt.subplots()
+    try:
+        with pytest.raises(ValueError, match=r"No instance IDs overlap.*table 't'.*element 'pts'"):
+            sdata.pl.render_points("pts", color="cat", table_name="t").pl.show(ax=ax)
+    finally:
+        plt.close(fig)

tests/pl/test_render_shapes.py

@@ -1323,6 +1323,39 @@ def test_render_shapes_color_with_conflicting_index_name():
     sdata.pl.render_shapes("shapes", color="cell_type", table_name="table").pl.show()
 
 
+def test_render_shapes_disjoint_instance_ids_clear_error():
+    # Regression test for #603: when a table annotates the element (region key matches) but no
+    # instance_id values overlap, the call used to crash with a bare `KeyError: None` from deep
+    # inside spatialdata's join path.  Replace with a clear, actionable ValueError.
+    from shapely.geometry import Point
+
+    shapes = ShapesModel.parse(
+        gpd.GeoDataFrame({"geometry": [Point(5, 5), Point(15, 5), Point(25, 5)], "radius": [2.0] * 3})
+    )
+    obs = pd.DataFrame(
+        {
+            "instance_id": [99, 100, 101],  # element has IDs 0, 1, 2 -- no overlap
+            "region": pd.Categorical(["s"] * 3),
+            "cat": pd.Categorical(["A", "B", "C"]),
+        }
+    )
+    obs.index = obs.index.astype(str)
+    table = TableModel.parse(
+        AnnData(X=np.zeros((3, 1)), obs=obs),
+        region=["s"],
+        region_key="region",
+        instance_key="instance_id",
+    )
+    sdata = SpatialData(shapes={"s": shapes}, tables={"t": table})
+
+    fig, ax = plt.subplots()
+    try:
+        with pytest.raises(ValueError, match=r"No instance IDs overlap.*table 't'.*element 's'"):
+            sdata.pl.render_shapes("s", color="cat", table_name="t").pl.show(ax=ax)
+    finally:
+        plt.close(fig)
+
+
 def test_datashader_colorbar_range_matches_data(sdata_blobs: SpatialData):
     """Datashader colorbar range must not exceed the actual data range for shapes.