De un volcado de PDFs a un atlas público: cómo construimos Atlas Criminalidad CR

El Organismo de Investigación Judicial (OIJ) publica estadísticas de incidencia criminal de todo el país. Los datos son genuinamente abiertos. También son, en la práctica, ilegibles — y que esos dos hechos convivan es el problema más común en los datos cívicos. Así lo resolvimos para Atlas Criminalidad CR, y las decisiones de diseño que lo mantienen honesto cada trimestre.

Datos abiertos que no eran usables

La materia prima llega como PDFs y hojas de cálculo, dividida por períodos de reporte, con nombres de cantón y distrito escritos de forma inconsistente entre archivos. Para responder algo tan básico como “¿está subiendo el hurto en mi cantón?”, un ciudadano debía descargar varios documentos, reconciliarlos a mano y confiar en su propia aritmética. Los datos abiertos que requieren una hora de reconciliación manual para leerse están, funcionalmente, cerrados.

La tentación es hacer una limpieza única: tomar los últimos archivos, arreglarlos a mano, lanzar un dashboard. Eso produce una captura de pantalla, no infraestructura. El OIJ publica de nuevo el próximo trimestre, la limpieza manual empieza otra vez y la herramienta se pudre. La especificación real nunca fue “hacer un dashboard” — fue “lograr que la próxima publicación entre sin que un humano la toque”.

Una restricción por encima de todo: legible en cinco minutos

Antes de cualquier código, fijamos un único estándar al que toda decisión posterior debía servir: un no-analista debía pasar de aterrizar en la página a una respuesta defendible en menos de cinco minutos. Esa restricción es implacable. Mata el informe de 90 páginas, el muro de login, el laberinto de “explora los datos” sin punto de partida. Obliga a resúmenes en lenguaje sencillo sobre cada gráfico y a una vista por defecto que ya responde la pregunta más común.

La inteligencia que no se puede consumir en quince minutos es inteligencia que no se usa. Para una herramienta pública, el presupuesto es cinco.

La arquitectura

El sistema es una tubería de un solo sentido. Los datos van de la fuente a un modelo estable y a una superficie renderizada, y cada etapa existe para absorber la próxima publicación sin romper la promesa de cinco minutos.

1 · Ingesta que sobrevive la próxima publicación

La primera etapa hace en código, una sola vez, el trabajo que antes era manual. Los archivos se parsean en filas, la geografía se reconcilia con códigos canónicos de cantón y distrito, y las categorías de delito se mapean a una taxonomía estable. La salida es una sola tabla normalizada con la misma forma cada trimestre — así una nueva publicación es un insumo, no un proyecto.

type Incidence = {
  provinceId: number;   // canonical 1–7
  cantonId: number;     // canonical, 82 total
  category: CrimeCode;  // mapped to a stable taxonomy
  period: `${number}-${number}`; // YYYY-MM
  count: number;
};

La parte poco glamorosa — la reconciliación de nombres — es donde la mayoría de las herramientas de datos cívicos falla en silencio. “San José”, “San Jose” y una variante con espacio al final son tres claves distintas para una computadora y el mismo lugar para una persona. Fijar cada registro a un código numérico canónico desde el inicio significa que nada aguas abajo tiene que adivinar.

2 · Un modelo, dos preguntas

Una redacción nacional y un solo residente quieren cosas opuestas de los mismos datos: una necesita comparar los 82 cantones, el otro necesita solo el suyo, a lo largo del tiempo. Ambas son la misma consulta contra un modelo — geografía por categoría por período — así que la herramienta responde una pregunta de tendencia nacional y una de un solo cantón sin reconstruirse. Las tasas y tendencias se derivan una vez, en el momento del modelo, no se recalculan en el navegador.

3 · Renderizar para el lector, no para el analista

Un gráfico no es una respuesta. Cada vista en el atlas se envuelve en una frase sobre la que un no-analista puede actuar, generada desde el mismo modelo para que nunca se desvíe de los números que describe. La capa de lenguaje sencillo sigue unas pocas reglas:

• ⟂Empezar con la dirección y la magnitud, luego el número — “sube fuerte (+38%)”, no una cifra suelta.
• ⟂Siempre nombrar la comparación: contra el año pasado, contra la tasa nacional, contra el cantón vecino.
• ⟂Nunca insinuar causalidad que los datos no sostienen. El atlas reporta incidencia; no la explica.

Lo que cuesta mantenerlo honesto

Como todo se renderiza a un build estático servido desde el edge, no hay servidor que se caiga y la página es rápida en un teléfono de gama media con datos móviles — el dispositivo en el que la mayoría de costarricenses realmente la abrirá. El costo continuo no es infraestructura; es la disciplina de pasar cada nueva publicación del OIJ por la misma tubería y volver a publicar, en lugar de parchar la salida. Esa disciplina es la diferencia entre un atlas y una captura de pantalla.

La lección

El valor nunca estuvo en recolectar los datos — el OIJ ya lo hizo, y bien. El valor estuvo en hacerlos legibles, y en construir la tubería para que la legibilidad sobreviva la próxima publicación. Esa es toda la tesis del estudio en un proyecto: la mayoría del software se optimiza para la demo; este se optimizó para su tercer año. Puedes leer el resultado por ti mismo.