Geographic Convergence Detection Method: Identifying Multi-Event Clusters Within 24 Hours in WorldMonitor

The detectGeoConvergence function in koala73/worldmonitor identifies geographic convergence zones by clustering at least three distinct event types within a 24-hour sliding window, scoring each zone based on event diversity and density.

The geographic convergence detection method implemented in the koala73/worldmonitor repository enables real-time identification of multi-event clusters that may indicate emerging geopolitical hotspots. This TypeScript-based system analyzes disparate event streams—ranging from military movements to natural disasters—within a strict 24-hour temporal boundary to surface anomalous geographic concentrations.

How the Geographic Convergence Detection Method Works

The 24-Hour Sliding Window

The system maintains a temporal boundary using the WINDOW_MS constant defined in /src/services/geo-convergence.ts at lines 18-20. This constant calculates the millisecond equivalent of 24 hours (24 * 60 * 60 * 1000), ensuring that only events occurring within the last day are considered during analysis. Before processing, the detectGeoConvergence function automatically prunes stale events that fall outside this window.

Multi-Event Cluster Thresholds

A geographic cell—representing approximately a 1° × 1° latitude-longitude bucket—qualifies as a convergence zone only when it contains at least three distinct event types. This threshold is enforced by the CONVERGENCE_THRESHOLD constant set to 3 in /src/services/geo-convergence.ts at lines 19-20. The system tracks event diversity using Set data structures to ensure uniqueness across categories such as military flights, vessel movements, protests, and seismic activity.

Convergence Scoring Algorithm

Each qualifying cell receives a composite score calculated between lines 105-116 of /src/services/geo-convergence.ts. The algorithm combines two factors: type diversity (typeScore = cell.events.size * 25) and event density (countBoost = min(25, totalEvents * 2)). The final score caps at 100 points, creating a normalized metric for ranking convergence zones by severity and complexity.

Core Implementation in geo-convergence.ts

The primary detection logic resides in the detectGeoConvergence function, while the public API exposes detectConvergence as a convenience wrapper that initializes an empty exclusion set. The implementation at lines 104-106 appears as follows:

export function detectConvergence(): GeoConvergenceAlert[] {
  return detectGeoConvergence(new Set());
}

To retrieve current convergence alerts with full metadata, call the public method:

import { detectConvergence } from '@/services/geo-convergence';

// Returns an array of alerts sorted by descending score
const alerts = detectConvergence();

alerts.forEach(alert => {
  console.log(
    `🗺️ Convergence at ${alert.lat.toFixed(1)}°, ${alert.lon.toFixed(1)}° – `,
    `${alert.types.join(', ')} (${alert.totalEvents} events/24h), score ${alert.score}`
  );
});

Ingesting Heterogeneous Event Streams

Before detection can occur, the system must ingest diverse event types into the geographic grid. The repository provides specialized ingestion functions that automatically timestamp and bucket events according to the 24-hour window constraints defined in /src/services/geo-convergence.ts:

import {
  ingestProtests,
  ingestFlights,
  ingestVessels,
  ingestEarthquakes,
} from '@/services/geo-convergence';

// Example payloads (normally fetched from external APIs)
ingestProtests(protestEvents);          // SocialUnrestEvent[]
ingestFlights(militaryFlights);         // MilitaryFlight[]
ingestVessels(militaryVessels);         // MilitaryVessel[]
ingestEarthquakes(earthquakeList);      // Earthquake[]

Each ingestion call updates the internal geographic cells and triggers automatic pruning of events exceeding the 24-hour threshold, ensuring that subsequent detectConvergence() calls operate on fresh data.

Converting Alerts to UI Signals

For dashboard integration, the repository includes utilities to transform raw convergence alerts into standardized signal objects. The geoConvergenceToSignal function prepares alerts for display in components like StrategicRiskPanel:

import { geoConvergenceToSignal } from '@/services/geo-convergence';

const signal = geoConvergenceToSignal(alerts[0]);
// `signal` can be displayed in the dashboard or fed to downstream analytics

This conversion utility leverages generateSignalId from /src/utils/analysis-constants.ts to ensure consistent signal identification across the WorldMonitor platform.

Summary

• The geographic convergence detection method in koala73/worldmonitor uses a 24-hour sliding window (WINDOW_MS) to filter relevant events.
• Convergence zones require at least three distinct event types per 1° × 1° geographic cell (CONVERGENCE_THRESHOLD = 3).
• The scoring algorithm combines type diversity and event density, capping at 100 points to rank hotspot severity.
• Core implementation resides in /src/services/geo-convergence.ts, exposing detectConvergence() for public consumption and detectGeoConvergence() for internal logic.
• Event ingestion supports heterogeneous streams including military movements, social unrest, and seismic activity, with automatic pruning of stale data.

Frequently Asked Questions

What defines a geographic convergence zone in WorldMonitor?

A geographic convergence zone is defined as a 1° × 1° latitude-longitude cell containing at least three distinct event types within a 24-hour period. This threshold, enforced by the CONVERGENCE_THRESHOLD constant in /src/services/geo-convergence.ts, ensures that only significant multi-domain anomalies trigger alerts.

How does the 24-hour window affect detection accuracy?

The 24-hour sliding window, implemented via the WINDOW_MS constant (86,400,000 milliseconds), automatically prunes stale events before analysis. This temporal boundary ensures real-time relevance while preventing historical event accumulation from distorting current convergence scores, maintaining detection accuracy for emerging hotspots.

What event types can trigger a convergence alert?

The system accepts heterogeneous event streams including military flights (MilitaryFlight), naval vessels (MilitaryVessel), social unrest protests (SocialUnrestEvent), and seismic activity (Earthquake). Each ingestion function processes these distinct types, and convergence triggers when any combination of three or more different categories co-occur in the same geographic cell.

Where is the convergence detection logic implemented?

The core detection algorithm resides in /src/services/geo-convergence.ts, specifically within the detectGeoConvergence function (lines 104-116). This module defines the temporal window constants, geographic bucketing logic, and scoring algorithm. The public API wrapper detectConvergence exposed at lines 104-106 serves as the primary entry point for UI components like StrategicRiskPanel.

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