Correr un proyecto de principio a fin

El recorrido estándar de una corrida en una sola llamada: lee el proyecto, arma los insumos, ajusta, lleva el ajuste a las ubicaciones subnacionales si corresponde, valida contra el ancla, calcula los AVD, las etiquetas y la sensibilidad, resume y escribe la carpeta de la corrida. Cada paso sigue disponible por separado, con la función que se nombra en Detalles.

Usage

dl_correr(
  proyecto,
  causa = NULL,
  semilla,
  carpeta_salida = NULL,
  rapido = FALSE,
  sensibilidad = TRUE,
  opciones = NULL,
  registro = NULL,
  forzar = FALSE,
  anios = NULL
)

Arguments

proyecto: Carpeta del proyecto (con las tablas del contrato de insumos o en el formato completo) o un proyecto de dl_proyecto().
causa: Causa (cause_id); NULL si el proyecto tiene una sola (o si proyecto ya es un dl_proyecto).
semilla: Semilla (entero), obligatoria: el resultado es reproducible con la misma semilla. Una causa que es la suma de sus subtipos no se ajusta y no la usa.
carpeta_salida: Carpeta raíz de las corridas: la corrida se escribe en <carpeta_salida>/mod/dismod_lite/<AAAA-MM-DD>_causa-<causa>_v<n>/. NULL (por defecto) es la carpeta resultados del proyecto. Una suma de subtipos busca ahí las corridas de sus subtipos.
rapido: TRUE para una corrida de prueba (ver Detalles); FALSE (por defecto), la de producción.
sensibilidad: TRUE (por defecto) corre el análisis de sensibilidad y lo guarda en la corrida (diagnostics/sensibilidad.csv); FALSE lo omite.
opciones: Opciones de dl_opciones_mcmc() del ajuste nacional; NULL (por defecto) usa las de producción o, con rapido = TRUE, las cortas. Con rapido = TRUE, las opciones que se den reemplazan a las cortas y la corrida sigue siendo una prueba. Su motor y sus nucleos valen también para la sensibilidad (ver Detalles).
registro: Archivo YAML del registro de corridas, que ya existe (uno nuevo es un archivo con la línea datasets: []): la corrida se agrega al final. Se comprueba antes de ajustar. NULL (por defecto) no registra.
forzar: TRUE escribe la corrida aunque las cadenas no hayan convergido (queda declarado en el manifiesto; ver Detalles); no salta la compuerta del ancla. FALSE (por defecto) exige la convergencia, salvo con rapido = TRUE, que la salta siempre.
anios: Vector de años enteros, sin NA ni repetidos (por ejemplo 2019:2023): corre la causa una vez por año, en orden, con el proyecto leído para cada uno (ver Detalles). NULL (por defecto) corre una sola vez, el año de la configuración del proyecto.

Value

Sin anios, un objeto de clase dl_run, como el de dl_exportar_corrida(), una lista con run_id (el identificador de la corrida, <AAAA-MM-DD>_causa-<causa>_v<n>, o ..._causa-<causa>-prueba_v<n> con rapido = TRUE), dir (su carpeta), manifest (el contenido de su manifest.yaml, como lista) y files (las tablas de celdas escritas, una por medida, con su ruta, su sha256 y su número de filas). Los mensajes dicen qué paso corre y, al final, dónde quedó la corrida.

Con anios, una lista de clase dl_corridas con un dl_run por año, con los años como nombres (corridas[["2023"]]); su identificador es <AAAA-MM-DD>_causa-<causa>-<año>_v<n> (..._causa-<causa>-<año>-prueba_v<n> con rapido = TRUE). print() muestra una línea por año.

Details

Los pasos, en orden:

