Preparar tus datos

Qué vas a aprender

Los insumos de dismodlite son unas pocas tablas, el contrato de insumos, y una configuración corta. Esta guía explica:

el eje: las seis columnas que comparten todas las tablas, y la regla para omitir las que no varían;
las doce tablas: para qué sirve cada una, qué columnas exige y de dónde suele salir;
las dos formas de pasarlas al paquete: la carpeta del proyecto y la puerta de R (data.frame);
cómo revisar una tabla con dl_tabla() y el proyecto entero con dl_revisar_proyecto();
las bandas de edad del ancla y de la población, y cuándo hace falta poblacion_detalle;
qué filtrar al bajar las descargas de GBD y para qué sirve ubicacion_gbd;
cómo se organiza la carpeta de un proyecto de modelación: una causa, varias, subtipos y su suma, la partición de severidad, avanzado y cómo repetir una corrida.

Los ejemplos usan el proyecto de ejemplo (dl_ejemplo(): datos sintéticos de un país, con código nacional 123, y sus 25 ubicaciones subnacionales), pero nada del contrato es propio de ese país: las ubicaciones subnacionales pueden ser departamentos, regiones, provincias o estados, con cualquier código. La referencia completa de las tablas está en ?dl_tablas.

library(dismodlite)
proyecto <- dl_proyecto(dl_ejemplo(), causa = 9100)

1. El eje y la regla de omisión

Todas las tablas describen sus filas con las mismas seis columnas, el eje:

Columna	Qué es	Valores
`causa`	la causa	un entero: el `cause_id` de GBD si la causa existe en GBD, o uno propio
`ubicacion`	la ubicación	un código propio, como texto (`123`, `01`, `norte`)
`anio`	el año calendario	un entero
`sexo`	el sexo	`hombres`, `mujeres` o `ambos` (también `1`, `2`, `3`), sin distinguir mayúsculas
`edad_inicio`, `edad_fin`	la banda de edad $[\text{inicio}, \text{fin})$ , en años	cualquier banda de años enteros; `edad_fin` vacío es la banda abierta («95 y más»)

Cada tabla agrega sus propias columnas de valores (poblacion, valor, beta…).

Regla de omisión. Una columna del eje que no viene significa que la tabla no varía en esa dimensión:

Si falta	La tabla vale para
`causa`	todas las causas del proyecto
`ubicacion`	la ubicación nacional
`anio`	todos los años
`sexo`	ambos sexos
`edad_inicio` y `edad_fin`	todas las edades

Por ejemplo, el valor nacional de una covariable que no cambia con la edad ni con el sexo es una sola fila con su año, sin ubicacion, sexo ni edades:

haqi <- data.frame(covariable = "haqi", anio = 2023, valor = 50.9, inferior = 48.6, superior = 53.2)
dl_tabla("covariables", haqi)
#>     anio covariable valor inferior superior
#>    <int>     <char> <num>    <num>    <num>
#> 1:  2023       haqi  50.9     48.6     53.2

Cada tabla declara qué dimensiones exige: la población, por ejemplo, no tiene sentido sin el sexo. Omitir una dimensión exigida es un error, que dice qué falta:

dl_tabla("poblacion", data.frame(ubicacion = "01", anio = 2023, edad_inicio = 30, edad_fin = 35,
                                 poblacion = 1200))
#> Error:
#> ! dl_tabla(): la tabla poblacion tiene 1 problema(s):
#>   - faltan las columnas sexo (trae: ubicacion, anio, edad_inicio, edad_fin, poblacion)
#>   origen: argumento `x` (data.frame)

Unidades fijas. No hay columna de unidad: la prevalencia y las proporciones van en proporción (entre 0 y 1); la incidencia, la mortalidad y los AVD, por persona-año (no por 100 000); la población, en personas. Los lectores de las descargas de GBD hacen la conversión solos.

Las tablas son CSV en UTF-8, separados por comas y con punto decimal (en Excel, «CSV UTF-8»), o data.frame de R. Los nombres de columna no distinguen mayúsculas y algunos sinónimos fijos se aceptan (year por anio, tipo por medida…); las columnas de más se ignoran.

2. Las doce tablas

Tabla	¿Hace falta?	Qué aporta	De dónde suele salir
`ubicaciones`	siempre	la nacional y las subnacionales	se escribe
`poblacion`	siempre	los pesos para promediar por edad y sumar ubicaciones	instituto de estadística, GBD o la ONU
`ancla`	siempre	la estimación de referencia: prevalencia, mortalidad, AVD, incidencia	GBD Results
`covariables`	si hay `betas`	el valor nacional de cada covariable y, si ya están calibrados, sus proxies subnacionales	GHDx y fuentes nacionales
`betas`	para las diferencias entre ubicaciones	el efecto publicado de cada covariable	el apéndice metodológico de GBD
`datos`	opcional	estudios, registros y estadísticas vitales locales	encuestas y registros propios
`severidad`	para los AVD	los estados de salud de la causa y sus proporciones	GBD, estudios de la causa o una partición
`fuentes_gbd`	opcional	las fuentes que GBD ya usó (doble conteo)	GHDx
`poblacion_detalle`	si el ancla tiene bandas más finas que la población (80 y más, menores de 5)	la población nacional con más detalle de edad	GBD o la ONU
`proxies_crudos`	opcional, en lugar de los proxies de `covariables`	un indicador de encuesta por ubicación subnacional y edición, que el paquete calibra	encuestas de hogares y similares
`razones`	con `subnacional.modo: razon`	la razón entre la tasa de cada ubicación subnacional y la nacional, con su error	una encuesta, la población en riesgo, casos notificados
`prior_mortalidad_exceso`	con `mortalidad_exceso.prior: tabla`	el prior de la mortalidad en exceso por sexo y tramo de edad: centro y desviación estándar de su logaritmo	un estudio de seguimiento, otra corrida, un año vecino

Con las tres obligatorias (y la configuración) ya se estima la causa en el país y, si hay ubicaciones subnacionales, en cada una con las tasas nacionales. Cada tabla, con sus columnas (la definición es la misma que usa el validador; «exige» marca las obligatorias) y tres filas de ejemplo:

`ubicaciones`

Declara una vez las ubicaciones del proyecto. La nacional es la única sin padre; las subnacionales tienen a la nacional de padre. Un proyecto solo nacional tiene una fila. Los códigos son libres y son los que usan las demás tablas.

Columna	Exige	Qué es
`ubicacion`	sí	Código de la ubicación, el que use el proyecto
`nombre`		Nombre de la ubicación en las salidas
`padre`		Ubicación que la contiene: vacío en la nacional, la nacional en las subnacionales

head(proyecto$tablas$ubicaciones, 3)
#>    ubicacion   nombre  padre
#>       <char>   <char> <char>
#> 1:       123     Perú   <NA>
#> 2:        01 Amazonas    123
#> 3:        02   Áncash    123

`poblacion`

La población por ubicación, año, sexo y banda de edad. Sus bandas son las bandas del modelo: reparten las edades sin solaparse y seguidas (sin huecos), desde edad_inicio, y son las mismas en todas las ubicaciones, años y sexos. Trae al menos el año que se estima (y el del ancla, si es otro) y los dos sexos. Las filas nacionales son opcionales: sin ellas, la población nacional es la suma de las subnacionales; si vienen, deben ser esa suma. Fuente habitual: las proyecciones del instituto nacional de estadística, o las de GBD o de la ONU.

Columna	Exige	Qué es
`ubicacion`	sí	Ubicación
`anio`	sí	Año
`sexo`	sí	hombres, mujeres o ambos
`edad_inicio`	sí	Primera edad de la banda (años)
`edad_fin`	sí	Fin de la banda (excluido); vacío en la banda abierta (años)
`poblacion`	sí	Población (personas)

head(proyecto$tablas$poblacion, 3)
#>    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

Al leer un CSV en R, conviene leer ubicacion como texto (read.csv(..., colClasses = c(ubicacion = "character"))) para que un código como 01 no se convierta en el número 1.

`ancla`

La estimación de referencia del país, por año, sexo y banda de edad. No lleva ubicacion: es la nacional. Lleva causa si el proyecto tiene más de una. Lo habitual es poner en ancla/ las descargas de GBD Results tal cual: el lector las reconoce y las convierte (sección 6). También puede ser una tabla propia en el contrato, de otra fuente.

`medida`	Unidad	Para qué se usa	¿Hace falta?
`prevalencia`	proporción	el término principal del ajuste	siempre
`mortalidad`	por persona-año	el prior y el techo de la mortalidad en exceso	con el prior por defecto (`mortalidad_exceso.prior: desde_ancla`); con `prior: cero` no se usa
`avd`	por persona-año	calibra los AVD del modelo a los del ancla	opcional
`incidencia`	por persona-año	solo la validación	opcional

Columna	Exige	Qué es
`causa`		Causa
`anio`	sí	Año
`sexo`	sí	hombres, mujeres o ambos (el modelo no usa las filas de ambos sexos: no hacen falta)
`edad_inicio`	sí	Primera edad de la banda (años)
`edad_fin`	sí	Fin de la banda (excluido); vacío en la banda abierta (años)
`medida`	sí	Qué mide la fila: `prevalencia`, `mortalidad`, `avd`, `incidencia`
`valor`	sí	Estimación (proporción (prevalencia) o por persona-año)
`inferior`	sí	Límite inferior del intervalo del 95 % (igual que valor)
`superior`	sí	Límite superior del intervalo del 95 % (igual que valor)
`nombre_causa`		Nombre de la causa (lo llena el lector de GBD)

