# Diccionario de datos

## Archivos de entrada del pipeline

---

### `proporciones_nacionales.csv`

Proporción del área nacional en cada categoría de USV por estrategia y año, derivadas del modelo SISEPUEDE.

| Columna | Tipo | Descripción | Ejemplo |
|---------|------|-------------|---------|
| `Estrategia` | `str` | Nombre completo de la estrategia de descarbonización | `"Desarrollo tradicional"` |
| `Año` | `int` | Período de tiempo (0 = año base; máx 35 = horizonte 2050) | `0` |
| `Categoria` | `str` | Categoría de uso del suelo y vegetación | `"Bosque primario"` |
| `Total` | `int` | Hectáreas nacionales en esta categoría (México = 196 437 500 ha) | `75710268` |
| `Proporcion` | `float` | Fracción = Total / Superficie total México; suma 1.0 por (Estrategia, Año) | `0.385417` |

**Categorías válidas:** `Bosque primario`, `Bosque cultivado`, `Manglar`, `Pastizales`, `Agricultura`, `Humedales`, `Asentamiento humano`, `Otros`

**Estrategias en el ejemplo Yucatán:** `Desarrollo tradicional`, `Estrategia intersectorial`, `Mejoras incrementales`, `Cambios en el consumo`, `Soluciones de oferta`, `Baseline`

---

### `emisiones_nacionales.csv`

Emisiones AFOLU del país bajo cada estrategia, por año y subsector, en MtCO₂e/año.

| Columna | Tipo | Descripción | Ejemplo |
|---------|------|-------------|---------|
| `Estrategia` | `str` | Nombre completo de la estrategia | `"Estrategia intersectorial"` |
| `Año` | `int` | Período de tiempo (0–35) | `35` |
| `Agricultura` | `float` | MtCO₂e/año — subsector AGRC | `49.71` |
| `Forestal` | `float` | MtCO₂e/año — subsector FRST (negativo = secuestro neto) | `-170.36` |
| `Uso_de_suelo` | `float` | MtCO₂e/año — subsector LNDU | `4.44` |
| `Estiercol` | `float` | MtCO₂e/año — subsector LSMM | `4.20` |
| `Ganaderia` | `float` | MtCO₂e/año — subsector LVST | `33.94` |
| `Suelo` | `float` | MtCO₂e/año — subsector SOIL | `11.39` |
| `Emisiones_CO2e_AFOLU` | `float` | MtCO₂e/año — suma de los seis subsectores | `-66.68` |

> **Unidades:** MtCO₂e/año (millones de toneladas de CO₂ equivalente, utilizando GWP a 100 años del AR5 del IPCC). Los valores negativos en `Forestal` y `Emisiones_CO2e_AFOLU` indican secuestro neto.

---

### `cobertura_por_unidad.csv`

Superficie (ha) por categoría de USV para cada unidad territorial. En el ejemplo Yucatán, son los 106 municipios.

| Columna | Tipo | Descripción | Ejemplo |
|---------|------|-------------|---------|
| `NOMGEO` | `str` | Nombre de la unidad territorial | `"ABALA"` |
| `categoria_SISEPUEDE` | `str` | Categoría de cobertura (mismo vocabulario que `proporciones_nacionales.csv`) | `"Bosque primario"` |
| `area_total_ha` | `float` | Superficie en hectáreas de esta categoría en esta unidad | `10124.06` |

> **Fuente (caso Yucatán):** Serie 7 de Uso del Suelo y Vegetación, INEGI (2022). Las categorías del INEGI se reclasificaron al esquema de 8 categorías de SISEPUEDE siguiendo la correspondencia documentada en Cruz Núñez (2025, Tabla 3).

---

### `matriz_transicion.xlsx`

Matriz de transición histórica entre categorías de cobertura. Define la probabilidad de que un área en categoría $i$ transite a categoría $j$ en un período dado.

**Estructura:** Matriz cuadrada de 8×8 (categorías × categorías).
- Filas: categoría de origen
- Columnas: categoría de destino
- Valores: fracción de área (deben sumar 1.0 por fila)
- Primera columna: nombre de la categoría origen (`from`)

> **Fuente (caso Yucatán):** Calculada a partir de la intersección espacial de las Series 5 (2013) y 6 (2016) del USV de INEGI. Elaboración propia con QGIS y R (`sf`).

