dismodlite: estimación de carga de enfermedad por edad, sexo y ubicación

Estima la prevalencia, la incidencia, la mortalidad en exceso y los años vividos con discapacidad (AVD) de una causa, por edad y sexo, en un país y en sus ubicaciones subnacionales (departamentos, regiones, provincias...), con un modelo enfermedad-muerte (DisMod-lite). El modelo se ancla en una estimación de referencia externa (el ancla; por ejemplo, la de GBD para el país), la combina con los datos locales que se declaren y lleva el resultado nacional a las ubicaciones subnacionales según las diferencias de sus covariables. La incertidumbre se propaga con simulaciones MCMC, y cada corrida se escribe en una carpeta reproducible, con un manifiesto que registra sus insumos y sus decisiones.

Tres comandos

Un proyecto es una configuración corta y unas pocas tablas, el contrato de insumos (ver dl_tablas): las ubicaciones, la población, el ancla (las descargas de GBD Results, tal como se descargan) y, si hacen falta, las covariables (las descargas del GHDx y sus valores subnacionales), sus betas, los datos locales y la severidad. Las tablas van en la carpeta del proyecto o se pasan como data.frame a dl_proyecto(). Tres funciones cubren el trabajo:

dl_nuevo_proyecto() crea la carpeta con la configuración comentada, las plantillas de las tablas y un LEEME.md que dice de dónde se descarga cada archivo.
dl_revisar_proyecto(), con la carpeta llena, revisa cada archivo y cada regla sin detenerse en el primer problema y dice cómo corregir cada uno.
dl_correr() hace la corrida en una llamada: primero con rapido = TRUE, una prueba de principio a fin que tarda segundos; después, la corrida de producción.

dl_nuevo_proyecto("mi_proyecto", causa = 1234, nombre = "Mi enfermedad", anio = 2023,
                  edad_inicio = 30)
# llenar las tablas y copiar las descargas a ancla/ (y a covariables/); después:
dl_revisar_proyecto("mi_proyecto")
prueba <- dl_correr("mi_proyecto", semilla = 1, rapido = TRUE)
corrida <- dl_correr("mi_proyecto", semilla = 1)

dl_ejemplo() es un proyecto completo con datos sintéticos (una enfermedad ficticia, con la geografía del Perú como ejemplo), para leerlo, correrlo y copiarlo como punto de partida. dl_configuracion() documenta cada clave de la configuración, dl_tablas cada tabla y sus columnas y dl_proyecto(), la carpeta y las dos puertas.

Etapas de una corrida

dl_correr() hace en orden las etapas de una causa. Cada etapa es también una función que se puede llamar por separado, para mirar o cambiar un paso:

Proyecto e insumos: dl_proyecto() lee la carpeta y dl_insumos() lee y valida todas las tablas (dl_configuracion() y dl_rutas() arman la configuración y las rutas por separado).
Ajuste nacional, por sexo: dl_ajustar(), con las opciones del muestreo de dl_opciones_mcmc(), y dl_ajustar_solo_prior(), el mismo ajuste sin los datos locales. dl_estimaciones() da la media y el intervalo por edad, sexo y ubicación de un ajuste, de una cascada o de los AVD.
Estimación subnacional: dl_cascada().
Validación contra el ancla y contra los datos subnacionales reservados: dl_validar_ancla().
Carga: dl_avd(), con dl_factor_comorbilidad(), que calibra los AVD al AVD del ancla.
Diagnóstico: dl_etiquetas() (cuánto informan los datos a cada celda) y dl_sensibilidad(); dl_rhat() y dl_ess() miden la convergencia de las cadenas.
Resumen y carpeta de la corrida: dl_resumir() y dl_exportar_corrida().

Después de las corridas, dl_sumar_hijas() suma las corridas de los subtipos de una causa, dl_reresumir_corrida() vuelve a resumir una corrida sin volver a ajustar y dl_consolidar() reúne las corridas de varias causas en tablas por medida.

Guías

vignette("primeros-pasos", package = "dismodlite"): el proyecto de ejemplo de principio a fin.
vignette("el-modelo", package = "dismodlite"): el modelo, su notación y sus supuestos.
vignette("preparar-datos", package = "dismodlite"): las tablas de un proyecto propio, una por una.
En el sitio del paquete, https://horaciochacon.github.io/dismodlite/, las guías de temas avanzados: la estimación subnacional, los datos locales, los subtipos y su suma, la carga (AVD), las corridas y el consolidado, y el diagnóstico y la sensibilidad.

Formato completo y nombres anteriores

Los proyectos de la versión 0.2.2 (el formato completo, con schema: dismod_lite/v1 en la configuración) se leen igual y dan los mismos números (ver la sección «Formato completo» de dl_proyecto() y de dl_configuracion()). Los proyectos de la versión 1.0.0 se rehacen con las tablas del contrato de insumos. Las funciones tienen nombres en español; los nombres de la versión 0.2.2 siguen funcionando (ver dl_nombres_anteriores).

Author

Maintainer: Horacio Chacón hchacont@u.washington.edu

Other contributors:

University of Washington [copyright holder]

Examples