ancla <- proyecto$tablas$ancla
head(ancla[ancla$medida == "prevalencia" & ancla$anio == 2023], 3)
#>    causa  anio    sexo edad_inicio edad_fin      medida       valor    inferior
#>    <int> <int>  <char>       <num>    <num>      <char>       <num>       <num>
#> 1:  9100  2023 hombres          40       45 prevalencia 0.012028297 0.008964407
#> 2:  9100  2023 mujeres          40       45 prevalencia 0.009709473 0.007236242
#> 3:  9100  2023 hombres          45       50 prevalencia 0.018018046 0.013428426
#>      superior                   nombre_causa
#>         <num>                         <char>
#> 1: 0.01613938 Arteriopatía crónica sintética
#> 2: 0.01302801 Arteriopatía crónica sintética
#> 3: 0.02417632 Arteriopatía crónica sintética

Las bandas del ancla son también las de los resultados: las tablas de una corrida tienen una fila por banda del ancla. Las edades entre edad_inicio y la primera banda del ancla se modelan (la prevalencia crece desde 0 en edad_inicio), pero no aparecen en esas tablas: en el ejemplo, el ancla empieza en 40-44 años y edad_inicio es 30. Para tener resultados desde edad_inicio, baja el ancla desde esa edad. La sección 5 explica cómo se combinan las bandas del ancla con las de la población.

Se excluyen solas las bandas por debajo de edad_inicio y los ceros estructurales (valor, inferior y superior iguales a 0); dl_revisar_proyecto() lo informa.

`covariables`

El valor de cada covariable, en una sola tabla para dos usos:

las filas nacionales (sin ubicacion, o con la nacional): el valor de referencia, normalmente el de GBD. Se ponen en covariables/ las descargas del GHDx tal cual (sección 6);
las filas subnacionales: el valor de la covariable en cada ubicación, el proxy, con su procedencia en fuente. Vienen ya calibrados en esta tabla o salen de proxies_crudos, que el paquete calibra al leer el proyecto.

La incertidumbre va como error_estandar o como inferior y superior (el intervalo del 95 %). Las covariables no cambian el ajuste nacional: mueven las tasas de cada ubicación subnacional según su diferencia con el valor nacional, con el efecto de la tabla betas. Por eso los proxies deben cerrar en el valor nacional: su promedio, ponderado por la población del mismo sexo y banda, debe ser el valor nacional (la sección 4 muestra cómo revisarlo y cómo corregirlo). Los proxies pueden traer sus propias bandas de edad, más anchas que las de la población (por ejemplo 25-44, 45-59, 60-74 y 75 y más), siempre que cada una sea una unión de bandas de la población: el cierre se comprueba en cada una, con la población de las bandas que la forman.

Columna	Exige	Qué es
`ubicacion`		Ubicación; sin la columna, la nacional
`anio`		Año; sin la columna, todos
`sexo`		Sexo; sin la columna, ambos
`edad_inicio`		Primera edad; sin las columnas de edad, todas las edades (años)
`edad_fin`		Fin de la banda (excluido) (años)
`covariable`	sí	Nombre de la covariable
`valor`	sí	Valor de la covariable
`error_estandar`		Error estándar del valor
`inferior`		Límite inferior del intervalo del 95 %
`superior`		Límite superior del intervalo del 95 %
`fuente`		De dónde sale el valor (el proxy, en las subnacionales)
`covariable_id`		Id de GBD de la covariable (lo llena el lector del GHDx)

En el ejemplo, covariables trae solo los valores nacionales (las descargas del GHDx) y las filas subnacionales salen de proxies_crudos: proyecto$calibracion las tiene, con la fuente que dice cómo se calibraron.

cov <- proyecto$tablas$covariables
head(cov[cov$covariable == "LDI_pc"], 3)
#>     anio   sexo covariable valor inferior superior covariable_id
#>    <int> <char>     <char> <num>    <num>    <num>         <int>
#> 1:  2019  ambos     LDI_pc  9800   9388.4  10211.6            57
#> 2:  2023  ambos     LDI_pc 11040  10576.3  11503.7            57
cal <- proyecto$calibracion
head(cal[cal$ubicacion == "01" & cal$covariable == "LDI_pc"], 3)
#>    ubicacion  anio   sexo edad_inicio edad_fin covariable    valor
#>       <char> <int> <char>       <num>    <num>     <char>    <num>
#> 1:        01  2023  ambos          NA       NA     LDI_pc 5866.691
#>    error_estandar
#>             <num>
#> 1:       209.2787
#>                                                                                                                        fuente
#>                                                                                                                        <char>
#> 1: indicador sintético de ingreso per cápita (mensual): calibrado (paseo_aleatorio, q = 0.000373, ediciones 2019, 2021, 2023)

`betas`

El efecto de cada covariable: el coeficiente $\beta$ publicado, que es el cambio del logaritmo de la tasa por unidad de la covariable transformada. Una fuente habitual es el apéndice metodológico del modelo de GBD de la causa. Sin causa, la beta vale para todas las causas; un subtipo sin filas propias usa las de su causa padre: la que lo declara en subtipos en el mismo proyecto o, en su propia carpeta, la de subtipo_de (sección 7). La estimación subnacional usa las betas cuya covariable tiene filas subnacionales en covariables.

efecto_sobre: prevalencia o incidencia (las dos mueven el logaritmo de la incidencia) o mortalidad_exceso.
transformacion: la de la regresión publicada, log, logit o lineal.
inferior y superior: el intervalo del 95 % de la beta; sin ellos, la beta es fija.
escala (solo con lineal): multiplica la diferencia antes de la beta, por ejemplo 0.01 si la beta se estimó con la covariable en 0-1 y la descarga viene en 0-100. La guía Estimación subnacional lo explica con un ejemplo.
valor_nacional_de: otra covariable cuyo valor nacional ancla a esta. Por ejemplo, una beta estimada por edad cuyos valores subnacionales se comparan con la versión estandarizada por edad de la misma covariable. La covariable de la beta, que trae sus valores subnacionales, no necesita entonces su fila nacional en covariables: basta la de la covariable nombrada (sin valores subnacionales no hay nada que anclar, y la fila nacional propia se sigue pidiendo). Si los valores subnacionales vienen de proxies_crudos, la calibración cierra en ese mismo valor nacional. La guía Estimación subnacional lo explica.

Columna	Exige	Qué es
`causa`		Causa; sin la columna, todas
`covariable`	sí	Covariable, como en la tabla covariables
`efecto_sobre`	sí	Parámetro sobre el que actúa: `prevalencia`, `incidencia`, `mortalidad_exceso`
`transformacion`	sí	Transformación de la covariable en la regresión publicada: `log`, `logit`, `lineal`
`escala`		Multiplica la diferencia de la covariable (solo con lineal); 1 por defecto
`beta`	sí	Coeficiente publicado
`inferior`		Límite inferior del 95 % (vacío: beta fija)
`superior`		Límite superior del 95 % (vacío: beta fija)
`valor_nacional_de`		Otra covariable cuyo valor nacional ancla a esta (con valores subnacionales de esta, su fila nacional propia no hace falta)
`escala_confirmada`		true confirma una beta lineal grande con escala 1
`fuente`		De dónde sale la beta

proyecto$tablas$betas
#>    causa                covariable      efecto_sobre transformacion escala
#>    <int>                    <char>            <char>         <char>  <num>
#> 1:  9100 SEV_scalar_agestd_cvd_pvd       prevalencia            log     NA
#> 2:  9100                    LDI_pc       prevalencia            log     NA
#> 3:  9100                      haqi mortalidad_exceso         lineal      1
#>      beta inferior superior
#>     <num>    <num>    <num>
#> 1:  0.620    0.550    0.700
#> 2: -0.210   -0.300   -0.120
#> 3: -0.012   -0.018   -0.006
#>                                                          fuente
#>                                                          <char>
#> 1: Tabla sintética de covariables (datos sintéticos de ejemplo)
#> 2: Tabla sintética de covariables (datos sintéticos de ejemplo)
#> 3: Tabla sintética de covariables (datos sintéticos de ejemplo)

`datos`

Los datos locales: estudios, registros y estadísticas vitales, nacionales o subnacionales. Cada fila trae valor y error_estandar, o casos y muestra (personas con la enfermedad entre las examinadas, o casos nuevos o muertes en personas-año). La incidencia y la mortalidad son por persona-año de toda la población, como las publica GBD.

`medida`	Qué es
`prevalencia`	una encuesta o un estudio (también se acepta `prevalencia_estudio`)
`incidencia`	casos nuevos por persona-año
`mortalidad`	muertes por la causa por persona-año
`prevalencia_registro`	un registro administrativo: se lee, pero nunca entra al ajuste

Columna	Exige	Qué es
`causa`		Causa; sin la columna, la del proyecto
`ubicacion`	sí	Ubicación
`anio`		Año (o anio_inicio y anio_fin)
`anio_inicio`		Primer año del dato
`anio_fin`		Último año del dato (no antes de anio_inicio)
`sexo`	sí	hombres, mujeres o ambos
`edad_inicio`	sí	Primera edad (años)
`edad_fin`	sí	Fin de la banda (excluido) (años)
`medida`	sí	Qué mide el dato: `prevalencia`, `incidencia`, `mortalidad`, `prevalencia_registro`
`valor`		Valor (proporción o por persona-año)
`error_estandar`		Error estándar (igual que valor)
`casos`		Casos (con muestra, en vez de valor y error)
`muestra`		Muestra (personas o personas-año)
`muestra_efectiva`		Muestra efectiva
`excluir`		true deja el dato fuera
`motivo`		Por qué se excluye
`fuente`		Fuente del dato
`definicion`		Definición de caso

datos <- proyecto$tablas$datos
table(datos$medida, ifelse(datos$ubicacion == "123", "nacional", "subnacional"))
#>              
#>               nacional subnacional
#>   incidencia         4           0
#>   mortalidad        14         120
#>   prevalencia        7          40
head(datos[datos$medida == "prevalencia", c("ubicacion", "anio", "sexo", "edad_inicio", "edad_fin", "casos",
                                            "muestra", "fuente")], 3)