---

### `caracterizacion_territorial.csv`

Variables socioeconómicas y ambientales por unidad territorial, para el Análisis de Componentes Principales (Fase 6).

| Columna | Descripción | Fuente |
|---------|-------------|--------|
| `NOMGEO` | Nombre del municipio | — |
| `idh2020` | Índice de Desarrollo Humano 2020 (0–1) | PNUD, 2020 |
| `habitantes` | Población total | INEGI, Censo 2020 |
| `pib` | PIB per cápita (USD) | González y Gallegos, 2014 |
| `suptotal` | Superficie municipal total (ha) | INEGI, 2022 |
| `supagropec` | Superficie agropecuaria (ha) | INEGI, 2022 |
| `bovinos` | Cabezas de ganado bovino | SIAP, 2022 |
| `porcinos` | Cabezas de ganado porcino | SIAP, 2022 |
| `cambio0020` | Cambio de cobertura forestal 2000–2020 (ha) | Elaboración propia |
| `supforestal` | Superficie forestal (ha) | CONAFOR/INEGI, 2022 |
| `supplantaciones` | Superficie de plantaciones forestales (ha) | CONAFOR/INEGI, 2022 |
| `gini` | Coeficiente de Gini (0–1) | CONEVAL, 2020 |
| `pca` | Grupo asignado por k-means (1, 2 o 3) | Elaboración propia |

> El campo `pca` es un **resultado** del Análisis de Componentes Principales (Fase 6), no un insumo. Está incluido para facilitar la reproducción directa de mapas y figuras sin re-ejecutar el PCA.

---

## Variables de salida del pipeline

### Salidas de Fase 3 (`aporte_municipal_por_estrategia`)

| Columna | Descripción |
|---------|-------------|
| `NOMGEO` | Unidad territorial |
| `Estrategia` | Estrategia de descarbonización |
| `Año` | Período (0–35) |
| `categoria_SISEPUEDE` | Categoría de cobertura |
| `aporte_total_ha` | Hectáreas estimadas de esta categoría en esta unidad bajo esta estrategia y año |

### Salidas de Fase 4 (`resultados_superficies`)

Extiende Fase 3 con:

| Columna adicional | Descripción |
|-------------------|-------------|
| `area_total_ha` | Superficie base de la unidad en esta categoría (ha) |
| `superficie_inicial` | Superficie al inicio del período (ha) |
| `superficie_final` | Superficie al final del período (ha), aplicando la matriz de transición |

### Salidas de Fase 5 (`emisiones_municipales`)

| Columna | Descripción |
|---------|-------------|
| `NOMGEO` | Unidad territorial |
| `Estrategia` | Estrategia |
| `Año` | Período |
| `Emisiones_CO2e` | MtCO₂e/año distribuidas territorialmente |
| `peso_territorial` | Fracción del área total de la región en esta unidad |

---

## Vocabulario de categorías USV

Correspondencia completa entre categorías de SISEPUEDE, nombres del pipeline y nomenclatura de INEGI:

| Pipeline (este repositorio) | SISEPUEDE | Serie 7 INEGI (simplificada) |
|-----------------------------|-----------|-------------------------------|
| Bosque primario | `area_lndu_forests_primary` | Bosque de coníferas, encino, tropical perennifolio, etc. |
| Bosque cultivado | `area_lndu_forests_secondary` | Vegetación secundaria arbórea, arbustiva y herbácea |
| Manglar | `area_lndu_forests_mangroves` | Manglar |
| Pastizales | `area_lndu_grasslands` | Pastizal inducido, cultivado y natural |
| Agricultura | `area_lndu_croplands` | Agricultura de temporal, riego, humedad |
| Humedales | `area_lndu_wetlands` | Petén, tular, vegetación acuática y subacuática |
| Asentamiento humano | `area_lndu_settlements` | Zona urbana, asentamientos humanos |
| Otros | `area_lndu_other` | Desprovisto de vegetación, sin vegetación aparente, cuerpos de agua |

> La reclasificación de categorías INEGI al esquema SISEPUEDE se realizó siguiendo los criterios de Cruz Núñez (2025) y consultando la nomenclatura de Kalra et al. (2023, Apéndice metodológico).