Configuración de una causa

Lee la configuración de una causa, le aplica los cambios y valida todos los campos. Lee los dos formatos: la configuración de un proyecto (corta, con las claves de la tabla de abajo) y el formato completo (schema: dismod_lite/v1). La configuración de un proyecto se traduce a la completa y pasa por la misma validación; sus errores citan su clave y, entre paréntesis, la del formato completo (ancla.peso (anchor.lambda): ...). Los errores de una configuración completa citan la ruta del campo (config.anchor.lambda, ...).

Usage

dl_configuracion(causa, carpeta_config = NULL, cambios = NULL)

Arguments

causa: Identificador de la causa (cause_id).
carpeta_config: La carpeta que tiene la configuración (<causa>.yaml, o config.yaml en un proyecto de una sola causa), la carpeta de un proyecto (con config/<causa>.yaml) o la ruta del archivo de configuración.
cambios: Lista con nombres que se funde sobre la configuración antes de validar, con las claves del formato completo (también para la configuración de un proyecto: se aplica sobre su traducción), por ejemplo list(anchor = list(lambda = 0.5)): cada clave reemplaza a la de la configuración y una lista con nombres se funde clave a clave; NULL quita la clave. Una secuencia (c("csmr", "incidencia"), o list(list(...)) para registros como remision.por_edad) reemplaza entera a la de la configuración. Una clave que la configuración no tiene es un error.

Value

Objeto de clase dl_config: la configuración validada, en el formato completo, una lista con sus claves (cause_id, years, sexos, edad_inicio, remision, emr_prior, nudos_incidencia, sigma_suavidad, anchor, medidas_entrada, cascada, transformaciones, covariables, severidad, sensibilidad, decisiones y las demás que declare; la columna «Formato completo» de la tabla de claves dice de qué clave del proyecto sale cada una). La de un proyecto trae además origen: formato ("simple"), archivo, nombre (el de la causa), subnacional (el modo subnacional: covariables, plano, razon o no), unidades ("contrato": las tablas del proyecto ya vienen en las unidades del modelo), betas (la tabla betas de la causa), por_defecto (las claves tomadas por defecto, con su valor, como texto) y configuracion (la configuración del proyecto tal como se leyó, con los nombres de clave de ahora: la que la corrida congela en inputs/contrato/config.yaml).

Configuración de un proyecto

Lo mínimo son tres claves: causa, anio y edad_inicio (y ubicacion_gbd, el location_id de GBD del país, si las descargas traen más de una ubicación y el código nacional de ubicaciones no es su location_id). Todo lo demás tiene un valor por defecto, que dl_proyecto() muestra y cada corrida registra. Las covariables con efecto y sus betas no se declaran aquí: son la tabla betas del proyecto (ver dl_tablas). La configuración guarda decisiones; los números con su fuente van en las tablas. Por eso, con la carpeta de un proyecto, dl_configuracion() lee también sus tablas (de ellas salen la ubicación nacional, las betas y lo que la traducción necesita): una tabla con un error lo detiene, como a dl_proyecto(). Un ejemplo con datos locales en el ajuste, una partición de severidad y subtipos:

causa: 1234
nombre: Enfermedad de ejemplo
anio: 2023
edad_inicio: 30
ubicacion_gbd: 130
ancla:
  peso: 0.5                  # los datos locales ya informaron la estimación de referencia
nudos: [30, 40, 50, 60, 70, 80, 95]
mortalidad_exceso:
  techo: 0.25                # por persona-año
datos_en_ajuste: [prevalencia, mortalidad]
severidad:
  particion: particion/mi_corrida   # carpeta de la corrida de partición, relativa al proyecto
  padre: 1230                       # la causa cuya partición reparte las secuelas
componente:
  secuelas: [5001, 5002]            # las secuelas que forman el componente que se modela
subtipos: [1235, 1236, 1237]
notas:
  - ancla.peso 0.5 porque el estudio de prevalencia entró a la estimación de referencia.