#>    ubicacion  anio    sexo edad_inicio edad_fin casos muestra
#>       <char> <int>  <char>       <num>    <num> <num>   <num>
#> 1:       123  2023 hombres          60       65    32     800
#> 2:       123  2023 hombres          70       75    49     800
#> 3:       123  2023 hombres          80      125    70     800
#>                              fuente
#>                              <char>
#> 1: Estudio de prevalencia sintético
#> 2: Estudio de prevalencia sintético
#> 3: Estudio de prevalencia sintético

Por defecto los datos locales no entran al ajuste: las filas nacionales se dejan fuera (con un mensaje) y las subnacionales del año subnacional.anio_validacion validan la estimación subnacional. Qué filas entran cuando datos_en_ajuste lista alguna medida, cómo excluir un dato y cómo evitar contar dos veces lo que ya informó el ancla lo explica la guía Datos locales.

`severidad`

La fracción de los casos prevalentes en cada estado de salud (asintomático, leve, moderado…) y su peso de discapacidad; con ella se calculan los AVD. Las proporciones de una causa suman 1. Sin sexo ni edades, vale para todas.

El estado puede ser un estado de salud de GBD, por su nombre o su id: sus pesos de discapacidad salen solos del catálogo de GBD 2023 que trae el paquete. Un estado propio necesita los tres pesos (peso_discapacidad, peso_inferior y peso_superior); en cualquier estado van los tres o ninguno.

Columna	Exige	Qué es
`causa`		Causa; sin la columna, todas
`sexo`		Sexo; sin la columna, ambos
`edad_inicio`		Primera edad; sin las columnas de edad, todas (años)
`edad_fin`		Fin de la banda (excluido) (años)
`estado`	sí	Estado de salud: nombre o id de GBD, o uno propio
`id_estado`		Id del estado
`proporcion`	sí	Proporción de los casos en el estado (proporción)
`inferior`	sí	Límite inferior del 95 % (proporción)
`superior`	sí	Límite superior del 95 % (proporción)
`peso_discapacidad`		Peso de discapacidad (vacío: el de GBD); con sus dos límites o ninguno
`peso_inferior`		Límite inferior del peso
`peso_superior`		Límite superior del peso

sev <- proyecto$tablas$severidad
sev[sev$causa == 9101]
#>    causa                            estado id_estado proporcion inferior
#>    <int>                            <char>     <int>      <num>    <num>
#> 1:  9101                      Asintomático       799       0.50   0.4250
#> 2:  9101     Arteriopatía sintomática leve      9801       0.35   0.2975
#> 3:  9101 Arteriopatía sintomática moderada      9802       0.15   0.1275
#>    superior peso_discapacidad peso_inferior peso_superior
#>       <num>             <num>         <num>         <num>
#> 1:   0.5750              0.00         0.000         0.000
#> 2:   0.4025              0.02         0.012         0.031
#> 3:   0.1725              0.07         0.046         0.102
# dos estados de GBD, sin pesos: los pesos salen del catálogo
dl_tabla("severidad", data.frame(estado = c("asymptomatic", "claudication"), proporcion = c(0.6, 0.4),
                                 inferior = c(0.5, 0.3), superior = c(0.7, 0.5)))
#>          estado proporcion inferior superior
#>          <char>      <num>    <num>    <num>
#> 1: asymptomatic        0.6      0.5      0.7
#> 2: claudication        0.4      0.3      0.5

Los estados de GBD están en system.file("referencia", "catalogo_health_states_gbd2023.csv", package = "dismodlite"), con sus nombres en healthstate_name y sus pesos. Si la severidad sale de una partición de las secuelas de la causa, en vez de esta tabla se declara la carpeta de la partición en la configuración (severidad.particion; ver ?dl_configuracion).

`fuentes_gbd`

