Route Event Governance

Purpose

Route Event Governance establishes and manages a linear referencing system (LRS) for route networks, enables attribute management using route/measure location, and provides tools for asset inventory, lifecycle tracking, and spatiotemporal querying of linear assets (poles, segments, intersections).

Typical Questions This Tool Helps Answer

• Where do route events contain gaps, overlaps, or invalid measure direction that break LRS consistency?
• Which event records violate attribute domain or policy rules?
• What portion of event issues can be auto-corrected versus escalated for manual governance review?

Background

Network planning workflows use graph-theoretic representations of roads, routes, or linear assets, where node-edge topology and impedance attribution directly control results. Missing restrictions, incorrect turn logic, or stale demand assumptions can dominate outcome quality.

These tools are best interpreted as constrained optimization and diagnostics frameworks. Decisions should be based on trade-offs across service, resilience, and cost objectives rather than any single metric.

Route-event governance formalizes linear referencing events with temporal and spatial consistency controls. Strong governance depends on reproducible event segmentation and audit-grade lineage.

Methodological Considerations

• Topology validation should precede optimization or scenario simulation.
• Explicitly represent operational constraints (time windows, restrictions, capacities, closures) before comparing objective outcomes.
• Test outcomes under stress scenarios so selected plans remain stable under realistic disruptions.

Practical Interpretation Pitfalls

Single-metric improvements can hide degraded resilience or equity; compare candidate plans across multiple KPIs and scenario conditions.

Inputs

Parameters

• gap_tolerance (optional): gap size below this value is ignored; default 0.0.
• overlap_tolerance (optional): overlap size below this value is ignored; default 0.0.
• auto_fix (optional): if true, fix descending intervals and trim overlaps when possible.
• domain_rules_json (optional): per-field domain policy file.
• governed_events (required): output path for governed events.
• issues_csv (required): output path for issue log.
• corrected_events (optional): output path for corrected records.
• governance_report (required): output path for governance summary JSON.
• remediation_queue_csv (optional): output path for prioritized remediation queue.
• html_report (optional): output path for HTML summary.

Domain Rules JSON (Optional)

Per-field rules can include:

• allowed_values
• regex
• min
• max

Violations are reported as domain_validation issues.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

governed_events added fields

• GOVERNANCE_STATUS: PASSED or CORRECTED
• CORRECTIONS: none, descending_fix, overlap_trim, or descending_fix+overlap_trim

issues_csv schema

event_id,route_id,rule_violated,severity,description,measure_start,measure_end

remediation_queue_csv schema

priority,event_id,route_id,rule_violated,severity,recommended_action

governance_report keys

• total_events
• passed_events
• failed_events
• pass_rate_percent
• rules_violated
• severity_distribution
• correctable_count
• domain_rules_applied

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.route_event_governance_for_linear_assets(
        events="route_events.gpkg",
        route_id_field="route_id",
        from_measure_field="from_m",
        to_measure_field="to_m",
        auto_fix=True,
        domain_rules_json="domain_rules.json",
        governed_events="outputs/governed_events.gpkg",
        issues_csv="outputs/issues.csv",
        corrected_events="outputs/corrected_events.gpkg",
        governance_report="outputs/governance_report.json",
        remediation_queue_csv="outputs/remediation_queue.csv",
        html_report="outputs/governance_report.html"
)

References

• OGC (Open Geospatial Consortium) Linear Reference Systems Standard

Parameter Interaction Notes

Output strictness depends on tolerance settings and auto-fix policy.

Note: This workflow validates linear-referencing event intervals and does not build a routing graph, so one-way routing parameters (for example one_way_field with FT/TF/B values) are not applicable.

• Tight tolerances catch more defects but may increase noise from minor measure jitter.
• Looser tolerances reduce issue counts but can hide meaningful defects.
• Auto-fix improves throughput for fixable issues, but review is still recommended before publication.

QA and Acceptance Criteria

Use a staged acceptance approach for Route Event Governance:

1. Validate required fields and measure data quality.
2. Validate domain-rules JSON format when used.
3. Confirm issue counts align with known data conditions.
4. Confirm correction outputs match governance expectations.

Recommended acceptance checks:

• passed_events + failed_events equals total_events.
• issues_csv includes all expected issue categories.
• governed_events contains governance status columns.
• corrected_events is present only when correction records exist.

Advanced Operational Guidance

For production deployment of Route Event Governance:

• Treat domain-rules JSON as a governed policy artifact.
• Use remediation queue output for data stewardship backlogs.
• Archive run artifacts (issues_csv, governance_report) for audit trails.

Implementation Patterns

Common implementation patterns with Route Event Governance:

• Compliance scan (auto_fix=false) for strict diagnostics.
• Corrective scan (auto_fix=true) for fast recovery of fixable defects.
• Release-ready scan with frozen rule policy and archived outputs.

Related Tools

Use Route Event Governance together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Route Event Governance is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Why are some events missing from governed output?
A: Error-level failing events are excluded if not fixable (or when auto-fix is off).

Q: Why is corrected output missing?
A: Corrected output is written only when auto_fix=true, a path is supplied, and at least one correction occurs.

Q: How should we interpret CORRECTED status?
A: The event passed after automatic correction; review is still recommended before publication.