los insumos (dl_proyecto() y dl_insumos());
el ajuste nacional (dl_ajustar()) y el ajuste solo con el ancla (dl_ajustar_solo_prior());
la cascada subnacional (dl_cascada()), si hay proxies del año que se estima o subnacional.modo es plano o razon (cascada.modo: plana o razon en el formato completo); si no, un mensaje lo dice y la corrida es solo nacional;
la validación contra el ancla (dl_validar_ancla());
el factor de comorbilidad (dl_factor_comorbilidad(), si el ancla trae AVD), los AVD (dl_avd()) y, con subnacional.modo: razon, el reparto por razón (dl_repartir_razon()), con la semilla de la corrida o la de avanzado: {cascada: {razon_semilla: ...}}: las tasas subnacionales de la corrida son las repartidas, y la validación, las etiquetas y la sensibilidad son las del ajuste nacional;
las etiquetas de cuánto informan los datos (dl_etiquetas()), con la grilla de sensibilidad.correlacion_edad de la configuración;
la sensibilidad (dl_sensibilidad()) con la grilla sensibilidad de la configuración, si sensibilidad = TRUE;
el resumen (dl_resumir()) y la carpeta de la corrida (dl_exportar_corrida()), llamada causa-<causa>; con registro, la corrida queda además en el registro de corridas.

Por defecto las cadenas son las de producción de dl_opciones_mcmc(): 1000 simulaciones, 4 cadenas de 50 000 iteraciones con 10 000 de calentamiento, motor "mh". La sensibilidad usa sus propias cadenas, las de dl_sensibilidad() (200 simulaciones, 2 cadenas de 6000 iteraciones con 3000 de calentamiento), con el motor de opciones y con sus nucleos como procesos: reparten las combinaciones de la grilla, y el resultado no depende de cuántos sean. Las etiquetas hacen sus reajustes con las cadenas cortas de dl_etiquetas() y el motor del ajuste.

La corrida no se escribe en dos casos, que dl_correr() comprueba en cuanto puede, con las mismas compuertas que dl_exportar_corrida(). Si las cadenas no convergieron (R-hat < 1.01 y ESS >= 400), justo después del ajuste: aumenta iteraciones y calentamiento con opciones. Y si la prevalencia ajustada se aleja de la del ancla (error relativo mediano mayor que 0.05), justo después de la validación, también con rapido = TRUE o forzar = TRUE: revisa el ajuste y los datos o declara un máximo mayor en la configuración, ancla: {error_maximo: ...} en un proyecto (en el formato completo, anchor: {gate_err_mediano: {valor, procedencia}}; ver dl_configuracion()).

forzar = TRUE salta la primera compuerta, la de la convergencia, y solo esa: la corrida se escribe con las cadenas que se pidieron aunque no hayan convergido, un mensaje da su R-hat y su ESS y el manifiesto lo declara (validacion.gates.force), como en dl_exportar_corrida(). El nombre de la corrida no cambia. Sirve para mirar una corrida que aún no converge; sus números no sirven para publicar.

rapido = TRUE es una prueba, para ver que el proyecto corre de principio a fin: cadenas cortas (100 simulaciones, 2 cadenas de 2000 iteraciones), las mismas en la sensibilidad, etiquetas solo con la ancla.correlacion_edad de la configuración y la corrida escrita con forzar = TRUE, sin exigir la convergencia (el manifiesto lo declara). Su nombre termina en -prueba y sus números no sirven para publicar.

Con anios, la causa se corre una vez por año, en orden, y el proyecto se vuelve a leer para cada uno (dl_proyecto(anio = ), con la regla del año del ancla de dl_proyecto()): un proyecto sirve para varios años sin editar su configuración. Las comprobaciones de los argumentos se hacen una vez, antes del primer año; el nombre de cada corrida lleva el año (causa-<causa>-<año>, y -prueba con rapido = TRUE), y cada corrida es de por sí una corrida completa, como la de un dl_correr() sin anios. El proyecto de todos los años se lee antes de correr el primero: si el de alguno no se puede leer (el ancla no trae ese año ni el anterior, falta su población...), dl_correr() se detiene ahí, con el año y el problema, sin haber escrito ninguna corrida. Si un año falla al correr, se detiene con el error de ese año y dice qué años quedaron escritos; esas corridas siguen en su carpeta.

La causa debe tener severidad (sus estados de salud en severidad.csv o desde severidad.particion): sin ella los AVD serían cero y la corrida no se escribe. dl_correr() lo comprueba antes de ajustar.

