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

> Discover the detectGeoConvergence method in koala73/worldmonitor to identify multi-event clusters within 24 hours. Optimize your event detection today.

- Repository: [Elie Habib/worldmonitor](https://github.com/koala73/worldmonitor)
- Tags: architecture
- Published: 2026-03-09

---

**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`](https://github.com/koala73/worldmonitor/blob/main//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`](https://github.com/koala73/worldmonitor/blob/main//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`](https://github.com/koala73/worldmonitor/blob/main//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:

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

```

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

```typescript
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`](https://github.com/koala73/worldmonitor/blob/main//src/services/geo-convergence.ts):

```typescript
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`:

```typescript
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`](https://github.com/koala73/worldmonitor/blob/main//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`](https://github.com/koala73/worldmonitor/blob/main//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`](https://github.com/koala73/worldmonitor/blob/main//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`](https://github.com/koala73/worldmonitor/blob/main//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`.