fix: raise clear error on disjoint instance IDs in render_shapes

Closes #603.

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

Author: SAY-5

src/spatialdata_plot/pl/render.py

@@ -345,6 +345,18 @@ def _render_shapes(
         if _saved_index_name is not None and _saved_index_name in _obs.columns:
             _obs.index.name = None
 
+        # Guard against a disjoint instance_key (#603): when no table rows annotate any element
+        # row, the upstream join crashes with `KeyError: None` from deep inside pandas.  Raise
+        # a clear, actionable ValueError before invoking the join.
+        _, _region_key, _instance_key = get_table_keys(sdata[table_name])
+        _annotating = sdata[table_name].obs[sdata[table_name].obs[_region_key].isin([element])]
+        if len(_annotating) > 0 and set(_annotating[_instance_key]).isdisjoint(set(sdata[element].index)):
+            raise ValueError(
+                f"No instance IDs overlap between table '{table_name}' (instance_key='{_instance_key}') "
+                f"and element '{element}'. Check that the table's '{_instance_key}' column matches the "
+                f"element's index."
+            )
+
         try:
             element_dict, joined_table = join_spatialelement_table(
                 sdata, spatial_element_names=element, table_name=table_name, how="inner"

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.