Las fuentes (nid) que GBD ya usó para la causa y la ubicación, por componente (no_fatal, causa_de_muerte). Si un dato local que entra al ajuste viene de una de ellas, ya informó el ancla: con el ancla a peso completo (ancla.peso 1) y alguna medida en datos_en_ajuste, los insumos se detienen para evitar el doble conteo. Si ningún dato local entra al ajuste (datos_en_ajuste vacío) no hay nada que contar dos veces: el ancla puede ir a peso completo, un mensaje dice cuántas fuentes locales trae la tabla y la corrida lo declara entre las limitaciones de su manifiesto. Se pone en fuentes_gbd/ la lista de fuentes que exporta el GHDx (https://ghdx.healthdata.org/), tal cual: el lector toma 4 de sus columnas y las filas del país (su location_id de GBD, ver ubicacion_gbd en la sección 6), que quedan con el código nacional de ubicaciones; las fuentes de otras ubicaciones de GBD se descartan, con un aviso. La lista del GHDx repite cada fuente en varias filas (una por año o por título): el lector la deja una vez.

Columna	Exige	Qué es
`causa`		Causa
`ubicacion`		Ubicación
`componente`	sí	Componente de GBD que usó la fuente: `no_fatal`, `causa_de_muerte`
`nid`	sí	Id de la fuente en el GHDx

dl_plantilla("fuentes_gbd")
#>   causa ubicacion componente    nid
#> 1  1234      PAIS   no_fatal 123456

`poblacion_detalle`

La población nacional con más detalle de edad que poblacion, por sexo, del año del ancla. Solo hace falta cuando el ancla tiene bandas más finas que la población (sección 5): lo habitual es el detalle de 80 años y más (80-84, …, 95 y más) y el de menores de 5 (menores de 1 y 1 a 4 años, o los grupos de GBD de esas edades). Puede ser poblacion_detalle.csv o una carpeta poblacion_detalle/ con un CSV por fuente. Fuente típica: la población de GBD o de la ONU.

Columna	Exige	Qué es
`anio`	sí	Año
`sexo`	sí	hombres, mujeres o ambos (ambos solo si se quieren agrupar las filas de ambos sexos del ancla)
`edad_inicio`	sí	Primera edad de la banda (años)
`edad_fin`	sí	Fin de la banda (excluido) (años)
`poblacion`	sí	Población nacional con más detalle de edad (personas)

dl_plantilla("poblacion_detalle")
#>   anio    sexo edad_inicio edad_fin poblacion
#> 1 2023 mujeres          80       85     30500

`proxies_crudos`

El indicador de una encuesta (u otra fuente con ediciones) que representa a una covariable, ya agregado por ubicación subnacional y edición, con su error estándar: por ejemplo, la proporción de hogares con un servicio en cada región y en cada ronda de la encuesta. Sus valores no están en la escala de la covariable ni cierran en su valor nacional: dl_proyecto() los calibra al leer el proyecto. Toma la posición de cada ubicación frente al promedio de su edición, la suaviza en el tiempo con todas las ediciones y la lleva al valor nacional del año que se estima, de modo que el promedio ponderado por la población cierra exactamente. El resultado son las filas subnacionales de covariables (proyecto$calibracion). La guía Estimación subnacional explica el método y ?dl_calibrar_proxies, el detalle. La configuración elige el método, la transformación de cada covariable y las ediciones que no entran (claves proxies.*).

Una sola fuente por covariable. Las filas subnacionales de cada covariable vienen de una de las dos tablas: de covariables (ya calibradas) o de proxies_crudos (se calibran). Si una covariable trae filas subnacionales en las dos, es un error. Cada tabla puede traer covariables distintas.

Una fila sin edades (o sin las columnas de edad, o con la banda de 0 y más) es de todas las edades, las de la población; con edades, cada banda debe ser una unión de bandas de la población.

Columna	Exige	Qué es
`ubicacion`	sí	Ubicación subnacional
`anio`	sí	Año de la edición de la encuesta
`sexo`		Sexo; sin la columna, ambos
`edad_inicio`		Primera edad; sin las columnas de edad (o con las edades vacías), todas las edades de la población (años)
`edad_fin`		Fin de la banda (excluido) (años)
`covariable`	sí	Covariable de GBD que representa (como en betas)
`indicador`		Nombre del indicador crudo; pasa a la fuente de las filas calibradas
`valor`	sí	Estimación de la encuesta
`error_estandar`	sí	Error estándar de la estimación (mayor que 0)
`fuente`		Procedencia

head(proyecto$tablas$proxies_crudos, 3)
#>    ubicacion  anio    sexo edad_inicio edad_fin                covariable
#>       <char> <int>  <char>       <num>    <num>                    <char>
#> 1:        01  2019 hombres          40       45 SEV_scalar_agestd_cvd_pvd
#> 2:        02  2019 hombres          40       45 SEV_scalar_agestd_cvd_pvd
#> 3:        03  2019 hombres          40       45 SEV_scalar_agestd_cvd_pvd
#>                                              indicador  valor error_estandar
#>                                                 <char>  <num>          <num>
#> 1: indicador sintético de riesgo vascular (proporción) 0.2385         0.0063
#> 2: indicador sintético de riesgo vascular (proporción) 0.2313         0.0056
#> 3: indicador sintético de riesgo vascular (proporción) 0.2437         0.0065
#>                                          fuente
#>                                          <char>
#> 1: Encuesta de hogares sintética (edición 2019)
#> 2: Encuesta de hogares sintética (edición 2019)
#> 3: Encuesta de hogares sintética (edición 2019)

`razones`

Para el reparto por razón (subnacional: {modo: razon} en la configuración): la tasa de cada ubicación subnacional dividida por la nacional, ya calculada fuera del paquete (con una encuesta, la población en riesgo, los casos notificados…), y el error estándar de su logaritmo. Una fila por ubicación subnacional y año: en el año que se estima deben estar todas las ubicaciones subnacionales de la población, y solo ellas (la nacional no lleva fila). razon y error_log son números finitos y no negativos, con alguna razón mayor que 0. Una razón 0 deja la ubicación sin casos; con error_log 0 la razón no se sortea. La razón vale para todas las edades y los dos sexos. Con varias causas en el proyecto, la columna causa dice de cuál es cada fila. La tabla solo se usa en ese modo, que no admite valores subnacionales de covariables; la guía Estimación subnacional explica el cálculo y ?dl_repartir_razon, el detalle.

Columna	Exige	Qué es
`causa`		Causa; sin la columna, todas
`ubicacion`	sí	Ubicación subnacional
`anio`	sí	Año que se estima
`razon`	sí	Razón entre la tasa de la ubicación y la nacional (0: la ubicación queda sin casos)
`error_log`	sí	Error estándar del logaritmo de la razón (0: la razón no se sortea)
`fuente`		De dónde sale la razón

dl_plantilla("razones")
#>   causa ubicacion anio razon error_log               fuente
#> 1  1234       R01 2023  1.15      0.08 indicador de ejemplo

`prior_mortalidad_exceso`

Para dar al modelo el prior de la mortalidad en exceso (mortalidad_exceso: {prior: tabla} en la configuración) cuando se conoce por otra vía: un estudio de seguimiento, otra corrida de la misma causa o los años vecinos de un año sin muertes fiables. Una fila por sexo y tramo de edad [edad_inicio, edad_fin), con el centro (mu_log) y la desviación estándar (sd_log, mayor que 0) del logaritmo de la mortalidad en exceso, por persona-año. Cada nudo de la configuración toma el prior del tramo que lo contiene: todos los nudos deben caer en un tramo (el prior no se extrapola a otras edades) y los tramos de un sexo no se solapan; lo más simple es un tramo por nudo, del nudo al siguiente, y también vale un solo tramo para todas las edades. sexo: ambos, o la tabla sin la columna sexo, vale para los dos sexos. Sin la columna anio la tabla vale para todos los años; con ella, se usan las filas del año que se estima.

El logaritmo de la mortalidad en exceso de cada nudo sigue una Normal con ese centro y esa desviación, truncada bajo el techo (mortalidad_exceso.techo; sin la clave, el que sale del ancla): el mismo rango del prior que sale del ancla. mu_log es el centro de la Normal antes de truncarla y no puede superar el techo: la mortalidad en exceso quedaría junto al techo y no en el centro pedido. Si el centro de algún nudo lo supera, dl_insumos() se detiene y la revisión del proyecto lo marca, con los nudos y el techo; lo habitual es un error de unidades, o un techo que no corresponde (el que sale de un ancla sin muertes fiables): entonces se declara mortalidad_exceso.techo. Una sd_log muy pequeña deja la mortalidad en exceso fija en el centro. La tabla solo se usa con ese prior; con él, mortalidad_exceso.fraccion_aguda no cambia el prior (mueve el techo que sale del ancla y la corrida sigue declarando la fase aguda) y sensibilidad.fraccion_aguda no se admite.

Columna	Exige	Qué es
`causa`		Causa; sin la columna, todas
`anio`		Año que se estima; sin la columna, todos
`sexo`		hombres, mujeres o ambos (ambos, o sin la columna: el mismo prior en los dos sexos)
`edad_inicio`	sí	Primera edad del tramo (años)
`edad_fin`	sí	Fin del tramo (excluido) (años)
`mu_log`	sí	Centro del prior de log f en los nudos del tramo: el de la Normal antes de truncarla bajo el techo, que no puede superar (logaritmo de la tasa por persona-año)
`sd_log`	sí	Desviación estándar de esa Normal, mayor que 0 (una muy pequeña deja la mortalidad en exceso fija en el centro)
`fuente`		De dónde sale el prior

dl_plantilla("prior_mortalidad_exceso")
#>   causa anio    sexo edad_inicio edad_fin mu_log sd_log             fuente
#> 1  1234 2023 mujeres          40       50   -3.2    0.4 estudio de ejemplo

Un ejemplo con la causa 9100: el prior que el paquete saca del ancla (dl_prior_emr()), pasado como tabla, como si viniera de otra corrida. Ese prior empieza en la primera banda del ancla (40 años) y el primer nudo de la causa es 30: el primer tramo se extiende hasta él, porque cada nudo necesita su tramo.

desde_ancla <- dl_prior_emr(dl_insumos(dl_proyecto(dl_ejemplo(), causa = 9100)))
#> 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
tabla <- data.frame(sexo = ifelse(desde_ancla$sex_id == 1, "hombres", "mujeres"),
                    edad_inicio = desde_ancla$age_start, edad_fin = desde_ancla$age_end,
                    mu_log = desde_ancla$mu_log, sd_log = desde_ancla$sd_log, fuente = "otra corrida")
tabla$edad_inicio[tabla$edad_inicio == 40] <- 30
config <- yaml::read_yaml(file.path(dl_ejemplo(), "config", "9100.yaml"))
config$mortalidad_exceso$prior <- "tabla"
p <- dl_proyecto(dl_ejemplo(), causa = 9100, configuracion = config, prior_mortalidad_exceso = tabla)
head(dl_prior_emr(dl_insumos(p)), 3)
#> 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
#>    sex_id age_start age_end    mu_log   sd_log
#>     <int>     <num>   <num>     <num>    <num>
#> 1:      1        30      45 -4.253818 0.212132
#> 2:      1        45      50 -4.073958 0.212132
#> 3:      1        50      55 -3.946815 0.212132

dl_plantilla() da la plantilla de cualquier tabla: sus columnas y una fila de ejemplo. Con archivo, la escribe como CSV.

3. La carpeta y la puerta de R

Las tablas llegan al paquete por dos puertas, en una sola función, dl_proyecto(): la carpeta del proyecto o argumentos de R. Las dos se pueden mezclar y pasan por el mismo validador.

La carpeta

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

Los nombres son fijos y las rutas no se declaran (salvo la de la partición de severidad, relativa a la carpeta). Cada tabla es <tabla>.csv o una carpeta <tabla>/ cuyos CSV se juntan: cada archivo se reconoce por sus columnas (una descarga de GBD, una del GHDx o una tabla del contrato) y pasa por su lector. Una tabla opcional que no está, o que solo trae el encabezado, no existe. Los demás archivos (notas, resultados) no se leen. La sección 7 muestra la carpeta de un proyecto de modelación completo.

dl_nuevo_proyecto() crea la carpeta con la configuración comentada, las plantillas de las tablas (solo el encabezado), las carpetas de las descargas y un LEEME.md con los pasos. No sobrescribe nada. Para esta guía, la causa 9101 del ejemplo, en una carpeta temporal:

carpeta <- file.path(tempdir(), "mi_proyecto")
dl_nuevo_proyecto(carpeta, causa = 9101, nombre = "ACS de miembros inferiores", anio = 2023, edad_inicio = 30)
#> dl_nuevo_proyecto(): proyecto de la causa 9101 en /tmp/RtmpRk3xeq/mi_proyecto
#>   archivos nuevos: LEEME.md, betas.csv, config.yaml, datos.csv, poblacion.csv, poblacion_detalle.csv, prior_mortalidad_exceso.csv, proxies_crudos.csv, razones.csv, severidad.csv, ubicaciones.csv
#>   ya existían (no se tocaron): ninguno
#>   siguientes pasos: lee LEEME.md, completa config.yaml, llena las tablas, pon las descargas en ancla/ (y en covariables/) y revisa el proyecto con dl_revisar_proyecto()
list.files(carpeta, recursive = TRUE, include.dirs = TRUE)
#>  [1] "ancla"                       "betas.csv"                  
#>  [3] "config.yaml"                 "covariables"                
#>  [5] "datos.csv"                   "fuentes_gbd"                
#>  [7] "LEEME.md"                    "poblacion_detalle.csv"      
#>  [9] "poblacion.csv"               "prior_mortalidad_exceso.csv"
#> [11] "proxies_crudos.csv"          "razones.csv"                
#> [13] "severidad.csv"               "ubicaciones.csv"

Se llenan las tres tablas obligatorias y la severidad (aquí, copiando las del ejemplo; la descarga del ancla trae las cuatro causas del ejemplo y cada causa usa sus filas):

invisible(file.copy(c(dl_ejemplo("ubicaciones.csv"), dl_ejemplo("poblacion.csv")), carpeta, overwrite = TRUE))
invisible(file.copy(dl_ejemplo("ancla", "sintetico_acs_v1.csv"), file.path(carpeta, "ancla")))
severidad <- read.csv(dl_ejemplo("severidad.csv"), encoding = "UTF-8")
write.csv(severidad[severidad$causa == 9101, ], file.path(carpeta, "severidad.csv"), row.names = FALSE,
          fileEncoding = "UTF-8")
dl_proyecto(carpeta)
#> <dl_proyecto> ACS de miembros inferiores, causa 9101 | año 2023 | tablas del contrato
#>   carpeta: /tmp/RtmpRk3xeq/mi_proyecto
#>   tablas:
#>     ubicaciones             26 fila(s), de ubicaciones.csv
#>     poblacion               2100 fila(s), de poblacion.csv
#>     ancla                   768 fila(s), de ancla
#>     covariables             no
#>     betas                   no
#>     datos                   no
#>     severidad               3 fila(s), de severidad.csv
#>     fuentes_gbd             no
#>     poblacion_detalle       no
#>     proxies_crudos          no
#>     razones                 no
#>     prior_mortalidad_exceso no
#>   subnacional: plano
#>   tomado por defecto (17):
#>     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
#>     mortalidad_exceso.techo = 3 veces la EMR máxima del ancla
#>     remision = 0
#>     datos_en_ajuste = ninguno: las nacionales no se usan; las subnacionales de mortalidad validan
#>     subnacional.modo = plano
#>     subnacional.kappa (κ) = 1
#>     subnacional.anio_validacion = 2023
#>     sensibilidad.peso (λ) = [0.25, 0.5, 1]
#>     sensibilidad.correlacion_edad (ρ) = [0, 0.5, 0.9]
#>     sensibilidad.kappa (κ) = [0.5, 1]

print() del proyecto dice qué tablas encontró y de dónde, y qué claves de la configuración tomaron su valor por defecto.

La configuración

La configuración guarda decisiones; las tablas guardan números con su fuente. config.yaml trae cada clave con su explicación, su símbolo en el modelo y su valor por defecto. Las obligatorias (causa, anio y edad_inicio) van sin comentar; las demás van comentadas (con #) y toman su valor por defecto. Para cambiar una, se quita el # de su línea y el de su bloque, respetando la sangría de dos espacios:

cat(readLines(file.path(carpeta, "config.yaml"), n = 22, encoding = "UTF-8"), sep = "\n")
# Configuración de una causa de un proyecto de dismodlite (la escribió dl_nuevo_proyecto()).
# Cada clave va con qué es, su símbolo en el modelo y su valor por defecto:
# - las obligatorias van sin «#»: completa las que están vacías;
# - las demás están comentadas con su valor por defecto o, si no tienen un valor fijo, con un
#   ejemplo. Para usar otro valor, quita el «# » de su línea (y el de su
#   bloque, como `ancla:` para ancla.peso), deja la sangría de dos espacios y escribe el valor.
# Referencia de las claves: ?dl_configuracion. Para revisar el proyecto: dl_revisar_proyecto().

# `causa`: Identificador de la causa: un entero (el cause_id de GBD si la causa existe en GBD). Obligatoria;
#     por ejemplo 1234.
causa: 9101

# `nombre`: 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. Por defecto, el
#     cause_name de la descarga del ancla.
nombre: ACS de miembros inferiores

# `anio`: Año que se estima. Obligatoria; por ejemplo 2023.
anio: 2023

# `sexos`: Sexos que se estiman: hombres y mujeres (o sus códigos 1 y 2); una causa de un solo sexo lleva
#     solo ese. Por defecto, [hombres, mujeres].

Cada clave, en el orden del archivo, con su símbolo en el modelo entre paréntesis (la tabla sale de la misma definición que usa el paquete; ?dl_configuracion agrega el tipo de cada clave):

Clave	Qué es	Por defecto
`causa`	Identificador de la causa: un entero (el cause_id de GBD si la causa existe en GBD).	obligatoria
`nombre`	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.	el cause_name de la descarga del ancla
`anio`	Año que se estima.	obligatoria
`sexos`	Sexos que se estiman: hombres y mujeres (o sus códigos 1 y 2); una causa de un solo sexo lleva solo ese.	`[hombres, mujeres]`
`edad_inicio`	Primera edad del modelo, en años; ahí la prevalencia es 0. Una causa con `suma_de_subtipos: sí` no la necesita.	obligatoria
`ubicacion_gbd`	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.	el código nacional de ubicaciones.csv, si es un location_id de las descargas; o la única ubicación
`ancla.peso` (λ)	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.	`1`
`ancla.correlacion_edad` (ρ)	Correlación entre las bandas de edad vecinas del ancla, en [0, 1).	`0.5`
`ancla.anio`	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.	el valor de `anio`
`ancla.error_maximo`	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.	0.05
`nudos`	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.	cada 10 años desde edad_inicio hasta 80, y 95
`incidencia.suavidad` (σ)	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.	`0.5`
`mortalidad_exceso.prior`	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).	`desde_ancla`
`mortalidad_exceso.techo`	Techo de la EMR, un número > 0, por persona-año.	3 veces la EMR máxima del ancla
`mortalidad_exceso.fraccion_aguda`	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.	ninguno
`remision`	Remisión, un número >= 0, por persona-año (0 es una causa crónica).	`0`
`datos_en_ajuste`	Tipos de la tabla datos cuyas filas nacionales entran al ajuste: prevalencia (de estudios; también se admite prevalencia_estudio), incidencia, mortalidad.	ninguno: las nacionales no se usan; las subnacionales de mortalidad validan
`severidad.particion`	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//.	ninguno
`severidad.padre`	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.	ninguno
`componente.secuelas`	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.	ninguno
`subnacional.modo`	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).	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
`subnacional.kappa` (κ)	Fuerza del efecto subnacional de las covariables, en (0, 1].	`1`
`subnacional.anio_validacion`	Año de los datos subnacionales de datos.csv reservados para validar.	el valor de `anio`
`proxies.metodo`	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.	`paseo_aleatorio`
`proxies.transformacion`	Por covariable: cociente (tasas y proporciones; por defecto) o diferencia (índices). Cada clave es una covariable de proxies_crudos.	ninguno
`proxies.excluir`	Ediciones de proxies_crudos que no entran, cada una con anio y motivo.	ninguno
`sensibilidad.peso` (λ)	Valores de ancla.peso del análisis de sensibilidad.	`[0.25, 0.5, 1]`
`sensibilidad.correlacion_edad` (ρ)	Valores de ancla.correlacion_edad del análisis de sensibilidad.	`[0, 0.5, 0.9]`
`sensibilidad.kappa` (κ)	Valores de subnacional.kappa del análisis de sensibilidad.	`[0.5, 1]`
`sensibilidad.fraccion_aguda`	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.	ninguno
`subtipos`	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/.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).	ninguno
`suma_de_subtipos`	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.	no
`subtipos_omitidos[].causa`	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.	obligatoria
`subtipos_omitidos[].motivo`	Por qué el subtipo no entra en la suma; queda entre las limitaciones de la corrida.	obligatoria
`subtipo_de`	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).	ninguno
`exportar.incidencia`	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`.	`sí`
`notas`	Decisiones que quedan registradas en cada corrida.	ninguno
`avanzado`	Claves del formato completo, tal cual: se aplican al final, sobre la traducción (para expertos).	ninguno

Cuándo cambiar las que no son obligatorias, en breve: nudos, si la incidencia cambia rápido en algún tramo de edad; mortalidad_exceso.prior: plano, si el ancla no trae muertes fiables, y mortalidad_exceso.techo, con un valor conocido para la causa; mortalidad_exceso.prior: cero, si la causa no tiene muertes (la mortalidad en exceso queda fija en 0 y no se estima); mortalidad_exceso.prior: tabla, si la mortalidad en exceso se conoce por otra vía (la tabla prior_mortalidad_exceso); ancla.correlacion_edad, rara vez (la sensibilidad la explora); subnacional.kappa, para atenuar diferencias entre ubicaciones poco creíbles; subnacional.modo: razon, si las diferencias entre ubicaciones salen de una razón ya calculada (la tabla razones) y no de covariables; exportar: {incidencia: no}, si la incidencia de la causa no se debe reportar (la corrida la escribe igual y las tablas consolidadas la omiten; ver Corridas, versiones y tablas consolidadas). Y notas, siempre que se decida algo: por qué ancla.peso es 0.5, por qué ese techo.

La puerta de R

Las mismas tablas se pueden pasar como argumentos de dl_proyecto(), con su nombre: un data.frame (o un tibble) o la ruta de un CSV o de una carpeta. La configuración va en configuracion, como lista o como la ruta de un YAML. Sin carpeta, el proyecto entero sale de R:

ubicaciones <- read.csv(dl_ejemplo("ubicaciones.csv"), colClasses = "character", encoding = "UTF-8")
poblacion <- read.csv(dl_ejemplo("poblacion.csv"), colClasses = c(ubicacion = "character"))
p <- dl_proyecto(configuracion = list(causa = 9101, nombre = "ACS de miembros inferiores", anio = 2023,
                                      edad_inicio = 30),
                 ubicaciones = ubicaciones, poblacion = poblacion, ancla = dl_ejemplo("ancla"),
                 severidad = severidad[severidad$causa == 9101, ])
p
#> <dl_proyecto> ACS de miembros inferiores, causa 9101 | año 2023 | tablas del contrato
#>   carpeta: (ninguna: las tablas vienen como argumentos)
#>   tablas:
#>     ubicaciones             26 fila(s), de argumento `ubicaciones` (data.frame)
#>     poblacion               2100 fila(s), de argumento `poblacion` (data.frame)
#>     ancla                   768 fila(s), de ancla
#>     covariables             no
#>     betas                   no
#>     datos                   no
#>     severidad               3 fila(s), de argumento `severidad` (data.frame)
#>     fuentes_gbd             no
#>     poblacion_detalle       no
#>     proxies_crudos          no
#>     razones                 no
#>     prior_mortalidad_exceso no
#>   subnacional: plano
#>   tomado por defecto (17):
#>     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
#>     mortalidad_exceso.techo = 3 veces la EMR máxima del ancla
#>     remision = 0
#>     datos_en_ajuste = ninguno: las nacionales no se usan; las subnacionales de mortalidad validan
#>     subnacional.modo = plano
#>     subnacional.kappa (κ) = 1
#>     subnacional.anio_validacion = 2023
#>     sensibilidad.peso (λ) = [0.25, 0.5, 1]
#>     sensibilidad.correlacion_edad (ρ) = [0, 0.5, 0.9]
#>     sensibilidad.kappa (κ) = [0.5, 1]

Con una carpeta, lo que se pasa como argumento reemplaza a la tabla de la carpeta; lo demás se lee de ella. Por ejemplo, la misma carpeta con otra población:

p <- dl_proyecto(carpeta, poblacion = mi_poblacion)

El proyecto se revisa y se corre igual que una carpeta (dl_revisar_proyecto(p), dl_correr(p, semilla = 1)), y la corrida guarda las tablas y la configuración que usó (en inputs/contrato/, que es la carpeta de un proyecto), así que se puede repetir sin los data.frame originales (sección 7). Sin carpeta, las rutas relativas de la configuración (como severidad.particion) se resuelven contra el directorio de trabajo.

4. Revisar: `dl_tabla()` y `dl_revisar_proyecto()`

dl_tabla() lee, convierte y valida una tabla, sin armar el proyecto: sirve para preparar las tablas en R y comprobar cada una antes de seguir. Devuelve la tabla en el contrato (con el sexo en palabras y la banda abierta con edad_fin 125) o un error que dice la tabla, su origen, la columna, las filas y qué se esperaba. Las filas se cuentan como las líneas del CSV (el encabezado es la línea 1, así que la primera fila de datos es la 2) o, en un data.frame, por su número de fila («fila(s) 2 del data.frame»):

pob <- data.frame(ubicacion = "01", anio = 2023, sexo = c("hombres", "masculino"), edad_inicio = 30,
                  edad_fin = 35, poblacion = c(1200, 1300))
dl_tabla("poblacion", pob)
#> Error:
#> ! dl_tabla(): la tabla poblacion tiene 1 problema(s):
#>   - sexo: masculino no es hombres, mujeres ni ambos (fila(s) 2 del data.frame)
#>   origen: argumento `x` (data.frame)

dl_revisar_proyecto() revisa el proyecto entero sin detenerse en el primer problema: cada tabla sola, la configuración, las reglas que cruzan tablas (ubicaciones conocidas, población que cubre el año, los sexos y las edades, el ancla con la prevalencia de la causa, cada beta con su covariable, la severidad que suma 1…) y, al final, los insumos completos. Muestra una línea por comprobación, con ✓ si está en orden, ! si es un aviso y ✗ si es un error, con la corrección sugerida. dl_proyecto() comprueba las mismas reglas entre tablas, pero se detiene: con el primer problema de una tabla sola o, si todas están bien, con todos los problemas entre tablas juntos. La revisión acepta una carpeta o un proyecto ya leído:

dl_revisar_proyecto(carpeta)
#> Revisión del proyecto «mi_proyecto», causa 9101
#>   ✓ ubicaciones: leída: 26 fila(s)
#>   ✓ poblacion: leída: 2100 fila(s)
#>   ✓ ancla: leída: 768 fila(s) (descarga de GBD Results)
#>   ✓ severidad: leída: 3 fila(s)
#>   ✓ configuración: config.yaml: proyecto
#>   ✓ proyecto: las reglas entre tablas se cumplen
#>   ✓ insumos: dl_insumos() los arma y los valida (hash f2dc0815f5b6)
#> Todo en orden.

El cierre de las covariables

Los proxies de proxies_crudos cierran por construcción. Los que llegan ya calibrados a covariables se leen tal cual, y un error frecuente es que no cierren en el valor nacional. Se agrega al proyecto una covariable, con su beta, su descarga del GHDx y unos valores subnacionales de otra fuente (aquí, los calibrados del ejemplo en otra base de precios):

betas <- read.csv(dl_ejemplo("betas.csv"), encoding = "UTF-8")
betas <- betas[betas$covariable == "LDI_pc", names(betas) != "causa"]   # sin causa: vale para todas
write.csv(betas, file.path(carpeta, "betas.csv"), row.names = FALSE, na = "", fileEncoding = "UTF-8")
invisible(file.copy(dl_ejemplo("covariables", "LDI_PC.csv"), file.path(carpeta, "covariables")))
proxies <- as.data.frame(proyecto$calibracion)
proxies <- proxies[proxies$covariable == "LDI_pc", ]
proxies$valor <- proxies$valor * 0.9                     # valores de otra fuente
proxies$error_estandar <- proxies$error_estandar * 0.9
write.csv(proxies, file.path(carpeta, "covariables", "proxies.csv"), row.names = FALSE, na = "",
          fileEncoding = "UTF-8")
dl_revisar_proyecto(carpeta)
#> Revisión del proyecto «mi_proyecto», causa 9101
#>   ✓ ubicaciones: leída: 26 fila(s)
#>   ✓ poblacion: leída: 2100 fila(s)
#>   ✓ ancla: leída: 768 fila(s) (descarga de GBD Results)
#>   ✓ covariables: leída: 27 fila(s) (descarga de covariables del GHDx)
#>   ✓ betas: leída: 1 fila(s)
#>   ✓ severidad: leída: 3 fila(s)
#>   ✓ configuración: config.yaml: proyecto
#>   ✓ proyecto: las reglas entre tablas se cumplen
#>   ✗ covariables: el promedio ponderado por población es 9936 y el valor nacional de la covariable es 11040: difieren en -1104 y la tolerancia es 1e-08 (covariable LDI_pc, ambos sexos, todas las edades). El promedio de las ubicaciones, ponderado por su población del mismo sexo y grupo de edad, debe ser el valor nacional de la covariable; desplaza o escala sus valores para que cierren (ver ?dl_proyecto)
#>       → columnas ubicacion, anio, covariable, valor, error_estandar, fuente (ver ?dl_tablas)
#> 1 error(es) y 0 aviso(s): corrige los errores y vuelve a revisar.

La revisión da el promedio, el valor nacional y la diferencia. Para cerrar, se llevan los valores al valor nacional $X$ con los pesos $w$ de población: por escala, v * X / (sum(w * v) / sum(w)) (el error estándar se escala igual), o por desplazamiento, v + X - sum(w * v) / sum(w) (el error estándar no cambia). La escala conserva las razones entre ubicaciones (lo que compara una covariable con transformación log) y sirve para valores positivos, como el ingreso; el desplazamiento conserva las diferencias (lo que compara una lineal). Aquí, por escala, con la población de ambos sexos y todas las edades del año que se estima:

pob_2023 <- poblacion[poblacion$anio == 2023, ]
w <- tapply(pob_2023$poblacion, pob_2023$ubicacion, sum)[proxies$ubicacion]
nacional <- dl_tabla("covariables", dl_ejemplo("covariables", "LDI_PC.csv"), ubicacion_gbd = 123)
X <- nacional$valor[nacional$anio == 2023]
promedio <- sum(w * proxies$valor) / sum(w)
c(nacional = X, promedio = promedio)
#> nacional promedio 
#>    11040     9936
proxies$valor <- proxies$valor * X / promedio
proxies$error_estandar <- proxies$error_estandar * X / promedio
write.csv(proxies, file.path(carpeta, "covariables", "proxies.csv"), row.names = FALSE, na = "",
          fileEncoding = "UTF-8")
dl_revisar_proyecto(carpeta)
#> Revisión del proyecto «mi_proyecto», causa 9101
#>   ✓ ubicaciones: leída: 26 fila(s)
#>   ✓ poblacion: leída: 2100 fila(s)
#>   ✓ ancla: leída: 768 fila(s) (descarga de GBD Results)
#>   ✓ covariables: leída: 27 fila(s) (descarga de covariables del GHDx)
#>   ✓ betas: leída: 1 fila(s)
#>   ✓ severidad: leída: 3 fila(s)
#>   ✓ configuración: config.yaml: proyecto
#>   ✓ proyecto: las reglas entre tablas se cumplen
#>   ✓ insumos: dl_insumos() los arma y los valida (hash 47cedd19352c)
#> Todo en orden.

Con una covariable por sexo o por banda de edad, el cierre se cumple en cada sexo y banda: w, X y promedio se calculan por separado en cada uno. El paquete no recalibra los valores de covariables al leerlos: la elección entre escala y desplazamiento es del modelador, y conviene dejarla en notas. Si los valores vienen de una encuesta, proxies_crudos hace este trabajo (con la transformacion cociente, la escala; con diferencia, el desplazamiento) y lo registra en la corrida. La comprobación es prácticamente exacta (el promedio y el valor nacional pueden diferir en menos de 1e-8): escribe los valores recalibrados sin redondear (write.csv() guarda 15 cifras significativas, como aquí) y no los redondees en Excel.

Tasas por 100 000

Otro error frecuente es escribir la mortalidad por 100 000 y no por persona-año. La revisión lo avisa:

dato <- data.frame(causa = 9101, ubicacion = "123", anio = 2023, sexo = "hombres", edad_inicio = 60,
                   edad_fin = 65, medida = "mortalidad", valor = 45, error_estandar = 5,
                   fuente = "registro vital")
write.csv(dato, file.path(carpeta, "datos.csv"), row.names = FALSE)
dl_revisar_proyecto(carpeta)
#> Revisión del proyecto «mi_proyecto», causa 9101
#>   ✓ ubicaciones: leída: 26 fila(s)
#>   ✓ poblacion: leída: 2100 fila(s)
#>   ✓ ancla: leída: 768 fila(s) (descarga de GBD Results)
#>   ✓ covariables: leída: 27 fila(s) (descarga de covariables del GHDx)
#>   ✓ betas: leída: 1 fila(s)
#>   ✓ datos: leída: 1 fila(s)
#>   ✓ severidad: leída: 3 fila(s)
#>   ✓ configuración: config.yaml: proyecto
#>   ! proyecto: datos: 1 valor(es) de mortalidad parecen tasas por 100 000, no por persona-año (fila(s) 2; por ejemplo 45, donde el ancla da 0.000619): divide valor y error_estandar por 100 000
#>       → columnas causa, ubicacion, anio, sexo, edad_inicio, edad_fin, medida, valor, error_estandar, fuente (ver ?dl_tablas)
#>   ✓ proyecto: las reglas entre tablas se cumplen
#>   ✓ insumos: dl_insumos() los arma y los valida (hash 47cedd19352c)
#> 0 error(es) y 1 aviso(s).

5. Las bandas de edad del ancla y de la población

Las bandas de la población son las bandas del modelo. Las del ancla se comparan con ellas:

Cada banda del ancla es una o varias bandas de la población: se usa tal cual. Cada banda del ancla es un término del ajuste y una celda de los resultados. Es el caso del ejemplo: la población trae 80-84, 85-89, 90-94 y 95 y más, como el ancla.
Una banda del ancla es más fina que la población (el ancla trae 80-84, …, 95 y más y la población, solo 80 y más): las bandas del ancla que caben en una banda de la población se agrupan en ella, con un promedio ponderado por su población en poblacion_detalle, del año del ancla. Sin esa tabla, es un error que lo dice.
Las bandas de menos de un año de GBD se agrupan en $[0, 1)$ , ponderadas por su ancho. Si la población trae a los menores de 5 en una sola banda (0-4), las del ancla que caben en ella ( $[0, 1)$ y las de 1 a 4 años) se agrupan como las de 80 y más, con poblacion_detalle. Si no hay población de menores de 5 con detalle, una aproximación es repartir la de 0-4 por el ancho de cada banda (población uniforme); conviene dejarla en notas.
Las filas de ambos sexos del ancla (las descargas de GBD Results suelen traerlas) no entran al modelo, que ajusta cada sexo por separado: poblacion_detalle no tiene que traer ambos. Si no lo trae, esas filas se dejan fuera al agrupar; si lo trae, se agrupan como las demás.

Por ejemplo, una población subnacional que solo tiene 80 años y más:

gruesa <- poblacion
mayores <- gruesa$edad_inicio >= 80
gruesa$edad_inicio[mayores] <- 80
gruesa$edad_fin[mayores] <- 125
gruesa <- aggregate(poblacion ~ ubicacion + anio + sexo + edad_inicio + edad_fin, gruesa, sum)
config <- list(causa = 9101, anio = 2023, edad_inicio = 30)
dl_proyecto(configuracion = config, ubicaciones = ubicaciones, poblacion = gruesa, ancla = dl_ejemplo("ancla"))
#> Error:
#> ! dl_proyecto(): el proyecto tiene 1 problema(s) entre tablas:
#>   - ancla: la población trae 80 años y más y el ancla 80-84 años, 85-89 años, 90-94 años, 95 años y más: agrega poblacion_detalle (población nacional por sexo y edad con ese detalle, por ejemplo de GBD o de la ONU), o una población con ese detalle en todas las ubicaciones
#>   (dl_revisar_proyecto() revisa todo el proyecto sin detenerse)

poblacion_detalle da la población nacional por sexo con el detalle del ancla; aquí, la suma de la población del ejemplo:

detalle <- aggregate(poblacion ~ anio + sexo + edad_inicio + edad_fin, poblacion[mayores, ], sum)
head(detalle, 4)
#>   anio    sexo edad_inicio edad_fin poblacion
#> 1 2019 hombres          80       85    187690
#> 2 2023 hombres          80       85    197568
#> 3 2024 hombres          80       85    199542
#> 4 2019 mujeres          80       85    245019
p <- dl_proyecto(configuracion = config, ubicaciones = ubicaciones, poblacion = gruesa,
                 ancla = dl_ejemplo("ancla"), poblacion_detalle = detalle)

Con eso, el ancla de 80 años y más es una sola banda, con el peso de cada banda fina en su población. Si la población tiene el detalle, conviene usarlo: cada banda del ancla informa al ajuste por separado.

La versión 1.0.0 agrupaba siempre el ancla de 80 años y más (y la de menos de 5 años) en una sola banda, aunque la población trajera el detalle. Para reproducir una corrida de esa versión, la configuración lo declara en avanzado:

avanzado:
  anchor:
    agrupar_bandas_finas: true

6. Las descargas de GBD

El ancla: GBD Results

Se baja de la herramienta GBD Results del IHME (https://vizhub.healthdata.org/gbd-results/), en CSV, con las columnas «ID y nombre», y se pone en ancla/ sin editar. Qué pedir:

Medidas: prevalencia (obligatoria), muertes (para el prior de la mortalidad en exceso por defecto y, sin mortalidad_exceso.techo, para su techo), AVD (calibran los AVD del modelo a los de GBD) e incidencia (la usa la validación).
Métrica: Rate (por 100 000), en todas las medidas, también la prevalencia. El lector divide entre 100 000 y deja las filas de otras métricas. El Percent de la prevalencia no es la proporción de la población: GBD lo calcula sobre las personas con alguna causa, así que la supera (menos de 1 % en adultos, hasta 37 % antes de los 2 años). Si una descarga solo trae Percent, el mensaje lo dice.
Ubicación: el país (puede traer otras; ver ubicacion_gbd abajo).
Edades: los grupos de GBD desde edad_inicio, con el mismo detalle que la población (por ejemplo, 80-84, 85-89, 90-94 y 95 y más; sección 5). Los grupos de todas las edades o estandarizados se descartan.
Sexos: hombres y mujeres. Años: el que se estima (y el anterior, para proyectar).

Una descarga puede traer varias causas y años: cada causa usa sus filas. El lector convierte cada columna al eje (year a anio, sex_id a sexo, el grupo de edad a edad_inicio y edad_fin, measure_id a medida, val, lower y upper a valor, inferior y superior). La descarga del ejemplo, antes y después:

crudo <- read.csv(dl_ejemplo("ancla", "sintetico_acs_v1.csv"), encoding = "UTF-8")
head(crudo[, c("measure_name", "location_id", "sex_id", "age_name", "cause_id", "metric_name", "year", "val")], 3)
#>   measure_name location_id sex_id    age_name cause_id metric_name year
#> 1   Prevalence         123      1 40-44 years     9100     Percent 2019
#> 2   Prevalence         123      2 40-44 years     9100     Percent 2019
#> 3   Prevalence         123      1 45-49 years     9100     Percent 2019
#>          val
#> 1 0.01151006
#> 2 0.01004687
#> 3 0.01683509
table(crudo$measure_name, crudo$metric_name)
#>                                     
#>                                      Percent Rate
#>   Deaths                                   0  192
#>   Incidence                                0  192
#>   Prevalence                             192  192
#>   YLDs (Years Lived with Disability)       0  192
convertido <- dl_tabla("ancla", dl_ejemplo("ancla", "sintetico_acs_v1.csv"))
head(convertido[convertido$medida == "prevalencia" & convertido$anio == 2023], 3)
#>    causa  anio    sexo edad_inicio edad_fin      medida       valor    inferior
#>    <int> <int>  <char>       <num>    <num>      <char>       <num>       <num>
#> 1:  9100  2023 hombres          40       45 prevalencia 0.012028297 0.008964407
#> 2:  9100  2023 mujeres          40       45 prevalencia 0.009709473 0.007236242
#> 3:  9100  2023 hombres          45       50 prevalencia 0.018018046 0.013428426
#>      superior                   nombre_causa
#>         <num>                         <char>
#> 1: 0.01613938 Arteriopatía crónica sintética
#> 2: 0.01302801 Arteriopatía crónica sintética
#> 3: 0.02417632 Arteriopatía crónica sintética

Las covariables: el GHDx

Los valores nacionales de las covariables de GBD se bajan del GHDx (https://ghdx.healthdata.org/record/ihme-data/gbd-2023-covariates-1980-2023), uno por covariable, y se ponen en covariables/ sin editar, junto a la tabla de los proxies subnacionales ya calibrados (si no vienen de proxies_crudos). El lector toma las filas del país; del valor por edad, prefiere el estandarizado por edad al de todas las edades.

`ubicacion_gbd`: qué ubicación es el país

Las descargas de GBD identifican la ubicación con el location_id de GBD; el proyecto, con sus propios códigos. La clave ubicacion_gbd de la configuración dice qué location_id es el país. Casi nunca hace falta escribirla. Por defecto es:

el código nacional de ubicaciones (la ubicación sin padre), si es un location_id de la descarga (en el ejemplo, 123); o
la única ubicación de la descarga, si trae una sola.

Si no se cumple ninguna, el error la pide; si se declara, la descarga debe traerla. La misma regla vale para las descargas de GBD Results, las covariables y la lista de fuentes del GHDx, y print() del proyecto muestra la que se tomó. Las descargas de covariables del ejemplo traen el país, su región y el mundo; leídas solas, sin el proyecto, dl_tabla() pide la ubicación:

dl_tabla("covariables", dl_ejemplo("covariables", "HAQI.csv"))
#> Error:
#> ! dl_tabla(): «HAQI.csv» trae varias ubicaciones (1, 120, 123): declara ubicacion_gbd, el location_id de GBD del país
dl_tabla("covariables", dl_ejemplo("covariables", "HAQI.csv"), ubicacion_gbd = 123)
#>     anio   sexo covariable valor inferior superior covariable_id
#>    <int> <char>     <char> <num>    <num>    <num>         <int>
#> 1:  2019  ambos       haqi  47.3    45.17    49.43          1099
#> 2:  2023  ambos       haqi  50.9    48.61    53.19          1099

En un proyecto cuyo código nacional no es el location_id de GBD (por ejemplo, PAIS), la configuración lo declara: ubicacion_gbd: 123.

7. La carpeta de un proyecto de modelación

Una causa

Una carpeta de trabajo real trae, además de las tablas, lo que la configuración nombra y lo que el modelador agrega para sí. Por ejemplo, una causa con estimación subnacional por covariables, la severidad desde una partición y un ancla más fina que la población en 80 y más y en menores de 5:

una_causa/
  config.yaml              causa, anio, edad_inicio, las decisiones y sus notas
  ubicaciones.csv
  poblacion.csv            bandas de 5 años: 0-4, 5-9, ..., 80 y más
  ancla.csv                la tabla del contrato (o ancla/ con las descargas de GBD Results)
  covariables.csv          valores nacionales y proxies subnacionales (o covariables/ con las descargas del GHDx)
  proxies_crudos.csv       (en vez de los proxies de covariables) la encuesta que se calibra al leer
  betas.csv
  fuentes_gbd.csv
  poblacion_detalle/
    ancla.csv              la población nacional de 0-1, 1-4, 80-84, ..., 95 y más, del año del ancla
  particion/
    <corrida>/             la partición de severidad
  LEEME.md                 notas del modelador: el paquete no lo lee
  resultados/              lo escribe dl_correr()

Las tablas siguen las reglas de la sección 3: cada una es <tabla>.csv o una carpeta <tabla>/, cada archivo se reconoce por sus columnas y una tabla con solo el encabezado no existe.
La partición de severidad es la única ruta que se declara: severidad.particion: particion/<corrida>, relativa a la carpeta del proyecto. La severidad sale de ella en vez de severidad.csv; con severidad.padre, si es la partición de la causa padre. Sus secuelas y estados de salud deben estar en los catálogos de GBD 2023 del paquete (ver Subtipos y suma). Los límites de la tabla severidad van en $[0, 1]$ ; los de la severidad que sale de la partición de una hija o de un componente pueden pasar de 1 (son los de la partición divididos por su cuota) y se aceptan con un aviso, como en la versión 0.2.2.
poblacion_detalle hace falta solo si una banda del ancla cabe dentro de una banda de la población (sección 5).
El año que se estima es anio, y la carpeta sirve para los demás sin editarla: dl_proyecto(carpeta, anio = 2021) la lee para otro año y dl_correr(carpeta, semilla = 1, anios = 2018:2023) escribe una corrida por año. Las tablas traen las filas de cada año (la población, el ancla, las covariables). Si el ancla no trae la prevalencia del año que se estima y sí la del año anterior, el nivel nacional se proyecta desde ese año (uno a lo sumo) y un mensaje lo anuncia; ancla.anio lo declara de forma explícita. La guía Corridas, versiones y tablas consolidadas lo desarrolla.
ancla.error_maximo y mortalidad_exceso.fraccion_aguda son claves de la configuración: el error relativo mediano máximo entre la prevalencia ajustada y la del ancla con que se escribe la corrida (0.05 por defecto) y la parte de las muertes que ocurre en la fase aguda, que se descuenta del csmr del ancla (nada por defecto). sensibilidad.fraccion_aguda es la lista de valores de esta última que recorre la sensibilidad.
avanzado lleva, tal cual, las claves del formato completo que la configuración no tiene, cada una con su procedencia. Las más usadas: emr_prior.factor_techo (el factor del techo de la mortalidad en exceso, 3 por defecto), nsub, offset_lognormal y emr_prior.fraccion_aguda.cfr_30d. La lista completa está en ?dl_configuracion.

ancla:
  error_maximo: 0.08
mortalidad_exceso:
  fraccion_aguda: 0.3
avanzado:
  emr_prior:
    factor_techo: 6

Lo que no tiene clave ni tabla (las decisiones, de dónde sale cada número) va en notas, que cada corrida guarda en su manifiesto.

Varias causas, subtipos y su suma

Hay dos formas de organizar varias causas:

Un proyecto con varias causas: cada causa tiene su config/<causa>.yaml y comparten las tablas, cuyas filas dicen de qué causa son en la columna causa (una fila sin causa vale para todas). Es la forma natural de los subtipos: la causa padre los declara en subtipos, y cada subtipo encuentra ahí a su padre, usa sus betas si no tiene filas propias y su corrida lo declara, que es lo que pide la suma. Un subtipo tiene una sola causa padre: que dos configuraciones del proyecto lo declaren en subtipos es un error. Así está el ejemplo:
```
list.files(dl_ejemplo(), pattern = "[.]yaml$", recursive = TRUE)
#> [1] "config/9100.yaml" "config/9101.yaml" "config/9102.yaml" "config/9103.yaml"
```
Para agregar una causa, mueve config.yaml a config/<causa>.yaml y llama de nuevo a dl_nuevo_proyecto() con la causa nueva.

Una carpeta por causa: cada carpeta es un proyecto de una causa, con su config.yaml y sus tablas. Es cómodo cuando cada causa tiene fuentes propias, pero un subtipo leído solo no conoce a su causa padre: lo declara con subtipo_de: <causa padre>, para que su corrida se pueda sumar. Sin filas propias en betas, usa las de esa causa, así que la tabla betas del padre sirve tal cual; con filas propias, las suyas:

betas_padre <- read.csv(dl_ejemplo("betas.csv"), encoding = "UTF-8")
unique(betas_padre$causa)                                # solo las del padre
#> [1] 9100
config_subtipo <- list(causa = 9101, anio = 2023, edad_inicio = 30, subtipo_de = 9100)
p <- dl_proyecto(configuracion = config_subtipo, ubicaciones = ubicaciones, poblacion = poblacion,
                 ancla = dl_ejemplo("ancla"), covariables = dl_ejemplo("covariables"), betas = betas_padre,
                 severidad = severidad[severidad$causa == 9101, ])
p$configuracion$extraction$cause_id
#> [1] 9100
p$configuracion$origen$betas$covariable                  # las betas del padre
#> [1] "SEV_scalar_agestd_cvd_pvd" "LDI_pc"                   
#> [3] "haqi"

La causa que es la suma de sus subtipos. Una causa padre con subtipos se ajusta como cualquier otra, con su ancla. Si 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í; los subtipos que no se modelan van en subtipos_omitidos, cada uno con su motivo:

causa: 1010
nombre: Enfermedad de ejemplo
anio: 2023
subtipos: [1011, 1012, 1013]
suma_de_subtipos: sí
subtipos_omitidos:
  - {causa: 1013, motivo: sin datos suficientes}

Esa configuración lleva nombre y no lleva claves del modelo (edad_inicio, ancla, mortalidad_exceso…): no hay nada que ajustar. De las tablas solo usa ubicaciones y poblacion, así que puede ser una configuración más de un proyecto con varias causas o vivir en su propia carpeta, con esas dos tablas. print() dice qué suma, y dl_revisar_proyecto() revisa su configuración, sus dos tablas y qué subtipos tienen configuración en el proyecto:

suma <- dl_proyecto(configuracion = list(causa = 9200, nombre = "Suma de ejemplo", anio = 2023,
                                         subtipos = c(9101, 9102, 9103), suma_de_subtipos = "sí",
                                         subtipos_omitidos = list(list(causa = 9103, motivo = "sin datos"))),
                    ubicaciones = ubicaciones, poblacion = poblacion)
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 (omitido: 9103): no se ajusta; dl_correr() suma las corridas de sus subtipos
#>   tablas:
#>     ubicaciones 26 fila(s), de argumento `ubicaciones` (data.frame)
#>     poblacion   2100 fila(s), de argumento `poblacion` (data.frame)

La suma es la misma en las dos formas de organizar las causas: cada subtipo se corre con dl_correr() y después dl_correr() de la causa padre busca, en la carpeta de las corridas, la más reciente de cada subtipo y las suma (sin semilla: no hay ajuste):

for (causa in c(1011, 1012)) dl_correr("mi_proyecto", causa = causa, semilla = 1)
dl_correr("mi_proyecto", causa = 1010)

Con una carpeta por causa, las corridas de los subtipos y la de la suma van a la misma carpeta de corridas (carpeta_salida). La guía Subtipos y suma lo desarrolla con el ejemplo, y deja dl_sumar_hijas() para sumar corridas elegidas a mano.

Repetir una corrida

Cada corrida congela en inputs/contrato/ las tablas que usó y la configuración tal como se leyó, y esa carpeta es la de un proyecto: se lee y se corre igual. Las betas quedan bajo la causa de la corrida; la de un subtipo con las betas de su padre lleva además la causa padre: la clave subtipo_de cuando la configuración la declara y, cuando la relación salía de subtipos en la configuración del padre (que no se congela), avanzado: extraction. Así el subtipo se repite solo. Una corrida de prueba del subtipo 9101 del ejemplo:

salida <- file.path(tempdir(), "resultados")
corrida <- dl_correr(dl_ejemplo(), causa = 9101, semilla = 1, rapido = TRUE, sensibilidad = FALSE,
                     carpeta_salida = salida)
congelada <- file.path(corrida$dir, "inputs", "contrato")
list.files(congelada)
#> [1] "ancla.csv"          "betas.csv"          "config.yaml"       
#> [4] "covariables.csv"    "datos.csv"          "poblacion.csv"     
#> [7] "proxies_crudos.csv" "severidad.csv"      "ubicaciones.csv"
cat(tail(readLines(file.path(congelada, "config.yaml"), encoding = "UTF-8"), 4), sep = "\n")
#> avanzado:
#>   extraction:
#>     cause_id: 9100
#>     motivo: subtipo de la causa 9100
dl_proyecto(congelada)$configuracion$extraction$cause_id
#> [1] 9100

dl_correr(congelada, semilla = 1, carpeta_salida = ...) repite la corrida. Una corrida que usó severidad.particion congela también esa partición, en inputs/contrato/particion/<corrida>/, con la ruta de severidad.particion de config.yaml cambiada a esa carpeta y el sha256 de cada archivo en el manifiesto (la tabla severidad, que sale de ella, no se congela aparte): también se repite sola.

8. Lista de verificación

Antes de correr:

config.yaml tiene causa, anio y edad_inicio (y ubicacion_gbd, si el código nacional no es el location_id de GBD y las descargas traen varias ubicaciones).
ubicaciones tiene una sola ubicación sin padre, la nacional, y las subnacionales con la nacional de padre.
poblacion cubre las edades desde edad_inicio, los dos sexos, el año que se estima y todas las ubicaciones subnacionales, con las mismas bandas en todas, seguidas y sin huecos.
ancla/ tiene la descarga sin editar, con todas las medidas en Rate, de los dos sexos y del año que se estima; si sus bandas son más finas que las de la población (80 y más, menores de 5), hay poblacion_detalle.
Cada beta de betas tiene su covariable en covariables, con su valor nacional (o, con valor_nacional_de, el de la covariable que nombra); los proxies subnacionales cierran en ese valor nacional.
datos tiene la prevalencia como proporción y las tasas por persona-año, una fila por sexo; los datos excluidos tienen motivo; datos_en_ajuste lista las medidas que deben entrar, y ancla.peso y notas reflejan un posible doble conteo.
severidad tiene los estados de la causa y sus proporciones suman 1.
dl_revisar_proyecto() termina en «Todo en orden» (o solo con avisos entendidos).
dl_correr(carpeta, semilla = 1, rapido = TRUE) corre de principio a fin (la prueba pasa también por la compuerta del error del ancla; ver Las dos compuertas). Después, la corrida de producción sin rapido.

Siguientes pasos

Primeros pasos: correr un proyecto y leer sus resultados.
El modelo: cómo usa el modelo cada tabla de esta guía.
En el sitio del paquete (https://horaciochacon.github.io/dismodlite/), las guías Estimación subnacional, Datos locales y Carga: los años vividos con discapacidad.
La referencia de cada tabla y cada columna: ?dl_tablas; de la carpeta y las dos puertas: ?dl_proyecto; de cada clave: ?dl_configuracion.