fix: render shapes unannotated by the table with na_color instead of dropping them (#710)

render_shapes joined the element to its table with how="inner", silently dropping shapes whose
instance had no table row. Points (how="left" merge) and labels (raster + na_color) keep unannotated
elements, so shapes were the inconsistent outlier (and it broke the labels<->shapes interchangeability).

Switch _join_table_for_element to how="left": all shapes survive, and the per-shape color lookup
(_extract_color_column, reindexed to the element) yields NaN -> na_color for the unannotated ones, via
the existing NaN-handling path. Fully-annotated data is unaffected (verified pixel-identical: inner == left
when nothing is dropped), so only partial-annotation output changes.

Adds a regression test (fails on the old drop behavior: 12/20 rendered; passes now: 20/20 with 8 na_color).

Author: timtreis

src/spatialdata_plot/pl/render.py

@@ -646,7 +646,7 @@ def _render_shapes(
     outline_color_vector: Any = None
     if col_for_outline_color is not None:
         # When the outline column lives in a table that hasn't been joined yet
-        # (no fill table, or a different table than fill's), inner-join it onto
+        # (no fill table, or a different table than fill's), left-join it onto
         # the element so the lookup is aligned and the element row count matches
         # the outline vector length.
         if outline_table_name is not None and outline_table_name != table_name:

src/spatialdata_plot/pl/utils.py

@@ -444,7 +444,11 @@ def _join_table_for_element(
     element: str,
     table_name: str,
 ) -> tuple[Any, AnnData]:
-    """Inner-join ``element`` with its annotating ``table_name``.
+    """Left-join ``element`` with its annotating ``table_name``.
+
+    A left join keeps every shape, including those without a table row (they get no color value and
+    are rendered with ``na_color``), matching the points/labels behaviour instead of silently dropping
+    unannotated shapes.
 
     Wraps the workaround for scverse/spatialdata#1099: ``join_spatialelement_table``
     calls ``table.obs.reset_index()`` which fails when the obs index name matches
@@ -470,7 +474,7 @@ def _join_table_for_element(
 
     try:
         element_dict, joined_table = join_spatialelement_table(
-            sdata, spatial_element_names=element, table_name=table_name, how="inner"
+            sdata, spatial_element_names=element, table_name=table_name, how="left"
         )
     finally:
         if _saved_index is not None:

tests/pl/test_render_shapes.py

@@ -9,7 +9,7 @@
 import pytest
 import scanpy as sc
 from anndata import AnnData
-from matplotlib.colors import Normalize
+from matplotlib.colors import Normalize, to_rgba
 from shapely.geometry import MultiPolygon, Point, Polygon
 from spatialdata import SpatialData, deepcopy
 from spatialdata.models import ShapesModel, TableModel
@@ -439,6 +439,32 @@ def test_render_shapes_raises_for_missing_column_in_table(self, sdata_blobs_shap
                 element="blobs_polygons", color="not_a_column", table_name="table"
             )
 
+    def test_render_shapes_unannotated_shapes_get_na_color_not_dropped(self):
+        # Regression test for #710: shapes whose instance is not in the annotating table must render
+        # with na_color, not be silently dropped (consistent with the points/labels paths).
+        rng = np.random.default_rng(0)
+        n = 20
+        geom = gpd.GeoDataFrame(
+            {"geometry": [Point(*xy) for xy in rng.random((n, 2)) * 100], "radius": np.ones(n) * 2},
+        )
+        adata = AnnData(  # only the first 12 of 20 shapes are annotated
+            X=rng.random((12, 1)).astype("float32"),
+            obs=pd.DataFrame({"region": pd.Categorical(["shapes"] * 12), "instance_id": np.arange(12), "val": rng.random(12)}),
+        )
+        adata.var_names = ["g0"]
+        sdata = SpatialData(
+            shapes={"shapes": ShapesModel.parse(geom)},
+            tables={"t": TableModel.parse(adata, region="shapes", region_key="region", instance_key="instance_id")},
+        )
+        fig, ax = plt.subplots()
+        sdata.pl.render_shapes("shapes", color="val", na_color="red").pl.show(ax=ax)
+        fig.canvas.draw()
+        facecolors = ax.collections[0].get_facecolors()
+        plt.close(fig)
+        assert len(facecolors) == n, f"expected all {n} shapes rendered, got {len(facecolors)} (unannotated dropped)"
+        n_na = int(np.isclose(facecolors, to_rgba("red")).all(axis=1).sum())
+        assert n_na == 8, f"expected 8 unannotated shapes in na_color, got {n_na}"
+
     def test_plot_can_plot_shapes_after_spatial_query(self, sdata_blobs: SpatialData):
         # subset to only shapes, should be unnecessary after rasterizeation of multiscale images is included
         blob = SpatialData.init_from_elements(