Proyecto de una causa

Lee un proyecto y devuelve, para una causa, su configuración, sus tablas del contrato de insumos y las rutas de sus insumos: todo lo que dl_insumos() necesita (dl_insumos(dl_proyecto(carpeta))). Es la forma recomendada de empezar.

Usage

dl_proyecto(
  carpeta = NULL,
  causa = NULL,
  ...,
  configuracion = NULL,
  anio = NULL
)

Arguments

carpeta: Carpeta del proyecto: la que tiene config.yaml o config/ (opcional si se dan configuracion y las tablas).
causa: Causa (cause_id, un entero); NULL si el proyecto tiene una sola o la configuración la declara.
...: Tablas del contrato por su nombre (ver dl_tablas: ubicaciones, poblacion, ancla, covariables, betas, datos, severidad, fuentes_gbd, poblacion_detalle, proxies_crudos, razones, prior_mortalidad_exceso): un data.frame o la ruta de un CSV o de una carpeta. Reemplazan a las de la carpeta.
configuracion: Ruta del YAML de la configuración o una lista con sus claves (opcional; por defecto, la de la carpeta).
anio: Año que se estima (un entero), en lugar del anio de la configuración; NULL (por defecto) deja el de la configuración. Ver Detalles para el año del ancla.

Value

Objeto de clase dl_proyecto: una lista con

configuracion: la configuración de la causa, de clase dl_config, como la de dl_configuracion(). Trae origen$por_defecto: las claves tomadas por defecto, con su valor.
rutas: las rutas de los insumos, de clase dl_paths, como las de dl_rutas(). Apuntan a la traducción, en la carpeta temporal de la sesión: en otra sesión, o después de cambiar la configuración o una tabla (la traducción anterior del mismo año se borra), vuelve a llamar a dl_proyecto().
carpeta: la carpeta del proyecto (NULL sin carpeta).
formato: "simple" (un proyecto con las tablas del contrato) o "completo" (el formato de la 0.2.2).
tablas: las tablas del contrato, una lista nombrada de dl_tabla() (NULL en el formato completo), tal como vinieron (covariables sin las filas calibradas). De una suma de subtipos, solo ubicaciones y poblacion.
calibracion: solo si el proyecto trae proxies_crudos, el resultado de dl_calibrar_proxies() (las filas calibradas, con los atributos calibracion, series y excluidas).
configuracion_dada: solo si configuracion se dio como lista, esa lista tal como se dio.
tablas_dadas: solo si se dieron tablas en ..., esas tablas tal como se dieron (un data.frame o una ruta). Con las dos, dl_correr() vuelve a leer el mismo proyecto para cada año de anios.

Details

Un proyecto es una configuración corta (sus claves en dl_configuracion()) y las tablas del contrato de insumos (ver dl_tablas). Hay dos puertas, en una sola función: las tablas se leen de la carpeta del proyecto por su nombre, o se pasan como argumentos (un data.frame o la ruta de un CSV o de una carpeta), y las dos se pueden mezclar: lo que se pasa reemplaza a lo de la carpeta.

p <- dl_proyecto("mi_proyecto")                                  # todo desde la carpeta
p <- dl_proyecto("mi_proyecto", poblacion = mi_pob)              # la carpeta + una tabla de R
p <- dl_proyecto(configuracion = "config.yaml", ubicaciones = ubic,
                 poblacion = mi_pob, ancla = "descargas/gbd_2023.csv")   # sin carpeta

Cada tabla pasa por su lector (las descargas de GBD Results y del GHDx se reconocen por sus columnas y se convierten solas) y se valida sola; un problema de una tabla detiene dl_proyecto() con la tabla, la columna y las filas. Después, dl_proyecto() comprueba las reglas que cruzan tablas (que haya una sola ubicación nacional y que las ubicaciones de las demás tablas estén en ubicaciones, que la población y el ancla cubran el año, los sexos y las edades del modelo, que cada beta tenga su valor nacional, que la severidad sume 1...): se detiene con todos sus problemas juntos (en el campo problemas del error) y avisa de sus sospechas (una mortalidad de datos que parece por 100 000, una ubicación subnacional sin proxies...). dl_revisar_proyecto() comprueba lo mismo sin detenerse en el primer problema, y dl_insumos() lo que necesita las tablas ya traducidas (la población nacional suma las subnacionales, los proxies cierran en el valor nacional, los datos tienen valores posibles).

El proyecto se traduce al formato completo de la versión 0.2.2, el que usa el resto del paquete: la configuración y las tablas a una carpeta temporal de la sesión, que se reutiliza mientras no cambien. Los números leídos pasan tal cual; solo se calcula lo que sale de la población (el total nacional, si no viene) y la agrupación del ancla en las bandas de la población (con poblacion_detalle, si el ancla es más fina; sus filas de ambos sexos, que el modelo no usa, no piden ese detalle y se dejan fuera si no lo traen).