# el proyecto de ejemplo
p <- dl_proyecto(dl_ejemplo(), causa = 9100)
p
#> <dl_proyecto> Arteriopatía crónica sintética, causa 9100 | año 2023 | tablas del contrato
#>   carpeta: /home/runner/work/_temp/Library/dismodlite/extdata/acs_peru
#>   tablas:
#>     ubicaciones             26 fila(s), de ubicaciones.csv
#>     poblacion               2100 fila(s), de poblacion.csv
#>     ancla                   768 fila(s), de ancla
#>     covariables             8 fila(s), de covariables
#>     betas                   3 fila(s), de betas.csv
#>     datos                   185 fila(s), de datos.csv
#>     severidad               12 fila(s), de severidad.csv
#>     fuentes_gbd             no
#>     poblacion_detalle       no
#>     proxies_crudos          1500 fila(s), de proxies_crudos.csv
#>     razones                 no
#>     prior_mortalidad_exceso no
#>   subnacional: covariables
#>   proxies calibrados de proxies_crudos (año 2023):
#>     SEV_scalar_agestd_cvd_pvd: paseo_aleatorio, q = 2.26e-05, ediciones 2019, 2021, 2023
#>     LDI_pc: paseo_aleatorio, q = 0.000373, ediciones 2019, 2021, 2023
#>     haqi: paseo_aleatorio, q = 0.406, ediciones 2019, 2021, 2023
#>   tomado por defecto (14):
#>     sexos = [hombres, mujeres]
#>     ubicacion_gbd = 123
#>     ancla.peso (λ) = 1
#>     ancla.correlacion_edad (ρ) = 0.5
#>     ancla.anio = 2023
#>     nudos = [30, 40, 50, 60, 70, 80, 95]
#>     incidencia.suavidad (σ) = 0.5
#>     mortalidad_exceso.prior = desde_ancla
#>     remision = 0
#>     datos_en_ajuste = ninguno: las nacionales no se usan; las subnacionales de mortalidad validan
#>     subnacional.modo = covariables
#>     subnacional.kappa (κ) = 1
#>     sensibilidad.correlacion_edad (ρ) = [0, 0.5, 0.9]
#>     sensibilidad.kappa (κ) = [0.5, 1]
# \donttest{
# una corrida de prueba, escrita en una carpeta temporal
salida <- file.path(tempdir(), "resultados")
run <- dl_correr(p, semilla = 1, rapido = TRUE, sensibilidad = FALSE, carpeta_salida = salida)
#> dl_correr(): corrida de prueba (rapido = TRUE): 2 cadena(s) de 2000 iteraciones y forzar = TRUE, que la escribe aunque las cadenas no converjan. Sus números no sirven para publicar: para la corrida final, rapido = FALSE
#> dl_correr(): causa 9100: insumos
#> dl_correr(): 25 fila(s) nacionales de la tabla datos quedan fuera del ajuste porque datos_en_ajuste está vacío en la configuración; las filas subnacionales se usan solo para validar la cascada
#> dl_correr(): ajuste nacional: 2 cadena(s) de 2000 iteraciones por sexo (motor mh)
#> dl_correr(): cascada subnacional
#> dl_correr(): validación contra el ancla y AVD
#> dl_correr(): etiquetas de cuánto informan los datos
#> dl_correr(): corrida escrita en /tmp/RtmpucVo2P/resultados/mod/dismod_lite/2026-10-15_causa-9100-prueba_v1 (prueba: no sirve para publicar)
run
#> <dl_run> corrida 2026-10-15_causa-9100-prueba_v1 (cascada subnacional)
#>   carpeta: /tmp/RtmpucVo2P/resultados/mod/dismod_lite/2026-10-15_causa-9100-prueba_v1
#>   3 particiones canónicas (una por medida) | exportada con forzar = TRUE

# paso a paso: insumos, un ajuste corto (una prueba, no una estimación para publicar) y sus
# estimaciones
b <- dl_insumos(p)
#> dl_insumos(): 25 fila(s) nacionales de la tabla datos quedan fuera del ajuste porque datos_en_ajuste está vacío en la configuración; las filas subnacionales se usan solo para validar la cascada
op <- dl_opciones_mcmc(simulaciones = 100, cadenas = 2, iteraciones = 2000, calentamiento = 1000)
f <- dl_ajustar(b, op, semilla = 1)
head(dl_estimaciones(f))
#>    location_id sex_id  edad      medida        media     inferior    superior
#>         <char>  <int> <int>      <char>        <num>        <num>       <num>
#> 1:         123      1    30 prevalencia 0.0000000000 0.0000000000 0.000000000
#> 2:         123      1    31 prevalencia 0.0009713892 0.0004834718 0.001674911
#> 3:         123      1    32 prevalencia 0.0019514261 0.0010106230 0.003300012
#> 4:         123      1    33 prevalencia 0.0029423464 0.0015789707 0.004877413
#> 5:         123      1    34 prevalencia 0.0039464232 0.0021877604 0.006410696
#> 6:         123      1    35 prevalencia 0.0049659840 0.0028435334 0.007903400
unlink(salida, recursive = TRUE)
# }