Implement render_graph for spatial connectivity visualization

Adds `sdata.pl.render_graph()` to render spatial graph edges from
adjacency matrices stored in table.obsp, using element centroids
for coordinates. Supports shapes, points, and labels elements via
spatialdata.get_centroids().

Key features:
- connectivity_key accepts full obsp key or prefix (auto-resolves)
- element and table_name auto-discovered when unambiguous
- groups + group_key filtering (both-endpoints semantics)
- Rasterized LineCollection for performance
- No networkx dependency (direct sparse matrix to line segments)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -31,6 +31,7 @@
 from spatialdata_plot._logging import _log_context, logger
 from spatialdata_plot.pl.render import (
     _draw_channel_legend,
+    _render_graph,
     _render_images,
     _render_labels,
     _render_points,
@@ -44,6 +45,7 @@
     ChannelLegendEntry,
     CmapParams,
     ColorbarSpec,
+    GraphRenderParams,
     ImageRenderParams,
     LabelsRenderParams,
     LegendParams,
@@ -63,6 +65,7 @@
     _prepare_cmap_norm,
     _prepare_params_plot,
     _set_outline,
+    _validate_graph_render_params,
     _validate_image_render_params,
     _validate_label_render_params,
     _validate_points_render_params,
@@ -861,6 +864,82 @@ def render_labels(
             n_steps += 1
         return sdata
 
+    def render_graph(
+        self,
+        element: str | None = None,
+        color: ColorLike | None = "grey",
+        *,
+        connectivity_key: str = "spatial",
+        groups: list[str] | str | None = None,
+        group_key: str | None = None,
+        edge_width: float = 1.0,
+        edge_alpha: float = 1.0,
+        table_name: str | None = None,
+        **kwargs: Any,
+    ) -> sd.SpatialData:
+        """Render spatial graph edges between observations.
+
+        Draws edges from a connectivity matrix stored in a table's ``obsp``,
+        using centroid coordinates of the linked spatial element.
+
+        Parameters
+        ----------
+        element : str | None, optional
+            Name of the spatial element (shapes, points, or labels) whose
+            observations the graph connects. Auto-resolved from the table
+            if not given.
+        color : ColorLike | None, default "grey"
+            Edge color as a color-like value (e.g. ``"red"``, ``"#aabbcc"``).
+        connectivity_key : str, default "spatial"
+            Key prefix in ``table.obsp``. Tries ``obsp[key]`` first, then
+            ``obsp[f"{key}_connectivities"]``.
+        groups : list[str] | str | None, optional
+            Show only edges where **both** endpoints belong to the specified
+            groups. Requires ``group_key``.
+        group_key : str | None, optional
+            Column in ``table.obs`` used for group filtering.
+        edge_width : float, default 1.0
+            Line width for edges.
+        edge_alpha : float, default 1.0
+            Transparency for edges (0 = invisible, 1 = opaque).
+        table_name : str | None, optional
+            Table containing the graph. Auto-discovered if not given.
+        **kwargs
+            Forwarded to :class:`matplotlib.collections.LineCollection`.
+
+        Returns
+        -------
+        sd.SpatialData
+            Copy with rendering parameters stored in the plotting tree.
+        """
+        params = _validate_graph_render_params(
+            self._sdata,
+            element=element,
+            connectivity_key=connectivity_key,
+            table_name=table_name,
+            color=color,
+            edge_width=edge_width,
+            edge_alpha=edge_alpha,
+            groups=groups,
+            group_key=group_key,
+        )
+
+        sdata = self._copy()
+        sdata = _verify_plotting_tree(sdata)
+        n_steps = len(sdata.plotting_tree.keys())
+        sdata.plotting_tree[f"{n_steps + 1}_render_graph"] = GraphRenderParams(
+            element=params["element"],
+            connectivity_key=params["obsp_key"],
+            table_name=params["table_name"],
+            color=params["color"],
+            groups=params["groups"],
+            group_key=params["group_key"],
+            edge_width=params["edge_width"],
+            edge_alpha=params["edge_alpha"],
+            zorder=n_steps,
+        )
+        return sdata
+
     def show(
         self,
         coordinate_systems: list[str] | str | None = None,
@@ -1001,6 +1080,7 @@ def show(
             "render_shapes",
             "render_labels",
             "render_points",
+            "render_graph",
         ]
 
         # prepare rendering params
@@ -1311,6 +1391,23 @@ def _draw_colorbar(
                             rasterize=rasterize,
                         )
 
+                elif cmd == "render_graph":
+                    # Graph rendering: resolve which element the graph connects,
+                    # check if that element exists in this CS.
+                    graph_element = params_copy.element
+                    element_in_cs = (
+                        (graph_element in sdata.shapes and has_shapes)
+                        or (graph_element in sdata.points and has_points)
+                        or (graph_element in sdata.labels and has_labels)
+                    )
+                    if element_in_cs:
+                        _render_graph(
+                            sdata=sdata,
+                            render_params=params_copy,
+                            coordinate_system=cs,
+                            ax=ax,
+                        )
+
                 if title is None:
                     t = cs
                 elif len(title) == 1:

src/spatialdata_plot/pl/render.py

@@ -49,6 +49,7 @@
     Color,
     ColorbarSpec,
     FigParams,
+    GraphRenderParams,
     ImageRenderParams,
     LabelsRenderParams,
     LegendParams,
@@ -1815,3 +1816,117 @@ def _draw_labels(
         scalebar_units=scalebar_params.scalebar_units,
         # scalebar_kwargs=scalebar_params.scalebar_kwargs,
     )
+
+
+def _render_graph(
+    sdata: sd.SpatialData,
+    render_params: GraphRenderParams,
+    coordinate_system: str,
+    ax: matplotlib.axes.SubplotBase,
+    **kwargs: Any,
+) -> None:
+    """Render spatial graph edges as a LineCollection on the given axes."""
+    from matplotlib.collections import LineCollection
+    from scipy.sparse import triu
+
+    _log_context.set("render_graph")
+    element_name = render_params.element
+    table_name = render_params.table_name
+
+    # Get table and adjacency matrix
+    table = sdata[table_name]
+    obsp_key = render_params.connectivity_key
+    # _validate_graph_render_params already resolved the actual obsp key,
+    # but we stored the prefix in render_params — re-resolve here
+    if obsp_key not in table.obsp:
+        suffixed = f"{obsp_key}_connectivities"
+        if suffixed in table.obsp:
+            obsp_key = suffixed
+        else:
+            logger.warning(f"Connectivity key '{obsp_key}' not found in table obsp. Skipping graph rendering.")
+            return
+
+    adjacency = table.obsp[obsp_key]
+
+    # Get the spatial element
+    if element_name in sdata.shapes:
+        element = sdata.shapes[element_name]
+    elif element_name in sdata.points:
+        element = sdata.points[element_name]
+    elif element_name in sdata.labels:
+        element = sdata.labels[element_name]
+    else:
+        logger.warning(f"Element '{element_name}' not found in sdata. Skipping graph rendering.")
+        return
+
+    # Get centroids in the target coordinate system
+    centroids_df = sd.get_centroids(element, coordinate_system=coordinate_system)
+    if hasattr(centroids_df, "compute"):
+        centroids_df = centroids_df.compute()
+
+    centroid_coords = np.column_stack([centroids_df["x"].values, centroids_df["y"].values])
+
+    # Align table observations to centroid positions
+    # The table's instance_key maps obs rows to spatial element instances.
+    # Centroids are ordered by element instance (e.g., label ID or GeoDataFrame index).
+    _, region_key, instance_key = get_table_keys(table)
+
+    # Filter table to only rows annotating this element
+    element_mask = table.obs[region_key] == element_name if region_key is not None else np.ones(table.n_obs, dtype=bool)
+    table_subset_indices = np.where(element_mask)[0]
+    instance_ids = table.obs[instance_key].values[element_mask]
+
+    # Build mapping from instance_id to centroid row index
+    # For shapes/points, centroids follow the GeoDataFrame/DataFrame index order.
+    # For labels, centroids follow unique label IDs (excluding background).
+    centroid_ids = centroids_df.index.values if hasattr(centroids_df, "index") else np.arange(len(centroids_df))
+
+    id_to_centroid_row = {}
+    for row, cid in enumerate(centroid_ids):
+        id_to_centroid_row[cid] = row
+
+    # Map each table obs (that annotates this element) to a centroid coordinate
+    obs_to_coord = {}
+    for table_row, iid in zip(table_subset_indices, instance_ids, strict=True):
+        if iid in id_to_centroid_row:
+            obs_to_coord[table_row] = centroid_coords[id_to_centroid_row[iid]]
+
+    # Apply group filtering
+    groups = render_params.groups
+    group_key = render_params.group_key
+    if groups is not None and group_key is not None:
+        group_values = table.obs[group_key].values
+        group_set = set(groups)
+        obs_in_groups = {idx for idx in obs_to_coord if group_values[idx] in group_set}
+    else:
+        obs_in_groups = set(obs_to_coord.keys())
+
+    # Extract edges from upper triangle (undirected graph — draw each edge once)
+    adj_upper = triu(adjacency, k=0)
+    rows, cols = adj_upper.nonzero()
+
+    # Build line segments for edges where both endpoints are valid
+    segments = []
+    for r, c in zip(rows, cols, strict=True):
+        if r == c:
+            continue  # skip self-loops
+        if r in obs_in_groups and c in obs_in_groups and r in obs_to_coord and c in obs_to_coord:
+            segments.append([obs_to_coord[r], obs_to_coord[c]])
+
+    if not segments:
+        return
+
+    segments_arr = np.array(segments)
+
+    edge_color = render_params.color.get_hex() if render_params.color is not None else "#808080"
+
+    lc = LineCollection(
+        segments_arr,
+        linewidths=render_params.edge_width,
+        colors=edge_color,
+        alpha=render_params.edge_alpha,
+        zorder=render_params.zorder,
+        **kwargs,
+    )
+    lc.set_rasterized(True)
+    ax.add_collection(lc)

src/spatialdata_plot/pl/render_params.py

@@ -307,3 +307,18 @@ class LabelsRenderParams:
     zorder: int = 0
     colorbar: bool | str | None = "auto"
     colorbar_params: dict[str, object] | None = None
+
+
+@dataclass
+class GraphRenderParams:
+    """Graph render parameters."""
+
+    element: str
+    connectivity_key: str = "spatial"
+    table_name: str | None = None
+    color: Color | None = None
+    groups: list[str] | str | None = None
+    group_key: str | None = None
+    edge_width: float = 1.0
+    edge_alpha: float = 1.0
+    zorder: int = 0