Las claves con punto van dentro de su bloque (ancla.peso es peso: bajo ancla:). Las covariables actúan solo en la estimación subnacional: con sus valores por ubicación en la tabla covariables, la diferencia de log i (o de log f, con efecto_sobre: mortalidad_exceso en la tabla betas) de cada ubicación es beta por su diferencia con el valor nacional; el ajuste nacional no cambia. Para una causa sin muertes, mortalidad_exceso: {prior: cero} fija la mortalidad en exceso en 0 y no la estima: no usa la mortalidad del ancla y no admite techo, fracción aguda ni datos de mortalidad en el ajuste. Si el proyecto trae proxies_crudos, leerlo la calibra para el año que se estima (anio, o el de cambios) con las claves proxies.* (dl_calibrar_proxies()). avanzado: pasa claves del formato completo tal cual y se aplica al final (para expertos). El bloque subnacional también se puede llamar departamentos, su nombre anterior. La carpeta del proyecto y sus archivos: ver dl_proyecto(). Todas las claves, con su valor por defecto, están en la tabla de la sección siguiente.

Claves de la configuración de un proyecto

Entre paréntesis, el símbolo del parámetro en el modelo. «Por defecto» es el valor de la clave cuando la configuración no la trae; «Formato completo», dónde queda el valor en la traducción al formato completo: la clave que citan los errores y que se puede ajustar en avanzado, con la forma del formato completo (emr_prior.cota es [0, techo]; years.ancla y cascada.heldout_anio son {valor, procedencia}; cascada.modo solo admite plana), o el archivo de la traducción donde queda. El reparto por razón se declara solo con subnacional.modo: razon: avanzado: {cascada: {modo: }} no puede cambiar el modo a razon ni desde razon. La semilla del sorteo de las razones es la de la corrida; otra se fija con avanzado: {cascada: {razon_semilla: <entero>}}.

