---
title: "Sistema de Centros Poblados del Perú"
subtitle: "Acceso a Capitales, Centros Poblados y Asentamientos Dispersos"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Sistema de Centros Poblados del Perú}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 8,
  fig.height = 6,
  warning = FALSE,
  message = FALSE
)
```

## Introducción

Este documento presenta las funciones del paquete `rsdot` para acceder y analizar el **Sistema de Centros Poblados del Perú**, basado en la clasificación oficial del Instituto Nacional de Estadística e Informática (INEI) según el Censo de Población y Vivienda 2017.

### Clasificación INEI de Asentamientos Humanos

El INEI clasifica los asentamientos humanos en el Perú utilizando una jerarquía basada en **tamaño poblacional, organización de viviendas y disponibilidad de servicios**:

#### 1. **Capitales** (Administrativas)
Centros administrativos principales del país:

- **Capital Departamental**: Sede del gobierno regional (ej. Cusco, Arequipa, Lima)
- **Capital Provincial**: Sede de la administración provincial
- **Capital Distrital**: Sede del gobierno local distrital

*Características*: Centros urbanos con la mayor concentración de servicios públicos, infraestructura y población.

#### 2. **Centros Poblados (CPs)**
Núcleos de población con las siguientes características:

- **Definición**: Asentamientos con nombre propio, población generalmente > 150 habitantes (según criterios del INEI)
- **Organización**: Viviendas agrupadas con cierta organización espacial
- **Servicios**: Infraestructura básica (agua, desagüe, luz) y vías de acceso
- **Clasificación**:
  - **Urbanos**: Viviendas agrupadas, con pistas/veredas, mayor densidad
  - **Rurales**: Viviendas más dispersas, menor densidad (caseríos, comunidades)

#### 3. **Asentamientos Dispersos**
Poblaciones muy pequeñas o viviendas aisladas:

- Poblaciones que no alcanzan la categoría de Centro Poblado
- Viviendas aisladas en zonas rurales
- Sin organización espacial definida
- Servicios básicos limitados o ausentes

### Funciones Disponibles:

El paquete `rsdot` proporciona dos funciones principales:

- **`get_capitales()`**: Accede a las capitales departamentales, provinciales y distritales
- **`get_centros_poblados()`**: Accede a todos los centros poblados y asentamientos dispersos censados

Ambas funciones utilizan datos georreferenciados del Censo 2017, accesibles a través de la plataforma **VIsor SDOT** de la PCM.

```{r load-packages}
library(rsdot)
library(ggplot2)
library(dplyr)
library(sf)
```

---

## Función 1: get_capitales()

Accede a las **capitales administrativas** (departamentales, provinciales y distritales) identificadas en el Censo 2017. Estas son los centros urbanos principales que sirven como sedes del gobierno en sus respectivos niveles.

### Jerarquía de Capitales

El campo `capital` indica la jerarquía administrativa:

- **1**: Capital departamental
- **2**: Capital provincial
- **3**: Capital distrital

### Uso Básico

```{r capitales-basico}
# Obtener todas las capitales de Cusco
capitales_cusco <- get_capitales(departamento = "CUSCO")

# Ver estructura de los datos
head(capitales_cusco)

# Resumen estadístico
summary(capitales_cusco$pob)
```

### Análisis por Jerarquía

```{r analisis-jerarquia}
# Clasificar capitales por tipo
capitales_cusco %>%
  st_drop_geometry() %>%
  mutate(
    tipo = case_when(
      capital == 1 ~ "Departamental",
      capital == 2 ~ "Provincial",
      capital == 3 ~ "Distrital"
    )
  ) %>%
  group_by(tipo) %>%
  summarise(
    n_capitales = n(),
    pob_total = sum(pob, na.rm = TRUE),
    pob_promedio = round(mean(pob, na.rm = TRUE)),
    pob_mediana = median(pob, na.rm = TRUE)
  )
```

### Identificar Capitales Provinciales

```{r capitales-provinciales}
# Las capitales provinciales son centros urbanos importantes
capitales_prov <- capitales_cusco %>%
  filter(capital == 2)