Una causa que es la suma de sus subtipos (suma_de_subtipos: sí en su configuración; ver dl_proyecto()) no se ajusta: dl_correr() busca en carpeta_salida la corrida más reciente de cada subtipo que entra en la suma, del año que se estima, y las suma simulación a simulación con dl_sumar_hijas(), con el nombre y los subtipos_omitidos de la configuración. Las corridas se reconocen por su manifiesto (la causa y el año), así que valen las de cualquier proyecto escritas en esa carpeta. Con rapido = TRUE suma las corridas de prueba (las que terminan en -prueba) y la suma también es de prueba; con rapido = FALSE, las de producción, nunca las de prueba. Si falta la corrida de un subtipo, el error dice cuál, de qué año y dónde se buscó. Con anios, suma cada año con las corridas de ese año. semilla, sensibilidad, opciones y forzar no se usan: no hay ajuste. El nombre de la corrida sigue la misma regla (causa-<causa>, con el año y -prueba si corresponde), y la corrida es la de dl_sumar_hijas(): celdas, simulaciones y manifiesto, sin diagnósticos.

La corrida más reciente de un subtipo es la del último día (la fecha de su nombre) y, en ese día, la de mayor versión. Si ese día hay corridas del subtipo con nombres distintos (por ejemplo causa-<causa> y causa-<causa>-<año>), gana la que se escribió última, por la fecha de modificación de su manifest.yaml: copiar la carpeta de las corridas sin conservar las fechas de los archivos puede cambiar ese desempate. Los mensajes dicen qué corrida se tomó de cada subtipo y cuáles se escribieron con forzar = TRUE, que en una suma de producción quedan también entre las limitaciones de su manifiesto; para elegirlas a mano, dl_sumar_hijas(). Los subtipos de una suma son causas que se ajustan: una suma no puede ser subtipo de otra suma.

Los ajustes quedan en la caché de la sesión: dl_ajustar() con los mismos insumos, opciones y semilla devuelve el de la corrida sin volver a muestrear. Con un proyecto con las tablas del contrato, los mensajes de todos los pasos citan sus claves y sus tablas (como dl_insumos()).

Examples