print() muestra la causa, el año, las tablas que encontró, el modo subnacional, la calibración de proxies_crudos (por covariable: el método, q y las ediciones) y las claves de la configuración que tomaron su valor por defecto.

anio lee el proyecto para otro año que el de su configuración, sin editarla: es como escribir ese anio en el archivo (los proxies de proxies_crudos se calibran para ese año). Las lecturas de años distintos del mismo proyecto conviven en la sesión. El año del ancla, el de la estimación de referencia que se usa, sale de una sola regla:

sin ancla.anio en la configuración, es el año que se estima si la tabla ancla trae la prevalencia de la causa en ese año; si no la trae, el último año anterior que trae, y un mensaje lo anuncia («el ancla no trae 2024: se proyecta desde 2023»). La proyección queda en la procedencia del año del ancla (years.ancla) y en las limitaciones del manifiesto de la corrida, y dl_revisar_proyecto() la muestra como aviso;
con ancla.anio, ese año, que no puede ser posterior al anio de la configuración. Con el argumento anio es el menor entre los dos: una configuración con anio: 2024 y ancla: {anio: 2023} sirve para 2024 (proyectado desde 2023) y, con anio = 2023 o un año anterior, para ese año con su propia ancla. El argumento anio solo baja el año del ancla declarado con ancla.anio: uno declarado en avanzado (o en years.ancla del formato completo) no se ajusta solo, y para un año anterior hay que cambiarlo en la configuración;
el ancla es, a lo sumo, de un año antes del que se estima: mantiene el nivel nacional, no lo extrapola. Si el ancla no trae el año ni ninguno anterior, las reglas entre tablas dicen qué falta.

Sin carpeta, las rutas relativas de la configuración (severidad.particion) se resuelven contra el directorio de trabajo; con carpeta, contra la carpeta del proyecto. Las secuelas y los estados de salud de una partición de severidad deben estar en los catálogos de GBD 2023 del paquete: una partición con secuelas propias todavía no se puede leer en un proyecto (sí en el formato completo, con sus catálogos).

La carpeta del proyecto

mi_proyecto/
  config.yaml          # una causa; o config/<causa>.yaml, una por causa
  ubicaciones.csv
  poblacion.csv
  ancla/               # cualquier CSV: descargas de GBD tal cual o tablas del contrato
  covariables/         # descargas del GHDx y/o la tabla del contrato con los proxies ya calibrados
  betas.csv
  datos.csv
  severidad.csv
  fuentes_gbd/
  poblacion_detalle.csv
  proxies_crudos.csv   # un indicador de encuesta por ubicación y edición: se calibra al leer
  razones.csv          # la razón de cada ubicación subnacional respecto de la nacional (subnacional.modo: razon)
  prior_mortalidad_exceso.csv   # el prior de la mortalidad en exceso por sexo y edad (mortalidad_exceso.prior: tabla)
  particion/<corrida>/ # opcional: la partición de severidad que nombra severidad.particion

Cada tabla es <tabla>.csv o una carpeta <tabla>/ cuyos CSV se juntan (cada uno pasa por su lector), como poblacion_detalle/ con un CSV por fuente. Las rutas no se declaran, salvo la de la partición de severidad (severidad.particion, relativa a la carpeta). Los demás archivos de la carpeta (un LEEME.md, la carpeta resultados/ que escribe dl_correr()) no se leen. Una tabla opcional ausente, o con solo el encabezado, no existe (así quedan las plantillas de dl_nuevo_proyecto()). Las obligatorias son ubicaciones, poblacion y ancla (una causa que es la suma de sus subtipos solo usa las dos primeras: ver «Subtipos y la causa que es su suma»): con ellas se estima la causa en el país y, si hay ubicaciones subnacionales, en cada una con las tasas nacionales. dl_correr(), que calcula los años vividos con discapacidad (AVD), necesita también severidad (o severidad.particion en la configuración). covariables y betas agregan las diferencias entre ubicaciones subnacionales y datos, los datos locales. Las columnas de cada tabla, sus unidades y sus valores están en dl_tablas. Con proxies_crudos, dl_proyecto() calibra los valores subnacionales de sus covariables para el año que se estima (dl_calibrar_proxies(), con las claves proxies.* de la configuración) y los agrega a covariables; los de cada covariable vienen de una sola de las dos tablas.

Con varias causas, cada una tiene su configuración en config/<causa>.yaml y comparten las tablas, que traen las filas de todas en la columna causa (sin ella, una fila vale para todas).

Subtipos y la causa que es su suma

Una causa que es la suma de otras las declara en subtipos; un subtipo sin betas propias usa las de su causa padre. El subtipo encuentra a su padre por esa clave, en otra configuración del mismo proyecto; leído solo (en su propia carpeta), lo declara con subtipo_de: <padre> y, sin betas propias, usa las de esa causa; si las dos configuraciones dicen su padre, deben decir la misma causa. Un subtipo tiene una sola causa padre: que dos configuraciones del proyecto lo declaren en subtipos es un error.