capitales_prov %>%
  st_drop_geometry() %>%
  select(nombprov, cen_pob, pob) %>%
  arrange(desc(pob))
```

### Visualización de la Jerarquía Administrativa

```{r mapa-jerarquia, fig.width=9, fig.height=7}
# Crear categorías para visualización
capitales_cusco <- capitales_cusco %>%
  mutate(
    tipo_capital = case_when(
      capital == 1 ~ "Departamental",
      capital == 2 ~ "Provincial",
      capital == 3 ~ "Distrital"
    ),
    tipo_capital = factor(
      tipo_capital, 
      levels = c("Departamental", "Provincial", "Distrital")
    )
  )

# Mapa de capitales por jerarquía administrativa
ggplot(capitales_cusco) +
  geom_sf(aes(color = tipo_capital, size = pob), alpha = 0.7) +
  scale_size_continuous(
    name = "Población",
    range = c(1, 12),
    labels = scales::comma,
    breaks = c(1000, 10000, 50000, 150000, 300000)
  ) +
  scale_color_manual(
    name = "Jerarquía\nAdministrativa",
    values = c(
      "Departamental" = "#E41A1C",  # Rojo - Capital departamental
      "Provincial" = "#377EB8",      # Azul - Capitales provinciales
      "Distrital" = "#4DAF4A"        # Verde - Capitales distritales
    )
  ) +
  theme_minimal() +
  labs(
    title = "Jerarquía Administrativa de Capitales en Cusco",
    subtitle = "Sistema de asentamientos según clasificación INEI - Censo 2017",
    caption = "Fuente: INEI - Censo de Población y Vivienda 2017 | Visor SDOT"
  ) +
  theme(
    legend.position = "right",
    plot.title = element_text(face = "bold", size = 14),
    plot.subtitle = element_text(size = 11)
  )
```

---

## Función 2: get_centros_poblados()

Accede al **universo completo de centros poblados y asentamientos dispersos** censados en 2017, incluyendo tanto núcleos urbanos organizados como viviendas dispersas en zonas rurales.


Esta función proporciona acceso a:

1. **Centros Poblados Urbanos**: Asentamientos con viviendas agrupadas, pistas/veredas, servicios básicos
2. **Centros Poblados Rurales**: Caseríos, comunidades, anexos con cierta organización
3. **Asentamientos Dispersos**: Viviendas aisladas, poblaciones muy pequeñas

### Datos Disponibles

La función proporciona información detallada sobre:

- **Población**: Total de habitantes
- **Vivienda**: Total de viviendas, viviendas particulares, viviendas ocupadas
- **Ubicación**: Coordenadas geográficas (REFERENCIAL)
- **Administración**: Departamento, provincia, distrito

### Uso Básico

```{r centros-poblados-basico}
# Obtener centros poblados de Tacna (departamento pequeño para ejemplo)
cp_tacna <- get_centros_poblados(departamento = "TACNA")

# Estructura de los datos
head(cp_tacna)

# Estadísticas generales
cat("Total de asentamientos censados:", nrow(cp_tacna), "\n")
cat("Población total:", format(sum(cp_tacna$pob, na.rm = TRUE), big.mark = ","), "\n")
cat("Viviendas totales:", format(sum(cp_tacna$viv, na.rm = TRUE), big.mark = ","), "\n")
```

### Clasificación por Tamaño Poblacional

Siguiendo los criterios del INEI para clasificación urbano-rural:

```{r clasificacion-tamano}
# Clasificar centros poblados según tamaño
cp_clasificados <- cp_tacna %>%
  mutate(
    categoria = case_when(
      pob >= 10000 ~ "Urbano Grande (≥10,000 hab.)",
      pob >= 2000 ~ "Urbano Mediano (2,000-9,999 hab.)",
      pob >= 500 ~ "Urbano Pequeño (500-1,999 hab.)",
      pob >= 150 ~ "Rural Concentrado (150-499 hab.)",
      pob >= 50 ~ "Rural Disperso (50-149 hab.)",
      TRUE ~ "Asentamiento Disperso (<50 hab.)"
    ),
    categoria = factor(
      categoria,
      levels = c(
        "Urbano Grande (≥10,000 hab.)",
        "Urbano Mediano (2,000-9,999 hab.)",
        "Urbano Pequeño (500-1,999 hab.)",
        "Rural Concentrado (150-499 hab.)",
        "Rural Disperso (50-149 hab.)",
        "Asentamiento Disperso (<50 hab.)"
      )
    )
  )