# \donttest{
# una prueba con el ejemplo; la corrida se escribe en una carpeta temporal
salida <- file.path(tempdir(), "resultados")
run <- dl_correr(dl_ejemplo(), causa = 9100, 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
list.files(run$dir, recursive = TRUE)
#>  [1] "cause/incidence/2026-10-15_causa-9100-prueba_v1.csv" 
#>  [2] "cause/prevalence/2026-10-15_causa-9100-prueba_v1.csv"
#>  [3] "cause/yld/2026-10-15_causa-9100-prueba_v1.csv"       
#>  [4] "diagnostics/aceptacion.csv"                          
#>  [5] "diagnostics/amplitud.csv"                            
#>  [6] "diagnostics/desplazamiento_splits.csv"               
#>  [7] "diagnostics/dx_bandas.csv"                           
#>  [8] "diagnostics/mcmc.csv"                                
#>  [9] "diagnostics/proxies_series.csv"                      
#> [10] "diagnostics/renorm.csv"                              
#> [11] "diagnostics/validacion.csv"                          
#> [12] "draws/incidence_2023.csv.gz"                         
#> [13] "draws/prevalence_2023.csv.gz"                        
#> [14] "draws/yld_2023.csv.gz"                               
#> [15] "etiquetas/2026-10-15_causa-9100-prueba_v1.csv"       
#> [16] "inputs/betas.csv"                                    
#> [17] "inputs/config_usado.yaml"                            
#> [18] "inputs/contrato/ancla.csv"                           
#> [19] "inputs/contrato/betas.csv"                           
#> [20] "inputs/contrato/config.yaml"                         
#> [21] "inputs/contrato/covariables.csv"                     
#> [22] "inputs/contrato/datos.csv"                           
#> [23] "inputs/contrato/poblacion.csv"                       
#> [24] "inputs/contrato/proxies_crudos.csv"                  
#> [25] "inputs/contrato/severidad.csv"                       
#> [26] "inputs/contrato/ubicaciones.csv"                     
#> [27] "inputs/cov_proxy.csv"                                
#> [28] "inputs/cov_valores.csv"                              
#> [29] "inputs/crosswalks.csv"                               
#> [30] "inputs/datos.csv"                                    
#> [31] "inputs/hash.json"                                    
#> [32] "inputs/poblacion.csv"                                
#> [33] "inputs/prior_gbd.csv"                                
#> [34] "inputs/sequela_map.csv"                              
#> [35] "inputs/severidad.csv"                                
#> [36] "manifest.yaml"                                       
# la prevalencia por banda de edad, nacional y subnacional
prev <- read.csv(file.path(run$dir, "cause", "prevalence", paste0(run$run_id, ".csv")),
                 fileEncoding = "UTF-8")
head(prev[, c("location_name", "sex_name", "age_group_name", "val", "lower", "upper")])
#>   location_name sex_name age_group_name        val       lower      upper
#> 1          Perú     Male    40-44 years 0.01274434 0.009321281 0.01653482
#> 2          Perú     Male    45-49 years 0.01897328 0.015643420 0.02291474
#> 3          Perú     Male    50-54 years 0.02581334 0.021226377 0.03130308
#> 4          Perú     Male    55-59 years 0.03340600 0.027504514 0.04002152
#> 5          Perú     Male    60-64 years 0.04196389 0.034660406 0.05038544
#> 6          Perú     Male    65-69 years 0.05226160 0.043213559 0.05996622
# lo que registra el manifiesto: las claves de la configuración tomadas por defecto
run$manifest$configuracion$por_defecto
#> $sexos
#> [1] "[hombres, mujeres]"
#> 
#> $ubicacion_gbd
#> [1] "123"
#> 
#> $ancla.peso
#> [1] "1"
#> 
#> $ancla.correlacion_edad
#> [1] "0.5"
#> 
#> $ancla.anio
#> [1] "2023"
#> 
#> $nudos
#> [1] "[30, 40, 50, 60, 70, 80, 95]"
#> 
#> $incidencia.suavidad
#> [1] "0.5"
#> 
#> $mortalidad_exceso.prior
#> [1] "desde_ancla"
#> 
#> $remision
#> [1] "0"
#> 
#> $datos_en_ajuste
#> [1] "ninguno — las nacionales no se usan; las subnacionales de mortalidad validan"
#> 
#> $subnacional.modo
#> [1] "covariables"
#> 
#> $subnacional.kappa
#> [1] "1"
#> 
#> $sensibilidad.correlacion_edad
#> [1] "[0, 0.5, 0.9]"
#> 
#> $sensibilidad.kappa
#> [1] "[0.5, 1]"
#> 
unlink(salida, recursive = TRUE)

# la misma causa para dos años: una corrida por año, que el proyecto relee para cada uno
corridas <- dl_correr(dl_ejemplo(), causa = 9100, semilla = 1, rapido = TRUE, sensibilidad = FALSE,
                      carpeta_salida = salida, anios = c(2019, 2023))
#> 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(): año 2019 (1 de 2)
#> 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-2019-prueba_v1 (prueba: no sirve para publicar)
#> dl_correr(): año 2023 (2 de 2)
#> 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-2023-prueba_v1 (prueba: no sirve para publicar)
corridas
#> <dl_corridas> 2 corrida(s), una por año
#>   2019: 2026-10-15_causa-9100-2019-prueba_v1
#>   2023: 2026-10-15_causa-9100-2023-prueba_v1
corridas[["2023"]]$run_id
#> [1] "2026-10-15_causa-9100-2023-prueba_v1"
unlink(salida, recursive = TRUE)

# la corrida de producción de un proyecto propio: las cadenas por defecto (1000 simulaciones,
# 4 cadenas de 50 000 iteraciones) o las mismas con el motor en C++, más rápido
# dl_correr("mi_proyecto", semilla = 1)
# dl_correr("mi_proyecto", semilla = 1, opciones = dl_opciones_mcmc(motor = "rcpp"))
# y, para mirar una corrida cuyas cadenas aún no convergen, sin la compuerta de la convergencia
# dl_correr("mi_proyecto", semilla = 1, forzar = TRUE)
# y una corrida de producción por año
# dl_correr("mi_proyecto", semilla = 1, anios = 2018:2023)

# una causa que es la suma de sus subtipos: en una copia del ejemplo, la causa 9100, que declara
# sus subtipos (9101, 9102 y 9103), deja de ajustarse con `suma_de_subtipos: sí`
carpeta <- dl_ejemplo(copiar_en = file.path(tempdir(), "proyecto_con_suma"))
con <- file(file.path(carpeta, "config", "9100.yaml"), open = "a", encoding = "UTF-8")
writeLines("suma_de_subtipos: sí", con)
close(con)
dl_proyecto(carpeta, causa = 9100)
#> <dl_proyecto> Arteriopatía crónica sintética, causa 9100 | año 2023 | tablas del contrato
#>   carpeta: /tmp/RtmpucVo2P/proyecto_con_suma
#>   suma de los subtipos 9101 + 9102 + 9103: no se ajusta; dl_correr() suma las corridas de sus subtipos
#>   tablas:
#>     ubicaciones 26 fila(s), de ubicaciones.csv
#>     poblacion   2100 fila(s), de poblacion.csv
# primero una corrida de cada subtipo (aquí, de prueba) y después la suma, que las busca en la
# carpeta de las corridas (`resultados`, en la carpeta del proyecto)
for (k in c(9101, 9102, 9103))
  dl_correr(carpeta, causa = k, semilla = 1, rapido = TRUE, sensibilidad = FALSE)
#> 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 9101: insumos
#> 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(): se omite la validación con la mortalidad subnacional reservada: los datos no la traen
#> dl_correr(): etiquetas de cuánto informan los datos
#> dl_correr(): corrida escrita en /tmp/RtmpucVo2P/proyecto_con_suma/resultados/mod/dismod_lite/2026-10-15_causa-9101-prueba_v1 (prueba: no sirve para publicar)
#> 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 9102: insumos
#> 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(): se omite la validación con la mortalidad subnacional reservada: los datos no la traen
#> dl_correr(): etiquetas de cuánto informan los datos
#> dl_correr(): corrida escrita en /tmp/RtmpucVo2P/proyecto_con_suma/resultados/mod/dismod_lite/2026-10-15_causa-9102-prueba_v1 (prueba: no sirve para publicar)
#> 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 9103: insumos
#> 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(): se omite la validación con la mortalidad subnacional reservada: los datos no la traen
#> dl_correr(): etiquetas de cuánto informan los datos
#> dl_correr(): corrida escrita en /tmp/RtmpucVo2P/proyecto_con_suma/resultados/mod/dismod_lite/2026-10-15_causa-9103-prueba_v1 (prueba: no sirve para publicar)
suma <- dl_correr(carpeta, causa = 9100, rapido = TRUE)
#> dl_correr(): causa 9100: suma de los subtipos 9101 + 9102 + 9103, con sus corridas de prueba de 2023 en /tmp/RtmpucVo2P/proyecto_con_suma/resultados/mod/dismod_lite
#> dl_correr(): 9101: 2026-10-15_causa-9101-prueba_v1
#> dl_correr(): 9102: 2026-10-15_causa-9102-prueba_v1
#> dl_correr(): 9103: 2026-10-15_causa-9103-prueba_v1
#> dl_correr(): corrida escrita en /tmp/RtmpucVo2P/proyecto_con_suma/resultados/mod/dismod_lite/2026-10-15_causa-9100-prueba_v1 (prueba: no sirve para publicar)
vapply(suma$manifest$causa$hijas, `[[`, "", "run_id")
#> [1] "2026-10-15_causa-9101-prueba_v1" "2026-10-15_causa-9102-prueba_v1"
#> [3] "2026-10-15_causa-9103-prueba_v1"
unlink(carpeta, recursive = TRUE)
# }

Usage

Arguments

Value

Details

See also

Examples