How the early-warning calculation works

Model structure

Score = Σ(wᵢ × componentᵢ) / Σ(wᵢ available) + concurrence bonus

Each component is bounded to 0–100. If a source is unavailable, its weight is excluded and remaining weights are renormalized. A failed component may retain its last validated value for no more than 72 hours and is visibly marked retained.

1. AIS flow components

IMF PortWatch derives daily port and chokepoint activity from Automatic Identification System messages. The model evaluates 12 high-activity ports and eight high-activity maritime passages.

Δ = 100 × (mean[xₜ₋₆ … xₜ] / mean[xₜ₋₃₄ … xₜ₋₇] − 1)
pressure = clamp((|Δ| − 5) / 35 × 100, 0, 100)

The transformation is two-sided: an unusual surge can indicate bunching or capacity pressure; an unusual shortfall can indicate closure, diversion, demand interruption, or disrupted throughput. Values within ±5% score zero; deviations of 40% or more score 100. Entity scores are combined using 55% activity-weighted mean and 45% mean of the three largest anomalies.

PortWatch is an AIS-derived proxy. Reception gaps, ship reporting behaviour, revisions, and calendar effects can affect the series.

2. Forward weather component

MET Norway Locationforecast supplies a 0–9 day global forecast based on ECMWF data. At ten high-activity port coordinates, the model evaluates the next seven days.

wind = clamp((maximum wind − 12 m/s) / 14 × 100, 0, 100)
rain = clamp((maximum daily precipitation − 30 mm) / 90 × 100, 0, 100)
site pressure = max(wind, rain)

The component is 65% mean of the three most exposed sites plus 35% mean across all evaluated sites. It is a screening indicator; point forecasts do not capture berth-level waves, currents, local operating limits, or port-authority decisions.

3. Hazard proximity component

Current GDACS tropical cyclones, floods, and earthquakes are matched to the nearest high-activity port using great-circle distance. Event alert level, reported severity, and distance determine pressure. Calibrated inclusion radii are 900 km for cyclones, 300 km for floods, and 350 km for earthquakes. The component equals the mean pressure of up to three highest-scoring matches.

Proximity is not impact. GDACS points may represent event centroids, while real hazard footprints are spatially complex.

Concurrence and alert bands

A +5 point concurrence bonus is applied only when at least one AIS flow component is ≥50 and an independent weather or hazard component is ≥40. This rewards cross-domain confirmation without allowing correlated AIS signals alone to create the bonus.

Reproduction

All transformation code, thresholds, source URLs, generated evidence, and tests are public in the repository. No API key or language model is required.

python -m pip install -r requirements.txt

python -m pytest -q

python pipeline/port_congestion_pulse_pipeline.py

The run writes a deterministic schema to data/output.json. Source revisions or later execution time can change observed values. GitHub Actions performs the same commands every six hours and publishes the resulting static site.