Network Readiness and Diagnostics

Purpose

Network Readiness and Diagnostics validates network topology and connectivity, identifies missing edges/nodes, and rates overall network quality and fitness for routing analysis.

Typical Questions This Tool Helps Answer

• Is this network ready for routing and optimization, or do data-quality issues make results unreliable?
• Where are the key topology defects (dead ends, disconnected components, broken continuity) that need correction?
• Does the current dataset pass readiness gates for production decision workflows?

Background

Network readiness diagnostics assess whether a transport graph is fit for optimization and scenario analysis. In a weighted graph $G=(V,E,w)$, path cost is typically:

$$c(P)=\sum_{e\in P} w(e)$$

So missing or inconsistent impedance attributes directly bias travel-time, accessibility, and optimization outcomes.

Readiness Dimensions

• Topological validity: connectivity, dangling structures, disconnected components, turn-model consistency.
• Impedance completeness: travel-time/speed consistency, directional restrictions, temporal rule coverage.
• Operational expressiveness: representation of capacities, time windows, closures, and policy constraints.

Diagnostic Metrics and Decision Use

A practical readiness approach combines structural metrics (for example component count, invalid edge ratio) with operational metrics (for example constrained-route solvability rate). The objective is not only data correctness, but decision stability under realistic operating assumptions.

Methodological Considerations

• Run diagnostics before optimization; post-hoc quality checks are far more expensive.
• Track metric drift across data refreshes to detect silent regression in network quality.
• Include stress scenarios (closure sets, demand spikes) to evaluate robustness of the modeled rules.

Practical Interpretation Pitfalls

Passing a single QA indicator can hide major operational blind spots. Readiness should be judged as a composite gate, not a one-metric pass/fail.

Inputs

Input Requirements

• network must contain line geometries (LineString or MultiLineString).
• If CRS is known, projected CRS is required for reliable geometric diagnostics.
• Networks with no usable vertices fail fast.

Parameters

Output Path Behavior

• diagnostics_layer format is inferred from file extension.
• If extension cannot be resolved, writer falls back to GeoJSON.
• Parent directory for diagnostics_layer is created automatically if needed.

Outputs

Runtime output keys (returned in ToolRunResult.outputs):

QA Findings CSV Schema (qa_report)

severity,check_type,count,description,feature_ids_sample

feature_ids_sample is semicolon-delimited in-cell text.

Diagnostics Layer Schema (diagnostics_layer)

Geometry type: Point

Attributes:

• CHECK_TYPE
• SEVERITY
• MESSAGE

Common CHECK_TYPE values:

• dead_end
• disconnected_component
• disconnected_edge

Readiness JSON Schema (readiness_score)

Top-level keys:

• overall_score
• connectivity_score
• cost_consistency_score
• pass_fail_gate
• fragmentation_penalty
• unreachability_penalty
• cost_variance_zscore
• assessment_timestamp
• schema_version

Scoring Logic (Current Implementation)

The current implementation computes:

• Connected-component structure from network topology
• Dead-end node counts
• Cost-consistency outliers from geometric segment-length variance

Current score formula:

$$ \text{connectivity_score} = 100,(1 - p_f - p_u) $$

$$ \text{cost_consistency_score} = 100,\left(1 - \min\left(\frac{z}{5},1\right)\right) $$

$$ \text{overall_score} = 0.6,\text{connectivity_score} + 0.4,\text{cost_consistency_score} $$

Where:

• $p_f$ is fragmentation_penalty
• $p_u$ is unreachability_penalty
• $z$ is cost_variance_zscore

Pass/fail gate is true only when all conditions are met:

• overall_score >= 80
• fragmentation_penalty < 0.1
• unreachability_penalty < 0.05

Example

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()
wbe.network_readiness_and_diagnostics_intelligence(
        network="road_network.shp",
        qa_report="out/network_readiness_findings.csv",
        diagnostics_layer="out/network_readiness_diagnostics.geojson",
        readiness_score="out/network_readiness_score.json",
        html_report="out/network_readiness_report.html"
)

Any WbEnvironment instance name is valid (wbe above is only an example).

References

• Rigaux, P., Scholl, M. O., & Voisard, A. (2002). Spatial Databases with Application to GIS. Morgan Kaufmann.

Parameter Interaction Notes

For Network Readiness and Diagnostics, output quality is most sensitive to parameter combinations rather than single values in isolation.

• Small disconnected subnetworks can sharply reduce pass/fail status even when most of the network is visually complete.
• Dense cul-de-sac neighborhoods increase dead-end diagnostics; treat these as context-sensitive, not automatically incorrect.
• Very uneven segment-length distributions increase cost_variance_zscore and depress cost_consistency_score.

QA and Acceptance Criteria

Use a staged acceptance approach for Network Readiness and Diagnostics:

1. Input integrity: validate projected CRS, line geometry type, and non-empty network extent.
2. Method validity: verify expected dead-end and disconnected-area diagnostics against known weak zones.
3. Output plausibility: confirm diagnostics layer aligns spatially with topology defects.
4. Reproducibility: rerun with identical inputs and confirm stable findings and score outputs.

Recommended acceptance checks:

• qa_report exists and includes header row plus expected check types.
• diagnostics_layer contains features when known defects are present.
• readiness_score includes all documented keys.
• Pass/fail gate matches expected policy for known-good and known-bad test networks.

Advanced Operational Guidance

For production deployment of Network Readiness and Diagnostics:

• Maintain a versioned readiness policy (score thresholds and remediation SLA).
• Store run metadata with input hashes, parameter JSON, and timestamp for auditability.
• Gate downstream routing/service-area tools on pass_fail_gate where governance requires it.
• Track recurring disconnected components to prioritize durable network editing backlogs.

Implementation Patterns

Common implementation patterns with Network Readiness and Diagnostics:

• Baseline run: score the current authoritative network snapshot.
• Remediation run: fix flagged defects and rerun readiness scoring.
• Release gate run: require pass before publishing operational route products.
• Monitoring run: rerun after network updates or quarterly governance checkpoints.

Related Tools

Use Network Readiness and Diagnostics 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

Network Readiness and Diagnostics is most valuable when teams need reliable routing and coverage outputs backed by an auditable network QA gate.

What this workflow helps you achieve:

• Converts topology quality into a measurable go/no-go readiness decision.
• Reduces false confidence in downstream routing analyses.
• Creates a repeatable QA cycle for network maintenance governance.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Verify readiness scoring and pass/fail gate against agreed thresholds.
3. Document each finding class and remediation owner.
4. Provide before/after scores for remediated network versions.
5. Include at least one known-defect regression case in acceptance evidence.

Common Questions

Q: Why did the readiness score drop even though we only edited a small area?
A: A small disconnected edit can increase both fragmentation and unreachability penalties, which heavily influence the overall score and gate.

Q: Why are we seeing many dead-end warnings in suburban neighborhoods?
A: Dead-end checks are structural and include cul-de-sacs; treat them as review flags, then classify valid cul-de-sacs separately from true data defects.

Q: Does this tool use our travel-time impedance field directly?
A: Current implementation derives cost-consistency from geometric segment-length variance; if policy requires impedance-field QA, pair this with dedicated impedance validation tooling.