Clave	Tipo	Qué es	Por defecto	Formato completo
`causa`	entero	Identificador de la causa: un entero (el cause_id de GBD si la causa existe en GBD). Ejemplo: `1234`.	obligatoria	`cause_id`
`nombre`	texto	Nombre de la causa que muestra print() del proyecto y que llevan las etiquetas en español del proyecto; las tablas de la corrida y su manifiesto llevan el cause_name del ancla. Ejemplo: `Enfermedad de ejemplo`.	el cause_name de la descarga del ancla
`anio`	entero	Año que se estima. Ejemplo: `2023`.	obligatoria	`years.ajuste`
`sexos`	lista de textos	Sexos que se estiman: hombres y mujeres (o sus códigos 1 y 2); una causa de un solo sexo lleva solo ese. Ejemplo: `[mujeres]`.	`[hombres, mujeres]`	`sexos`
`edad_inicio`	número	Primera edad del modelo, en años; ahí la prevalencia es 0. Una causa con `suma_de_subtipos: sí` no la necesita. Ejemplo: `30`.	obligatoria	`edad_inicio`
`ubicacion_gbd`	entero	location_id de GBD del país: el de las filas nacionales de las descargas de GBD Results y del GHDx. Hace falta solo si las descargas traen varias ubicaciones y el código nacional de ubicaciones.csv no es su location_id. Ejemplo: `130`.	el código nacional de ubicaciones.csv, si es un location_id de las descargas; o la única ubicación
`ancla.peso` (λ)	número	Peso de la estimación de referencia, en (0, 1]: 1 la toma a peso completo; menos (por ejemplo 0.5) si los datos locales que entran al ajuste ya informaron esa estimación. Ejemplo: `0.5`.	`1`	`anchor.lambda`
`ancla.correlacion_edad` (ρ)	número	Correlación entre las bandas de edad vecinas del ancla, en [0, 1). Ejemplo: `0.8`.	`0.5`	`anchor.rho_edad`
`ancla.anio`	entero	Año de la estimación de referencia cuando no es `anio`: a lo sumo un año antes, para proyectar el último año publicado (por ejemplo 2023 con anio 2024). Si el proyecto se lee para un año anterior al declarado (`dl_proyecto(anio = )`), el ancla es la de ese año: la misma configuración sirve para los años anteriores. Sin esta clave, si la tabla ancla no trae la prevalencia de la causa en `anio`, se proyecta desde el último año anterior que trae, con un mensaje. Ejemplo: `2023`.	el valor de `anio`	`years.ancla`
`ancla.error_maximo`	número	Error relativo mediano máximo, en (0, 1), entre la prevalencia ajustada y la del ancla con que se escribe la corrida: la compuerta del ancla, que ni `rapido` ni `forzar` saltan. Se sube solo con una razón (los datos locales son mejores que el ancla, el ancla tiene pocas bandas de edad; anótala en `notas`): la corrida declara el umbral entre sus limitaciones. Ejemplo: `0.08`.	0.05	`anchor.gate_err_mediano`
`nudos`	lista de números	Edades de los nudos, crecientes: las de la incidencia y las de la mortalidad en exceso (las mismas para las dos); log i y log f son lineales entre nudos. Ejemplo: `[30, 40, 50, 60, 70, 80, 95]`.	cada 10 años desde edad_inicio hasta 80, y 95	`nudos_incidencia`
`incidencia.suavidad` (σ)	número	Suavidad de la incidencia, un número > 0: la desviación estándar de las segundas diferencias de log i entre nudos. Un valor mayor permite una curva menos suave. Ejemplo: `1`.	`0.5`	`sigma_suavidad`
`mortalidad_exceso.prior`	texto	Prior de la mortalidad en exceso (EMR): desde_ancla (por edad, de las muertes y la prevalencia del ancla), plano (sin prior por edad, solo el techo), cero (la EMR queda fija en 0 y no se estima: para una causa sin muertes; no usa la mortalidad del ancla ni admite mortalidad_exceso.techo, mortalidad_exceso.fraccion_aguda, sensibilidad.fraccion_aguda ni mortalidad en datos_en_ajuste) o tabla (por sexo y edad, de la tabla prior_mortalidad_exceso del proyecto: el centro y la desviación estándar de log EMR de cada tramo de edad, con el centro bajo el techo; no usa la mortalidad del ancla, salvo para el techo si no se da mortalidad_exceso.techo: mortalidad_exceso.fraccion_aguda no cambia el prior, solo ese techo y la declaración de la fase aguda en la corrida, y no admite sensibilidad.fraccion_aguda). Ejemplo: `plano`.	`desde_ancla`	`emr_prior.tipo`
`mortalidad_exceso.techo`	número	Techo de la EMR, un número > 0, por persona-año. Ejemplo: `0.25`.	3 veces la EMR máxima del ancla	`emr_prior.cota`
`mortalidad_exceso.fraccion_aguda`	número	Fracción de las muertes de la causa que ocurre en su fase aguda, en [0, 1): GBD reparte las muertes de algunas causas entre una fase aguda (los primeros 28 días, con su propio modelo) y la crónica, que es la que modela dismodlite, con una razón que no publica. Esa fracción se descuenta del csmr del ancla en el prior y el techo de la EMR; sin la clave no se descuenta nada. Anota en `notas` de dónde sale. Ejemplo: `0.3`.	sin valor	`emr_prior.fraccion_aguda`
`remision`	número	Remisión, un número >= 0, por persona-año (0 es una causa crónica). Ejemplo: `0.1`.	`0`	`remision.valor`
`datos_en_ajuste`	lista de textos	Tipos de la tabla datos cuyas filas nacionales entran al ajuste: prevalencia (de estudios; también se admite prevalencia_estudio), incidencia, mortalidad. Ejemplo: `[prevalencia, mortalidad]`.	ninguno: las nacionales no se usan; las subnacionales de mortalidad validan	`medidas_entrada`
`severidad.particion`	texto	Carpeta de una corrida de partición de severidad, relativa a la carpeta del proyecto (sin carpeta, al directorio de trabajo). La tabla severidad de la causa sale de ella (con los pesos de discapacidad de GBD) en vez de la tabla severidad. En una hija o un componente, sus límites pueden pasar de 1 (los de la partición divididos por su cuota): se aceptan con un aviso. La corrida copia esta carpeta en inputs/contrato/particion/<corrida>/. Ejemplo: `particion/mi_corrida`.	sin valor	`severidad.run_id`
`severidad.padre`	entero	Causa padre cuya partición reparte las secuelas de esta causa (la causa es una hija dentro de la partición del padre). Solo con severidad.particion. Ejemplo: `1010`.	sin valor	`severidad.padre`
`componente.secuelas`	lista de enteros	Secuelas que forman el componente que se modela: el ancla se escala a su fracción de prevalencia y la severidad es la del componente. Necesita severidad.particion. Ejemplo: `[5001, 5002]`.	sin valor	`anchor.componente.sequela_ids`
`subnacional.modo`	texto	Estimación subnacional: covariables (gradiente por las covariables de la tabla betas), plano (las tasas nacionales en cada ubicación), razon (las tasas nacionales por la razón de cada ubicación, de la tabla razones, con cierre en el nacional) o no (sin estimación subnacional). Ejemplo: `plano`.	covariables si alguna covariable de la tabla betas tiene filas subnacionales en la tabla covariables; si no, plano si la población trae otras ubicaciones; si no, no	`cascada.modo`
`subnacional.kappa` (κ)	número	Fuerza del efecto subnacional de las covariables, en (0, 1]. Ejemplo: `0.5`.	`1`	`cascada.kappa`
`subnacional.anio_validacion`	entero	Año de los datos subnacionales de datos.csv reservados para validar. Ejemplo: `2019`.	el valor de `anio`	`cascada.heldout_anio`
`proxies.metodo`	texto	Cómo se obtiene el gradiente subnacional del año que se estima desde proxies_crudos: paseo_aleatorio suaviza todas las ediciones (q por máxima verosimilitud; ver ?dl_calibrar_proxies); edicion usa la del año o la más cercana. Ejemplo: `edicion`.	`paseo_aleatorio`
`proxies.transformacion`	bloque	Por covariable: cociente (tasas y proporciones; por defecto) o diferencia (índices). Cada clave es una covariable de proxies_crudos. Ejemplo: `{haqi: diferencia}`.	sin valor
`proxies.excluir`	lista de registros	Ediciones de proxies_crudos que no entran, cada una con anio y motivo. Ejemplo: `[{anio: 2021, motivo: cambio de modo de la encuesta}]`.	sin valor
`sensibilidad.peso` (λ)	lista de números	Valores de ancla.peso del análisis de sensibilidad. Ejemplo: `[0.5, 1]`.	`[0.25, 0.5, 1]`	`sensibilidad.lambda`
`sensibilidad.correlacion_edad` (ρ)	lista de números	Valores de ancla.correlacion_edad del análisis de sensibilidad. Ejemplo: `[0, 0.9]`.	`[0, 0.5, 0.9]`	`sensibilidad.rho`
`sensibilidad.kappa` (κ)	lista de números	Valores de subnacional.kappa del análisis de sensibilidad. Ejemplo: `[1]`.	`[0.5, 1]`	`sensibilidad.kappa`
`sensibilidad.fraccion_aguda`	lista de números	Valores de mortalidad_exceso.fraccion_aguda del análisis de sensibilidad, cada uno en [0, 1); sin la clave, la sensibilidad no varía la fracción aguda. Ejemplo: `[0, 0.3, 0.5]`.	sin valor	`sensibilidad.fraccion_aguda`
`subtipos`	lista de enteros	Causas hijas cuya suma es esta causa (solo en la configuración de la causa padre): cada una tiene su configuración (en el mismo proyecto, config/<causa>.yaml, que la reconoce como subtipo: sin betas propias, usa las de esta causa; o en su propia carpeta, con `subtipo_de`). Un subtipo tiene una sola causa padre. Con `suma_de_subtipos: sí`, dl_correr() suma sus corridas (ver ?dl_proyecto). Ejemplo: `[1011, 1012, 1013]`.	sin valor
`suma_de_subtipos`	sí o no	Con sí, la causa no se ajusta: es la suma, simulación a simulación, de las corridas de sus `subtipos`, y dl_correr() la suma. Exige `subtipos` y `nombre`. El proyecto de una suma solo usa las tablas ubicaciones y poblacion y las claves causa, nombre, anio, sexos, ubicacion_gbd, subtipos, subtipos_omitidos y notas: no necesita edad_inicio, ancla, severidad ni betas. Ejemplo: `sí`.	no
`subtipos_omitidos[].causa`	entero	Un subtipo de `subtipos` que no se modela y no entra en la suma (solo con `suma_de_subtipos: sí`): la suma queda por debajo de la causa en su parte y la corrida lo declara. Ejemplo: `1013`.	obligatoria	`suma.omitidas[].cause_id`
`subtipos_omitidos[].motivo`	texto	Por qué el subtipo no entra en la suma; queda entre las limitaciones de la corrida. Ejemplo: `sin datos suficientes`.	obligatoria	`suma.omitidas[].motivo`
`subtipo_de`	entero	Causa padre de esta causa, para un subtipo que se lee en su propia carpeta, sin la configuración de su padre: si la tabla betas no trae filas de la causa, usa las de la causa padre, y la corrida declara a la causa padre, que la suma exige (dl_correr() de una causa con `suma_de_subtipos`, o dl_sumar_hijas()). Si la configuración del padre la declara en `subtipos`, la relación sale sola y las dos deben decir la misma causa (ver ?dl_proyecto). Ejemplo: `1010`.	sin valor	`extraction.cause_id`
`exportar.incidencia`	sí o no	Con no, la incidencia de la causa no entra en las tablas consolidadas (dl_consolidar()): la corrida la escribe igual (cause/incidence/ y draws/), para el diagnóstico y las sumas, y su manifiesto lo declara. Sirve para una causa cuya incidencia el modelo no identifica (la fija la remisión declarada, sin datos de incidencia). Anota el motivo en `notas`. Ejemplo: `no`.	`sí`	`exportar.incidencia`
`notas`	lista de textos	Decisiones que quedan registradas en cada corrida. Ejemplo: `[la encuesta nacional ya entró a la estimación de referencia]`.	sin valor	`decisiones`
`avanzado`	bloque	Claves del formato completo, tal cual: se aplican al final, sobre la traducción (para expertos). Ejemplo: `{nsub: 10}`.	sin valor

