Guate OCDS Competition Screening Lab

Descripción

Herramienta educativa y exploratoria que descarga datos en formato Open Contracting Data Standard (OCDS) de Guatecompras (API MINFIN), calcula indicadores estadísticos de concentración y competencia para entidades compradoras, y los visualiza mediante gráficos interactivos.

⚠️ Aviso Importante

Todos los resultados tienen propósito exclusivamente educativo y exploratorio.

• No constituyen evidencia de colusión, fraude ni ninguna conducta ilegal
• Únicamente muestran patrones estadísticos que podrían servir como pantallas de riesgo
• Los indicadores están destinados a priorizar análisis humanos más profundos
• Este proyecto es una herramienta de análisis exploratorio, no una herramienta de auditoría

Características

• 📥 Descarga de datos OCDS: Consume datos públicos de contrataciones de Guatemala
• 📊 Cálculo de indicadores: Calcula métricas de concentración de mercado y competencia
• 🔍 Detección de anomalías: Utiliza Isolation Forest para identificar patrones atípicos
• 📈 Visualizaciones: Genera gráficos informativos sobre la competencia en contrataciones
• 📅 Análisis temporal: Procesa datos mes a mes para identificar tendencias

Requisitos

Dependencias Python

pip install pandas numpy matplotlib seaborn scikit-learn requests

Librerías principales:

• pandas: Manipulación y análisis de datos
• numpy: Operaciones numéricas
• matplotlib y seaborn: Visualización de datos
• scikit-learn: Machine learning (Isolation Forest, StandardScaler)
• requests: Consumo de API REST

Fuente de Datos

Los datos provienen de la API OCDS de Guatecompras:

• URL Base: https://ocds.guatecompras.gt/release/search
• Formato: Open Contracting Data Standard (OCDS)
• Cobertura: Contrataciones públicas de Guatemala

Estructura del Proyecto

Funciones Principales

1. Extracción de Datos

fetch_releases_ocds(...)

• Descarga releases de contrataciones desde la API de Guatecompras
• Parámetros de filtrado: año, mes, día, tipo de entidad, modalidad, etc.
• Implementa reintentos y paginación automática
• Pausa configurable entre requests para evitar sobrecarga del servidor

2. Procesamiento de Datos

flatten_releases_to_tables_enriched(releases)

• Transforma releases OCDS en tablas normalizadas
• Genera tres DataFrames: tenders, awards y processes
• Enriquece datos con información de compradores, proveedores y oferentes

3. Cálculo de Indicadores

compute_supplier_share_by_buyer(awards_df)

• Calcula la participación de cada proveedor por entidad compradora
• Identifica concentración de contratos en pocos proveedores

compute_hhi_by_buyer(shares_df)

• Calcula el Índice Herfindahl-Hirschman (HHI) por entidad
• HHI mide la concentración del mercado: valores altos indican menor competencia
• Rango: 0 (competencia perfecta) a 1 (monopolio)

compute_competition_intensity(processes_df)

• Analiza el número de oferentes por proceso
• Calcula proporción de procesos con un solo oferente
• Calcula promedio de oferentes por entidad

build_feature_table(...)

• Combina indicadores en una tabla de características
• Integra HHI, participación de proveedores e intensidad de competencia

4. Detección de Anomalías

run_isolation_forest(features_df, contamination=0.1)

• Aplica Isolation Forest para detectar entidades con patrones atípicos
• Normaliza características con StandardScaler
• Genera scores de anomalía para cada entidad
• Identifica entidades que merecen análisis más detallado

5. Pipeline Completo

run_full_2025_pipeline(...)

• Procesa múltiples meses de datos automáticamente
• Ejecuta todo el flujo: descarga, procesamiento, cálculo y detección
• Genera series temporales de indicadores
• Identifica anomalías por mes

build_buyer_ranking_2025(features_ts, min_months=3)

