---
title: "Explorar el censo por tema"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Explorar el censo por tema}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(censosbo)
```

El CPV-2024 tiene 393 variables. Buscarlas por nombre funciona cuando ya sabes qué
buscas, pero no ayuda a responder «¿qué hay sobre educación?» ni —más importante—
«¿a quién se le preguntó esto?». Esta viñeta cubre las dos cosas.

## Los temas

Cada variable pertenece a uno de 21 temas, y el mismo vocabulario se aplica a los
cinco censos. Diecisiete son los que el propio INE declara en su catálogo ANDA; los
otros cuatro los añade el paquete y están marcados en la columna `fuente`.

```{r}
censo_temas()[, c("tema", "etiqueta", "capitulo", "n_variables")]
```

El conteo se calcula en el momento, así que puedes acotarlo a una tabla:

```{r}
censo_temas(tabla = "vivienda")[, c("tema", "etiqueta", "n_variables")]
```

Para ver las variables de un tema, `codebook()` acepta el argumento `tema`:

```{r}
codebook(tema = "educacion", tabla = "persona")[, c("variable", "etiqueta", "universo")]
```

## Descargar solo un tema

`vars_tema()` devuelve los nombres en el orden del cuestionario, listos para el
argumento `variables`:

```{r}
vars_tema("educacion", tabla = "persona")
```

```{r eval=FALSE}
get_personas_2024(
  departamento = "Cochabamba",
  variables = vars_tema("educacion", tabla = "persona")
)
```

Las derivadas del INE van al final. Si solo quieres las preguntas tal cual se
hicieron, filtra por `origen`:

```{r}
vars_tema("caracteristicas_economicas", tabla = "persona", origen = "cuestionario")
```

## El universo: a quién se le preguntó

Esta es la columna que más errores evita. El cuestionario del CPV-2024 lleva
impresos cuatro filtros de edad y sexo, y varias variables derivadas se calculan
sobre poblaciones aún más restringidas. Compararlas sin tenerlo en cuenta produce
cifras equivocadas sin ningún aviso.

```{r}
codebook(c("p40_lee", "p43_pago", "p53_ecivil", "p54_hvtot", "nivel_edu"),
         tabla = "persona")[, c("variable", "etiqueta", "universo")]