Formato completo

Una configuración es del formato completo si trae schema: dismod_lite/v1; si no, es la de un proyecto. Es el formato de la versión 0.2.2: cada decisión va con su procedencia (edad_inicio_fuente, remision.fuente, emr_prior.fuente_cota, los bloques {valor, procedencia}) y la ubicación del ancla se declara con anchor.location_id (las configuraciones escritas para esa versión usan anchor.location). La configuración completa del ejemplo: system.file("extdata", "acs_peru_completo", "config", "9100.yaml", package = "dismodlite").

La configuración de un proyecto se traduce a la completa: cada clave va a la de la columna «Formato completo» de la tabla de claves, cada procedencia que el formato completo exige dice «declarado en la configuración del proyecto», y las claves tomadas por defecto quedan en origen$por_defecto (y en el manifiesto de cada corrida, en configuracion.por_defecto). Sobre esa traducción se aplican, en este orden, el bloque avanzado: de la configuración y el argumento cambios, los dos con claves del formato completo (así que avanzado manda sobre la clave corta que traduce a la misma). Por ejemplo, para relajar el prior de la mortalidad en exceso:

avanzado:
  emr_prior:
    factor_sd: {valor: 1.5, procedencia: el prior por edad del ancla es más estrecho que los datos}

Algunas claves del formato completo sin equivalente en la configuración de un proyecto, útiles en avanzado (entre paréntesis, el valor cuando la clave no está):