# Distribución por categoría
distribucion <- cp_clasificados %>%
  st_drop_geometry() %>%
  group_by(categoria) %>%
  summarise(
    n_asentamientos = n(),
    pob_total = sum(pob, na.rm = TRUE),
    pob_promedio = round(mean(pob, na.rm = TRUE)),
    viv_total = sum(viv, na.rm = TRUE)
  ) %>%
  mutate(
    pct_asentamientos = round(n_asentamientos / sum(n_asentamientos) * 100, 1),
    pct_poblacion = round(pob_total / sum(pob_total) * 100, 1)
  )

print(distribucion)
```

### Visualización del Sistema de Asentamientos

```{r mapa-sistema-completo, fig.width=10, fig.height=8}
# Mapa del sistema completo de asentamientos
ggplot(cp_clasificados) +
  geom_sf(aes(color = categoria, size = pob), alpha = 0.6) +
  scale_size_continuous(
    name = "Población",
    range = c(0.5, 8),
    labels = scales::comma
  ) +
  scale_color_brewer(
    name = "Clasificación\nINEI",
    palette = "Spectral", 
    direction = -1
  ) +
  theme_minimal() +
  labs(
    title = "Sistema de Centros Poblados y Asentamientos Dispersos",
    subtitle = "Departamento de Tacna - Clasificación según tamaño poblacional INEI",
    caption = "Fuente: INEI - Censo de Población y Vivienda 2017 | Visor SDOT\nNOTA: Ubicaciones son referenciales"
  ) +
  theme(
    legend.position = "right",
    plot.title = element_text(face = "bold", size = 14),
    legend.box = "vertical"
  )
```

### Análisis de Concentración Urbana vs Rural

```{r urbano-rural}
# Clasificación urbano-rural según INEI (> 2000 hab = urbano)
cp_tacna_ur <- cp_tacna %>%
  mutate(
    clasificacion = if_else(pob >= 2000, "Urbano", "Rural/Disperso")
  )

# Análisis de concentración
concentracion <- cp_tacna_ur %>%
  st_drop_geometry() %>%
  group_by(clasificacion) %>%
  summarise(
    n_asentamientos = n(),
    pob_total = sum(pob, na.rm = TRUE),
    viv_total = sum(viv, na.rm = TRUE)
  ) %>%
  mutate(
    pct_asentamientos = round(n_asentamientos / sum(n_asentamientos) * 100, 1),
    pct_poblacion = round(pob_total / sum(pob_total) * 100, 1)
  )

print(concentracion)

# Interpretación
cat("\nInterpretación:\n")
cat("- Los asentamientos urbanos (≥2,000 hab.) representan el", 
    concentracion$pct_asentamientos[concentracion$clasificacion == "Urbano"], 
    "% de los asentamientos\n")
cat("- Pero concentran el", 
    concentracion$pct_poblacion[concentracion$clasificacion == "Urbano"], 
    "% de la población total\n")
```

---

## Análisis Integrado: Capitales en el Sistema de Asentamientos

### Comparar Capitales con su Contexto Poblacional

```{r analisis-integrado}
# Obtener datos completos de Cusco
capitales <- get_capitales(departamento = "CUSCO")
centros <- get_centros_poblados(departamento = "CUSCO")

# Identificar centros poblados que son capitales
capitales_ids <- unique(capitales$codccpp)

centros <- centros %>%
  mutate(
    es_capital = codccpp %in% capitales_ids,
    tipo_asentamiento = case_when(
      es_capital ~ "Capital (administrativa)",
      pob >= 2000 ~ "Centro Poblado Urbano",
      pob >= 500 ~ "Centro Poblado Rural",
      pob >= 150 ~ "Centro Poblado Pequeño",
      TRUE ~ "Asentamiento Disperso"
    )
  )

