Predictive Risk Scoring and Early Warning System

Salud IA Bot goes beyond static data retrieval with a modular predictive subsystem that calculates epidemic risk scores, projects case trends, and generates early-warning alerts — all without relying solely on LLM inference. The system is triggered by queries containing keywords like prediccion, pronostico, alertas tempranas, clasificar riesgo, or analizar riesgo, which BotUpdate routes to PredictiveQuestionsService as the orchestration layer.

The prediction system supports dengue, zika, malaria, tuberculosis, and all other SIVIGILA-tracked events. Available events and regions are generated dynamically at query time from the in-memory SIVIGILA dataset.

System architecture

PredictiveQuestionsService coordinates four specialized services:

MlPredictionService

Composite risk scoring with four weighted dimensions. Produces BAJO to CRITICO classification.

AdvancedPredictionService

Holt-Winters-inspired time-series forecasting with confidence intervals and trend direction.

EarlyWarningService

Threshold-based alert engine that monitors case volume, vaccination coverage, and rurality.

DatasetBuilderService

Data pipeline that normalizes and cross-references SIVIGILA, PAI vaccination, and air quality sources. Includes 24-hour cache.

Composite Risk Scoring — `MlPredictionService`

MlPredictionService.clasificarRiesgo(nombreEvento, departamento) is the primary risk API. It cross-references SIVIGILA event data, departmental PAI vaccination coverage, and population structure to produce a 0-100 composite score across four weighted dimensions.

Scoring dimensions

Dimension	Weight	Source	Calculation
Case Volume (`volumen`)	40%	SIVIGILA `total_de_eventos`	Normalized using log10 scaling (60% positional, 40% logarithmic) relative to the max event in the dataset
Rurality (`ruralidad`)	20%	SIVIGILA `rural / total`	Tiered scoring: 70%+ rural = 100 pts; 50%+ = 75-100; 30%+ = 40-75; linear below
Vaccination Gap (`brecha_vacunacion`)	25%	PAI `cobertura_de_vacunaci_n`	Inverse of coverage: 95%+ = 0 pts risk; below 70% = 70-100 pts risk
Vulnerable Population (`poblacion_vulnerable`)	15%	SIVIGILA `primera_infancia + infancia + adulto_mayor`	% of cases in vulnerable age groups: 60%+ = 100 pts; linear below

The PESOS constant in MlPredictionService:

private readonly PESOS: PesosDimensiones = {
  volumen: 0.40,
  ruralidad: 0.20,
  brecha_vacunacion: 0.25,
  poblacion_vulnerable: 0.15,
};

Risk level thresholds

The UMBRALES constant drives level assignment:

private readonly UMBRALES = {
  CRITICO: 75,
  ALTO: 50,
  MEDIO: 25,
};

Level	Score range	Recommended action
`BAJO`	0 to 24	Routine surveillance, maintain vaccination schedules
`MEDIO`	25 to 49	Weekly monitoring, verify rural vaccination coverage
`ALTO`	50 to 74	Sanitary alert, intensify active epidemiological surveillance
`CRITICO`	75 to 100	Activate Emergency Operations Center (COE), mass prevention campaign

Output structure

clasificarRiesgo returns a ClasificacionRiesgo object:

interface ClasificacionRiesgo {
  evento: string;
  departamento: string;
  nivel_riesgo: 'BAJO' | 'MEDIO' | 'ALTO' | 'CRITICO';
  puntaje_total: number;
  desglose_puntaje: DesgloseScore;
  factores_decisivos: string[];
  recomendacion_accion: string;
}

interface DesgloseScore {
  volumen: number;
  ruralidad: number;
  brecha_vacunacion: number;
  poblacion_vulnerable: number;
  total: number;
}

Fields explained:

evento: canonical SIVIGILA event name
departamento: region queried
nivel_riesgo: one of BAJO, MEDIO, ALTO, or CRITICO
puntaje_total: 0-100 composite score
desglose_puntaje: per-dimension weighted contribution (volumen, ruralidad, brecha_vacunacion, poblacion_vulnerable, total)
factores_decisivos: human-readable list of the key risk factors detected (e.g. "Alto volumen: 45,230 casos", "Cobertura de vacunacion CRITICA (58%)")
recomendacion_accion: tailored recommendation text for the detected risk level

Example risk queries

"Analizar riesgo de dengue en Cali"
-> Composite score for DENGUE using Valle del Cauca vaccination coverage

"Clasificar riesgo de tuberculosis en Antioquia"
-> Score breakdown: volume (TUBERCULOSIS case count), rurality,
   Antioquia PAI coverage, vulnerable population share

"Predecir riesgo de malaria en Boyacá"
-> Risk classification for MALARIA in Boyaca with action recommendation

"Riesgo de zika en el Valle del Cauca"
-> Full ClasificacionRiesgo object with desglose and decisive factors

Time-series forecasting — `AdvancedPredictionService`

AdvancedPredictionService.predecirEvento(nombreEvento, departamento, periodosFuturos=3) implements a simplified Prophet-style decomposition model for case projection.