offset_lognormal: desplazamiento de la verosimilitud log-normal (0). Hace falta si un dato local con valor y error_estandar vale 0, o si el ancla trae un valor o un límite inferior 0 en una banda donde GBD modela la causa.
edad_fin: la última edad del modelo (99).
nsub: los subpasos por año del método numérico que resuelve el modelo (5, es decir, pasos de 0.2 años).
remision.por_edad: remisión por tramo de edad, una lista de {edad_inicio, edad_fin, valor, fuente}; fuera de los tramos rige remision.
emr_prior.factor_techo: sin mortalidad_exceso.techo, el techo de la EMR es este factor por la EMR máxima del ancla (3).
emr_prior.factor_sd: {valor, procedencia}, con valor mayor o igual que 1: multiplica la desviación estándar del prior de la EMR (1: el prior tal cual).
emr_prior.fraccion_aguda.cfr_30d: la letalidad a 30 días de la fase aguda, en (0, 1), junto a mortalidad_exceso.fraccion_aguda (avanzado: {emr_prior: {fraccion_aguda: {cfr_30d: 0.1}}}): la comprobación implied_incidence de dl_validar_ancla() compara entonces con la incidencia del ancla por (1 - cfr_30d), la de los sobrevivientes a 28 días.
anchor.metrica_prevalencia: {valor, procedencia}: la métrica en que se lee la prevalencia del ancla. Rate (por defecto) es la proporción de la población, por 100 000. Percent repite lo que hacían las versiones hasta la 1.0.0 y sirve solo para reproducir sus corridas: en GBD Results divide los casos por las personas con alguna causa, no por la población, y sobrestima la prevalencia (menos de 1 % en adultos, hasta 37 % antes de los 2 años).
anchor.agrupar_bandas_finas: true agrupa las bandas de 80-84 a 95+ en 80+ y las de menos de 5 años en <5, como hasta la 1.0.0, con los pesos de su población (en un proyecto, la población nacional de la tabla poblacion en el año del ancla, que entonces debe traer esas bandas; en el formato completo, pesos_80mas); false usa las bandas tal cual llegan (así las deja la traducción de un proyecto, que agrupa con poblacion_detalle solo las que la población no tiene). Por defecto true en el formato completo.
extraction: {cause_id, motivo}: la causa padre de un subtipo, en el formato completo. En un proyecto la declara subtipo_de (un subtipo en su propia carpeta, sin la configuración de su padre) o sale sola de subtipos en la configuración del padre; avanzado: {extraction: {cause_id, motivo}} manda sobre las dos.
cascada.dx_fuera_de_banda: en las edades sin grupo de edad del proxy, cero (sin diferencia con el valor nacional) o vecina (la del grupo más próximo, con procedencia) (cero).
cascada.dx_interpolacion: entre los grupos de edad del proxy, lineal (interpolada entre sus puntos medios) o escalon (constante en cada grupo, con procedencia) (lineal).

Examples

cfg <- dl_configuracion(9100, file.path(dl_ejemplo(), "config"))
cfg$anchor$lambda
#> [1] 1
cfg$origen$por_defecto
#>                                                                         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]" 
# con cambios (claves del formato completo)
cfg <- dl_configuracion(9100, file.path(dl_ejemplo(), "config"),
                        cambios = list(anchor = list(lambda = 0.5)))
# o con una clave más de la configuración del proyecto: aquí, el error del ancla que se acepta
d <- dl_ejemplo(copiar_en = tempfile("proyecto"))
cat("ancla:\n  error_maximo: 0.08\n", file = file.path(d, "config", "9100.yaml"), append = TRUE)
dl_configuracion(9100, d)$anchor$gate_err_mediano
#> $valor
#> [1] 0.08
#> 
#> $procedencia
#> [1] "declarado en la configuración del proyecto"
#>