• Construye ranking de entidades por HHI promedio
• Filtra entidades con observaciones mínimas
• Ordena por nivel de concentración

Visualizaciones

1. Distribución de HHI

plot_hhi_distribution(features_ts)

• Histograma de HHI con KDE (estimación de densidad de kernel)
• Muestra la distribución general de concentración entre entidades

2. HHI vs Proporción de Oferente Único

plot_hhi_vs_single(features_ts)

• Scatter plot que relaciona concentración con procesos de oferente único
• Identifica correlación entre indicadores de competencia

3. Ranking de Entidades

plot_buyer_ranking_bar(ranking_df, top_n=20)

• Gráfico de barras horizontal con top entidades por HHI
• Facilita identificación visual de entidades con mayor concentración

4. Heatmap Entidad-Proveedor

plot_entity_supplier_heatmap(awards_all, top_suppliers=12)

• Mapa de calor mostrando relaciones entidad-proveedor
• Visualiza patrones de adjudicación por monto

Uso

Ejecución Básica

# Ejecutar pipeline completo para 2025 (meses 1-10)
result_2025 = run_full_2025_pipeline(start_month=1, end_month=10, contamination=0.15)

# Extraer resultados
features_ts = result_2025["features_ts"]  # Serie temporal de características
awards_all = result_2025["awards_all"]    # Todos los awards procesados

Análisis de Resultados

# Construir ranking de entidades
ranking_2025 = build_buyer_ranking_2025(features_ts, min_months=3)

# Ver top 10 entidades por HHI
print(ranking_2025.head(10))

# Generar visualizaciones
plot_hhi_distribution(features_ts)
plot_hhi_vs_single(features_ts)
plot_buyer_ranking_bar(ranking_2025, top_n=20)

Indicadores Clave

HHI (Herfindahl-Hirschman Index)

• Rango: 0 a 1 (o 0 a 10,000 si se multiplica por 10,000)
• Interpretación:
  • HHI < 0.15: Mercado no concentrado
  • 0.15 ≤ HHI < 0.25: Concentración moderada
  • HHI ≥ 0.25: Alta concentración
• Uso: Mide concentración de contratos entre proveedores

Single Tenderer Share

• Proporción de procesos con un solo oferente
• Valores altos pueden indicar problemas de competencia
• Complementa el análisis de HHI

Anomaly Score

• Generado por Isolation Forest
• Valores negativos indican mayor anomalía
• Identifica entidades con patrones estadísticamente inusuales

Ejemplo de Notebook

El notebook OCDS_guate.ipynb incluye un ejemplo completo de uso:

1. Instalación de dependencias
2. Importación de librerías
3. Ejecución del pipeline para datos de 2025
4. Generación de ranking de entidades
5. Creación de visualizaciones

Puedes ejecutarlo directamente en Google Colab usando el badge al inicio de este README.

Metodología

1. Extracción: Descarga de releases OCDS desde la API de Guatecompras
2. Transformación: Normalización de datos en tablas estructuradas
3. Cálculo: Generación de indicadores de competencia y concentración
4. Detección: Identificación de anomalías usando machine learning
5. Visualización: Presentación de resultados mediante gráficos

Limitaciones

• Los indicadores son estadísticos y requieren interpretación experta
• No se consideran factores contextuales que puedan justificar concentración
• La detección de anomalías no implica irregularidad
• Se requiere análisis humano para validar hallazgos
• Depende de la calidad y completitud de datos publicados

Consideraciones Éticas

Este proyecto debe usarse de manera responsable:

• No hacer acusaciones basadas únicamente en indicadores estadísticos
• Respetar la presunción de inocencia
• Usar como herramienta de priorización, no de conclusión
• Complementar con análisis detallado y evidencia adicional

Contribuciones

Este es un proyecto educativo abierto a mejoras y sugerencias.

Licencia

Este proyecto tiene fines exclusivamente educativos y de investigación.