Forecasting pipeline

Synthetic temporal series

A 12-period (monthly proxy) series is constructed from the SIVIGILA event’s age-group distribution. Each period’s case count is weighted by the age-group proportion, with a semi-annual sinusoidal seasonality component (cycle = 6 periods).

Trend decomposition

Each temporal point is decomposed into: tendencia (linear base), estacionalidad (sinusoidal component), and residuo (the remainder).

Weighted linear regression

calcularRegresionLinealPonderada fits a least-squares line with exponential weighting (1.1^i) so that recent periods have more influence on the slope estimate.

Seasonality detection

detectarEstacionalidad tests for cycles of 3, 6, or 12 periods using the decomposed seasonality values, selecting the first cycle length for which the series has at least ciclo x 2 points.

Projection and confidence interval

Future values are computed as tendencia_futura + tendencia_futura * factor_estacional. A 95% confidence interval is derived from +-1.96 * std(residuos).

The result includes valor_proyectado, intervalo_confianza_bajo, intervalo_confianza_alto, tendencia (creciente | decreciente | estable), estacionalidad_detectada, and a contextual recomendacion.

Example forecasting queries

"Tendencia de zika en los próximos meses en Cali"
-> Projects ZIKA cases with trend direction and 95% CI for Valle del Cauca

"Pronóstico de dengue en Antioquia"
-> Returns valor_proyectado, interval, trend, and recommendation for DENGUE

Early warning alerts — `EarlyWarningService`

EarlyWarningService.evaluarAlertas() scans the full SIVIGILA event catalog against pre-defined thresholds and produces a sorted list of EarlyWarning objects.

Alert thresholds

Threshold	Value	Trigger
`casos_altos`	10,000 cases	Event total exceeds this value — vigilancia flag
`cobertura_baja`	below 80% PAI coverage	Vaccination gap factor added to alert
`cobertura_critica`	below 60% PAI coverage	Critical vaccination gap flagged in recommendation
`incremento_mensual`	above 20% increase	Estimated monthly growth triggers alerta flag

Alert levels

Level	Condition
`NORMAL`	No threshold exceeded
`VIGILANCIA`	Above 10,000 cases or 1 or more risk factors detected
`ALERTA`	Above 20,000 cases or 2 or more factors with growing trend
`EMERGENCIA`	Above 50,000 cases or 3 or more factors with growing trend

Alerts are sorted by severity (EMERGENCIA first) before being returned. The summary text from obtenerResumenAlertas() groups them by level with case counts, trigger descriptions, and specific recommendations (including whether a mass vaccination campaign is required based on PAI coverage).

Example early-warning queries

"Alertas tempranas de salud pública"
-> Full alert summary sorted by severity across all SIVIGILA events

"Alertas de brote de dengue"
-> Filtered alert assessment for DENGUE with factor_detonante and recommendation

Data pipeline — `DatasetBuilderService`

DatasetBuilderService is the data normalization layer that feeds all three prediction services. It:

Fetches and normalizes SIVIGILA event records from SaludPublicaService
Retrieves departmental PAI vaccination coverage from VaccinationService
Collects environmental air quality readings from AirQualityService
Cross-references these sources to build enriched feature vectors for risk scoring
Caches results for 24 hours to avoid redundant computation on repeated queries

This architecture ensures that MlPredictionService, AdvancedPredictionService, and EarlyWarningService always receive clean, normalized inputs regardless of the variable quality of the underlying open-data XML sources.

Get Started

Core Features

Architecture

Operations

System architecture

MlPredictionService

AdvancedPredictionService

EarlyWarningService

DatasetBuilderService

Composite Risk Scoring — `MlPredictionService`

Scoring dimensions

Risk level thresholds

Output structure

Example risk queries

Time-series forecasting — `AdvancedPredictionService`

Forecasting pipeline

Example forecasting queries

Early warning alerts — `EarlyWarningService`

Alert thresholds

Alert levels

Example early-warning queries

Data pipeline — `DatasetBuilderService`

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Operations

Documentation Index

​System architecture

MlPredictionService

AdvancedPredictionService

EarlyWarningService

DatasetBuilderService

​Composite Risk Scoring — MlPredictionService

​Scoring dimensions

​Risk level thresholds

​Output structure

​Example risk queries

​Time-series forecasting — AdvancedPredictionService

​Forecasting pipeline

​Example forecasting queries

​Early warning alerts — EarlyWarningService

​Alert thresholds

​Alert levels

​Example early-warning queries

​Data pipeline — DatasetBuilderService

Build docs developers (and LLMs) love

System architecture

Composite Risk Scoring — `MlPredictionService`

Scoring dimensions

Risk level thresholds

Output structure

Example risk queries

Time-series forecasting — `AdvancedPredictionService`

Forecasting pipeline

Example forecasting queries

Early warning alerts — `EarlyWarningService`

Alert thresholds

Alert levels

Example early-warning queries

Data pipeline — `DatasetBuilderService`