```

Ahí se ve por qué importa: `nivel_edu` **no** describe a toda la población, sino a
las personas de 19 años o más. Si calculas el porcentaje con secundaria sobre el
total de personas, el denominador incluye a menores que nunca pudieron responder y
el resultado sale hacia abajo. El universo correcto es el que declara la variable.

Para ver todas las variables que comparten un universo:

```{r}
cb <- codebook(tabla = "persona")
table(cb$universo, useNA = "no")
```

La versión textual del INE, con sus palabras exactas, está en `codebook_docs()`:

```{r}
codebook_docs("p40_lee", campos = "universo_literal")$universo_literal
```

## Qué mide exactamente una variable

`codebook_docs()` da acceso a la documentación conceptual oficial: la definición,
la pregunta tal como se leyó en campo y las instrucciones que recibió el censista.

```{r}
codebook_docs("p32_pueblo_per", campos = "definicion")$definicion
```

```{r}
codebook_docs("v17_tenencia", campos = "pregunta_literal")$pregunta_literal
```

Y para las variables que el INE construyó, la regla con la que las calculó:

```{r}
codebook_docs("nivel_edu", campos = "regla_derivacion")$regla_derivacion
```

Distinguir una pregunta de una construcción del INE es útil por sí mismo:

```{r}
table(codebook(tabla = "persona")$origen)
```

## Capítulos: la estructura del cuestionario

El cuestionario del CPV-2024 tiene siete capítulos, de la A a la G. `capitulo`
reproduce esa estructura, así que puedes recorrer el censo en el mismo orden en que
se aplicó:

```{r}
codebook(capitulo = "C", origen = "cuestionario")[, c("pregunta", "variable", "etiqueta")]
```

Un detalle que conviene saber: **capítulo y tema son dos ejes independientes**, no
una jerarquía. `v01_tipoviv` está en el capítulo B y `v17_tenencia` en el C, y las
dos son del tema `vivienda_hogar`, porque el cuestionario separó el tipo de
vivienda de su tenencia aunque conceptualmente vayan juntas.

```{r}
codebook(tema = "vivienda_hogar", tabla = "vivienda")[, c("variable", "capitulo", "pregunta")]
```

## Comparar entre censos

Los temas son el eje transversal: el mismo vocabulario se aplica a los cinco
censos, porque el INE publica un diccionario DDI de todos ellos.

```{r}
for (anio in c(1976, 1992, 2001, 2012, 2024)) {
  # En 1976 la tabla de personas se llama `poblacion`.
  tabla <- if (anio == 1976) "poblacion" else "persona"
  cb <- codebook(tema = "educacion", tabla = tabla, anio = anio)
  cat(anio, "->", nrow(cb), "variables:", paste(cb$variable, collapse = ", "), "\n")
}
```

Un tema existe solo en un censo: **religión**, que preguntó únicamente el de 1992.

```{r}
codebook(tema = "religion", anio = 1992)[, c("variable", "etiqueta")]
```

Los capítulos, en cambio, **solo existen en 2024**: los cuestionarios anteriores
tienen otra estructura, el de 2001 no numera sus etiquetas y los de 1976 y 1992
numeran las secciones de vivienda y de persona en paralelo (`v03` es el material de
las paredes y `p03` el sexo). Lo que sí traen los cuatro anteriores es la
agrupación oficial del INE de su época, en la columna `grupo_ine`:

```{r}
table(codebook(anio = 1992)$grupo_ine, useNA = "no")
```

### El universo también cambió entre censos

Esta es la razón principal por la que vale la pena tener el metadato de los cinco
censos: el INE movió el filtro de edad de varias preguntas, así que comparar una
serie temporal sin igualar el universo mide poblaciones distintas en cada punto.

```{r}
for (anio in c(1976, 1992, 2001, 2024)) {
  v <- switch(as.character(anio), "1976" = "p10", "1992" = "P10",
              "2001" = "P36", "2024" = "p40_lee")
  tabla <- if (anio == 1976) "poblacion" else "persona"
  cat(anio, "alfabetismo ->", codebook(v, tabla = tabla, anio = anio)$universo, "\n")
}
```

`get_temporal()` avisa de esto automáticamente cuando se piden variables
armonizadas cuyo universo no coincide entre los años solicitados.

Para poder hacerle caso al aviso hace falta la columna `edad` en el resultado, y
`get_temporal()` solo devuelve lo que se le pide. Los grupos predefinidos
(`grupo = "educacion"`) ya la incluyen; si pides variables sueltas, añádela:

```{r eval=FALSE}
get_temporal(variables = c("sabe_leer", "edad"), anios = c(1992, 2001, 2024)) |>
  filter(edad >= 6, !is.na(sabe_leer)) |>       # el universo comparable: 6+
  group_by(anio) |>
  summarise(pct_alfabetizado = round(100 * mean(sabe_leer == 1), 1))
```

## Los indicadores de manzano y comunidad

Las fichas del geoportal tienen su propio desglose, más fino que el tema: 15
bloques. Conviven con la taxonomía, así que puedes usar el que te convenga.

```{r}
censo_bloques_meta[, c("bloque", "etiqueta", "tema")]
```

Cada indicador es un conteo, y para leerlo como porcentaje hace falta el total
sobre el que se calcula. Eso está en `denominador`:

```{r}
codebook(tabla = "ficha")[3:8, c("variable", "bloque", "denominador")]
```

Las variables cuyo `denominador` es `NA` son los totales mismos.

## Fuentes y atribución

La taxonomía y los metadatos de contexto se construyen a partir de dos fuentes
oficiales del INE Bolivia:

- El **cuestionario censal del CPV-2024**, de donde salen los capítulos, la
  numeración de preguntas y los filtros de universo impresos en el formulario.
- Los **diccionarios DDI del catálogo ANDA**, estudios 132 (CPV-2024), 8
  (CPV-2012), 10 (CNPV-2001), 47 (CNPV-1992) y 46 (CNPV-1976), de donde salen los
  temas oficiales, el universo de cada variable, las definiciones conceptuales, las
  preguntas literales y las reglas de derivación.

Los textos de `codebook_docs_meta` se reproducen literalmente; el INE los publica
bajo la condición «Uso público». El objeto guarda la procedencia exacta de los
archivos usados:

```{r}
attr(codebook_docs_meta, "ddi")[, c("anio", "estudio", "idno", "fecha")]
```

Un aviso que el propio contraste con estas fuentes hizo evidente: el DDI del INE
tiene errores puntuales. En el CPV-2012, la variable de estado civil viene con las
categorías de otra pregunta. Por eso el paquete **nunca sobrescribe** las etiquetas
de valor que ya trae el diccionario de microdatos; las discrepancias se registran
para revisión en `data-raw/ddi/reporte_valores.md`.