Governance gap detection in sespy/network.py

[razinkele]

Source paper: Social–ecological network analysis of governance gaps in a newly designated marine protected area of the Global South, Marine Policy (2026). https://doi.org/10.1016/j.marpol.2026.107169
Alert week: 2026-07-07 (from LITERATURE/2026-07-07.md)

Motivation

Social-ecological network analysis (SENA) identifies governance gaps — situations where ecological units (habitats, resources, processes) are affected by activities but have no corresponding governance actor, or where governance actors exist without a linked ecological target. This is a distinct diagnostic from the already-shipped social_ecological_fit metric (cross-boundary coupling density): SE fit measures how well linked pairs are matched; governance gap detection finds nodes that are unlinked entirely.

The Marine Policy paper demonstrates this on a newly designated MPA, showing that gap detection reveals structural vulnerabilities in governance architecture that aggregate metrics miss. Directly applicable to MarineSABRES SES toolbox users diagnosing governance coverage.

Proposal

Add a governance_gap(g) function to sespy/network.py (alongside social_ecological_fit):

1. Partition nodes into governance (DAPSIWR(M) types: Responses R, Management M) and ecological (State S, Impacts I, Pressures P) using the existing node_type attribute.
2. Detect uncovered ecological nodes: ecological nodes with zero governance-type neighbours in the undirected graph.
3. Detect untargeted governance nodes: governance nodes with zero ecological-type neighbours.
4. Return a dict {ecological_gaps: [...], governance_orphans: [...], gap_fraction: float}.
5. Expose as a new row in the Network Metrics module output table.

Acceptance criteria

• network.governance_gap(g) returns correct ecological_gaps, governance_orphans, and gap_fraction on a synthetic test graph
• Result is surfaced in the Network Metrics Shiny module as a labelled row
• Function handles graphs with no typed nodes gracefully (returns empty lists, gap_fraction=NaN)
• Docstring references the SENA governance-gap concept

Effort

Small–Medium (one new function ~30 LOC + module wiring).