Sankey Diagram Conservation and Geometry Gate Verification in Diagram-Design

Diagram-Design verifies Sankey diagrams by enforcing flow conservation (ensuring incoming values equal outgoing values) and validating geometry gates (confirming polygons are closed, non-self-intersecting, and correctly aligned) to guarantee both data accuracy and visual integrity.

The Diagram-Design repository provides robust verification utilities that ensure generated diagrams meet strict visual and data-integrity standards. Sankey diagram conservation and geometry gate verification serve as critical quality gates within this toolchain, preventing misleading visualizations and malformed geometries from reaching production environments.

Architecture of Sankey Verification

The verification system splits responsibilities across specialized modules to promote reusability and maintainability across the codebase.

Core Verification Components

• scripts/verify-sankey.py: The main entry point that parses diagram JSON, computes source-to-target flow totals, and validates SVG-like gate geometries. It raises errors when conservation rules are violated or when gate polygons fail geometric constraints.

• scripts/verify-geometry.py: A shared geometry engine supplying reusable functions like is_polygon_valid and gate_alignment_ok. This module ensures a single source of truth for geometric correctness across all diagram types, including ridgeline and polar charts.

• scripts/verify-plugin-package.py: Validates that the Sankey verification script is properly bundled in the published plugin package with all dependencies declared in package.json.

• commands/doctor.md: Powers the diagram-design doctor CLI command, which aggregates verification results including Sankey-specific flow and geometry warnings.

The Four-Step Verification Pipeline

According to the source code in scripts/verify-sankey.py, the validation process follows this strict sequence:

1. Input Acquisition: The validator receives a JSON diagram description in the standard Diagram-Design format.

2. Flow-Conservation Check: For each node, incoming and outgoing edge values are summed. If the difference exceeds epsilon (1e-6), an error is recorded.

3. Geometry Gate Check: Using helpers from verify-geometry.py, the script confirms each gate polygon has a closed path (first_point == last_point), contains no self-intersections, and aligns orthogonally with the node's flow direction via gate_alignment_ok.

4. Reporting: Violations print to STDOUT and trigger a non-zero exit status for CI pipeline integration.

Why Conservation and Geometry Verification Matters

Preventing Data Misrepresentation

Sankey diagrams visualize quantitative flows. When conservation fails—showing more outgoing than incoming value—the diagram implies energy loss or creation that never occurred. The 1e-6 epsilon tolerance in scripts/verify-sankey.py catches floating-point drift while maintaining strict numerical accountability.

Protecting Rendering Integrity

Malformed geometry gates—such as self-intersecting polygons or open paths—break rendering engines, producing artifacts or invisible flows. The geometry validation in scripts/verify-geometry.py protects downstream processes like SVG export and Mermaid conversion by ensuring gate polygons are mathematically sound before rendering begins.

Implementation Examples

Manual CLI Verification

# Verify a specific Sankey diagram

diagram-design verify-sankey ./my-sankey.json

Successful validation exits with status 0 and prints:

✅ Sankey diagram passed all checks

Failure scenarios report specific errors:

❌ Flow conservation error on node “Manufacturing”: 
   incoming = 1250.0, outgoing = 1248.9 (Δ = 1.1)
❌ Geometry gate error on edge “Coal → Electricity”: 
   gate polygon is self-intersecting

CI/CD Pipeline Integration

# .github/workflows/ci.yml

jobs:
  diagram-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Diagram-Design
        run: pip install -e .
      - name: Verify Sankey diagrams
        run: |
          for file in diagrams/**/*.json; do
            diagram-design verify-sankey "$file"
          done

The workflow aborts on any non-zero exit, treating malformed diagrams as merge-blocking failures.

Programmatic Python API

from diagram_design.sankey import verify_sankey
import json

with open("my-sankey.json") as fp:
    diagram = json.load(fp)

issues = verify_sankey(diagram)
if issues:
    for error in issues:
        print(error)
    raise SystemExit(1)
print("All Sankey checks passed.")

The verify_sankey function returns a list of human-readable error strings, providing a thin wrapper around the CLI logic for custom automation scripts.

Summary

• Flow conservation in scripts/verify-sankey.py ensures incoming and outgoing values match within a 1e-6 epsilon, preventing misleading quantitative visualizations.
• Geometry gate verification validates that Sankey polygons are closed, non-self-intersecting, and properly aligned using shared utilities from scripts/verify-geometry.py.
• The modular architecture separates concerns between data validation (verify-sankey.py), geometric calculations (verify-geometry.py), and packaging (verify-plugin-package.py).
• Integration options include direct CLI usage, CI/CD pipelines via exit codes, and Python API imports for programmatic workflows.

Frequently Asked Questions

What is flow conservation in Sankey diagrams?

Flow conservation requires that the total value entering a node equals the total value leaving it. In scripts/verify-sankey.py, this calculation sums all incoming edge values and compares them against outgoing sums, raising an error if the difference exceeds the floating-point epsilon of 1e-6.

How does Diagram-Design detect self-intersecting gate polygons?

The scripts/verify-geometry.py module implements an is_polygon_self_intersecting check that analyzes the gate's path data. This function verifies that the polygon's edges do not cross each other and that the path closes properly (first_point == last_point), which scripts/verify-sankey.py calls during the geometry gate verification phase.

What exit codes does the Sankey verifier return?

The verifier exits with status 0 when all checks pass. Any flow conservation violation or geometry gate error triggers a non-zero exit status, specifically designed to fail CI/CD pipelines and prevent merges of invalid diagrams.

Can the geometry verification utilities handle other diagram types?

Yes. The scripts/verify-geometry.py module provides reusable functions like is_polygon_valid and gate_alignment_ok that support multiple diagram validators including ridgeline and polar charts. Improvements to this shared module automatically benefit all dependent diagram types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}