# Estadísticas comparativas
comparacion <- centros %>%
  st_drop_geometry() %>%
  group_by(tipo_asentamiento) %>%
  summarise(
    n = n(),
    pob_total = sum(pob, na.rm = TRUE),
    pob_promedio = round(mean(pob, na.rm = TRUE)),
    viv_total = sum(viv, na.rm = TRUE)
  ) %>%
  mutate(
    pct_asentamientos = round(n / sum(n) * 100, 1),
    pct_poblacion = round(pob_total / sum(pob_total) * 100, 1)
  ) %>%
  arrange(desc(pob_total))

print(comparacion)
```

### Visualización del Sistema Completo

```{r mapa-sistema-integrado, fig.width=10, fig.height=8}
# Mapa que muestra la jerarquía completa del sistema de asentamientos
ggplot() +
  # Primero: asentamientos dispersos y pequeños (fondo)
  geom_sf(
    data = centros %>% filter(!es_capital, pob < 500),
    aes(size = pob),
    color = "gray70",
    alpha = 0.3
  ) +
  # Segundo: centros poblados medianos
  geom_sf(
    data = centros %>% filter(!es_capital, pob >= 500, pob < 2000),
    aes(size = pob),
    color = "steelblue",
    alpha = 0.5
  ) +
  # Tercero: centros poblados urbanos (no capitales)
  geom_sf(
    data = centros %>% filter(!es_capital, pob >= 2000),
    aes(size = pob),
    color = "darkblue",
    alpha = 0.6
  ) +
  # Cuarto: capitales (destacadas)
  geom_sf(
    data = centros %>% filter(es_capital),
    aes(size = pob),
    color = "#E41A1C",
    alpha = 0.8
  ) +
  scale_size_continuous(
    name = "Población",
    range = c(0.3, 10),
    labels = scales::comma,
    breaks = c(100, 1000, 10000, 50000, 200000)
  ) +
  theme_minimal() +
  labs(
    title = "Sistema Jerárquico de Asentamientos Humanos en Cusco",
    subtitle = "Capitales (rojo), Centros Poblados Urbanos (azul oscuro), Rurales (azul claro), Dispersos (gris)",
    caption = "Fuente: INEI - Censo 2017 | Clasificación según INEI\nNOTA: Tamaño proporcional a población"
  ) +
  theme(
    legend.position = "right",
    plot.title = element_text(face = "bold", size = 14)
  )
```

---

## Análisis de Vivienda y Servicios

### Características Habitacionales por Tipo de Asentamiento

```{r analisis-vivienda}
# Análisis de vivienda por tipo de asentamiento
vivienda_stats <- centros %>%
  st_drop_geometry() %>%
  filter(viv > 0) %>%
  mutate(
    tipo = case_when(
      es_capital ~ "Capital",
      pob >= 2000 ~ "Urbano",
      pob >= 500 ~ "Rural",
      TRUE ~ "Disperso"
    )
  ) %>%
  group_by(tipo) %>%
  summarise(
    n_asentamientos = n(),
    pob_total = sum(pob, na.rm = TRUE),
    viv_total = sum(viv, na.rm = TRUE),
    viv_ocupadas = sum(viv_part_o, na.rm = TRUE),
    pob_por_vivienda = round(pob_total / viv_total, 2),
    tasa_ocupacion = round(viv_ocupadas / sum(viv_part, na.rm = TRUE) * 100, 1)
  )

print(vivienda_stats)
```

### Densidad Habitacional

```{r densidad-habitacional, fig.width=8, fig.height=6}
# Análisis de densidad habitacional
cp_densidad <- centros %>%
  filter(viv > 0) %>%
  mutate(
    pob_por_viv = pob / viv,
    categoria = case_when(
      es_capital ~ "Capital",
      pob >= 2000 ~ "Urbano",
      pob >= 500 ~ "Rural",
      TRUE ~ "Disperso"
    )
  )