Si la causa padre no se ajusta, sino que se reporta como la suma de las corridas de sus subtipos, su configuración lo dice con suma_de_subtipos: sí:

causa: 1010
nombre: Enfermedad de ejemplo
anio: 2023
subtipos: [1011, 1012, 1013]
suma_de_subtipos: sí
subtipos_omitidos:                 # opcional: los subtipos que no se modelan, con su motivo
  - {causa: 1013, motivo: sin datos suficientes}

El proyecto de una suma solo usa las tablas ubicaciones y poblacion (dan los catálogos de su corrida), que son sus dos tablas obligatorias: no necesita edad_inicio, ancla, severidad ni betas, y las demás tablas de la carpeta, que son de las otras causas, no se leen. Exige nombre (el de la causa en las tablas de su corrida). Puede ser una configuración más de un proyecto con varias causas o vivir en su propia carpeta. print() dice qué suma («suma de los subtipos 1011 + 1012 (omitido: 1013)»), dl_revisar_proyecto() revisa sus dos tablas, su configuración y qué subtipos tienen configuración en el proyecto, y dl_insumos() la rechaza: no hay nada que ajustar. Cada subtipo se corre por separado y dl_correr() de la causa las suma, con las corridas que encuentra en la carpeta de las corridas:

for (k in c(1011, 1012)) dl_correr(carpeta, k, semilla = 1)
dl_correr(carpeta, 1010)

Una causa padre con subtipos y sin suma_de_subtipos se ajusta como cualquier otra, con su ancla. Para sumar corridas elegidas a mano (de otras carpetas, o que no son las más recientes), dl_sumar_hijas().

Formato completo

Un proyecto es del formato completo de la versión 0.2.2 si su configuración trae schema: dismod_lite/v1. Tiene config/<causa>.yaml, ancla/ con un CSV por medida (prevalencia.csv, mortalidad.csv, incidencia.csv y avd.csv, en el formato de las estimaciones), covariables/, extraccion.yaml (las betas), poblacion.csv, pesos_80mas.csv, datos.csv, proxies_departamentales.csv, severidad/<causa>.csv, evidencia/, registro/, catalogos/ y, si hay una, la partición de severidad en particion/<corrida>/. Cada tabla sigue el contrato dismod_lite/v1 (ver dl_esquema()); no recibe tablas en .... El ejemplo en este formato: system.file("extdata", "acs_peru_completo", package = "dismodlite").

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]
p$configuracion$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]" 
p$tablas$poblacion
#>       ubicacion  anio    sexo edad_inicio edad_fin poblacion
#>          <char> <int>  <char>       <num>    <num>     <num>
#>    1:        01  2019 hombres          30       35     16573
#>    2:        01  2019 hombres          35       40     13924
#>    3:        01  2019 hombres          40       45     11698
#>    4:        01  2019 hombres          45       50      9829
#>    5:        01  2019 hombres          50       55      8257
#>   ---                                                       
#> 2096:        25  2024 mujeres          75       80      5385
#> 2097:        25  2024 mujeres          80       85      3712
#> 2098:        25  2024 mujeres          85       90      2375
#> 2099:        25  2024 mujeres          90       95      1285
#> 2100:        25  2024 mujeres          95      125       505

# el mismo proyecto leído para otro año, sin editar la configuración
dl_proyecto(dl_ejemplo(), 9101, anio = 2019)
#> <dl_proyecto> ACS de miembros inferiores, causa 9101 | año 2019 | 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 2019):
#>     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 = 2019
#>     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]

# un proyecto mínimo sin carpeta: la configuración y las tablas obligatorias como argumentos
p <- dl_proyecto(configuracion = list(causa = 9101, anio = 2023, edad_inicio = 30),
                 ubicaciones = dl_ejemplo("ubicaciones.csv"),
                 poblacion = dl_ejemplo("poblacion.csv"), ancla = dl_ejemplo("ancla"))

# una causa que es la suma de sus subtipos: solo su configuración, las ubicaciones y la población
suma <- dl_proyecto(configuracion = list(causa = 9200, nombre = "Suma de ejemplo", anio = 2023,
                                         subtipos = c(9101, 9102, 9103), suma_de_subtipos = "sí"),
                    ubicaciones = dl_ejemplo("ubicaciones.csv"),
                    poblacion = dl_ejemplo("poblacion.csv"))
suma
#> <dl_proyecto> Suma de ejemplo, causa 9200 | año 2023 | tablas del contrato
#>   carpeta: (ninguna: las tablas vienen como argumentos)
#>   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
# \donttest{
# el paso siguiente: los insumos
b <- dl_insumos(p)
# }