# Boxplot de población por vivienda
ggplot(cp_densidad %>% st_drop_geometry(), 
       aes(x = categoria, y = pob_por_viv, fill = categoria)) +
  geom_boxplot() +
  scale_fill_brewer(palette = "Set2") +
  coord_flip() +
  labs(
    title = "Densidad Habitacional por Tipo de Asentamiento",
    subtitle = "Habitantes por vivienda según clasificación INEI",
    x = "Tipo de Asentamiento",
    y = "Población por Vivienda",
    caption = "Fuente: INEI - Censo 2017"
  ) +
  theme_minimal() +
  theme(legend.position = "none")
```

---

## Análisis Provincial y Distrital

### Distribución de Asentamientos por Distrito

```{r por-distrito}
# Análisis por distrito
dist_stats <- centros %>%
  st_drop_geometry() %>%
  group_by(nombdist) %>%
  summarise(
    n_asentamientos = n(),
    n_capitales = sum(es_capital),
    n_urbanos = sum(pob >= 2000),
    n_rurales = sum(pob < 2000 & pob >= 150),
    n_dispersos = sum(pob < 150),
    pob_total = sum(pob, na.rm = TRUE),
    viv_total = sum(viv, na.rm = TRUE)
  ) %>%
  arrange(desc(pob_total)) %>%
  head(10)

print(dist_stats)
```

---

## Casos de Uso Especializados

### 1. Análisis de Accesibilidad a Servicios

```{r accesibilidad, eval=FALSE}
# Ejemplo: Calcular distancia de asentamientos rurales a centros urbanos
library(sf)

# Identificar centros urbanos (≥ 2000 hab)
urbanos <- centros %>%
  filter(pob >= 2000)

# Identificar asentamientos rurales dispersos
rurales <- centros %>%
  filter(pob < 500)

# Calcular distancia al centro urbano más cercano
rurales_con_dist <- rurales %>%
  mutate(
    centro_mas_cercano_idx = st_nearest_feature(., urbanos),
    distancia_km = as.numeric(st_distance(
      geometry,
      urbanos$geometry[centro_mas_cercano_idx],
      by_element = TRUE
    )) / 1000  # Convertir a km
  )

# Estadísticas de accesibilidad
summary(rurales_con_dist$distancia_km)
```

### 2. Jerarquía Urbana Regional

```{r jerarquia-urbana}
# Análisis de jerarquía urbana usando regla rango-tamaño
centros_urbanos <- centros %>%
  filter(pob >= 2000) %>%
  arrange(desc(pob)) %>%
  mutate(
    rango = row_number(),
    pob_esperada = first(pob) / rango,  # Ley de Zipf
    ratio = round(pob / pob_esperada, 2)
  )

# Top 10 centros urbanos
top_urbanos <- centros_urbanos %>%
  st_drop_geometry() %>%
  select(rango, cen_pob, nombdist, pob, pob_esperada, ratio) %>%
  head(10)

print(top_urbanos)
```

### 3. Patrón de Dispersión Rural

```{r patron-dispersion, fig.width=8, fig.height=6}
# Análisis del patrón de asentamientos rurales dispersos
dispersos <- centros %>%
  filter(pob < 150)

# Distribución de población en asentamientos dispersos
ggplot(dispersos %>% st_drop_geometry(), aes(x = pob)) +
  geom_histogram(binwidth = 10, fill = "steelblue", alpha = 0.7) +
  labs(
    title = "Distribución de Población en Asentamientos Dispersos",
    subtitle = "Asentamientos con menos de 150 habitantes",
    x = "Población",
    y = "Número de Asentamientos",
    caption = "Fuente: INEI - Censo 2017"
  ) +
  theme_minimal()
```

---


## Referencias y Recursos

### Fuentes de Datos

- INEI (2017). **Censo de Población y Vivienda 2017**. Instituto Nacional de Estadística e Informática.


### Funciones Relacionadas

- `get_red_vial_nacional()` - Red vial nacional del Perú
- `get_red_vial_departamental()` - Red vial departamental
- `get_departamentos()` - Límites departamentales

---