Referencia de la API — R
Esta página documenta todas las funciones disponibles en el paquete R de GeoQuetzal. Para instalar:
remotes::install_github("geoquetzal/geoquetzal-r")Geografía
Funciones para acceder a los límites administrativos de Guatemala. Los datos se cargan instantáneamente desde el paquete — no requieren conexión a Internet.
country()
Retorna el contorno del país de Guatemala como un objeto sf.
library(geoquetzal)
pais <- country()
plot(sf::st_geometry(pais), col = "lightgreen", border = "gray")departamentos()
Retorna los 22 departamentos de Guatemala con sus códigos INE y geometría.
Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
name |
character | integer |
Nombre o código del departamento (insensible a acentos) |
region |
character |
Filtra por región (ej. "V - Central") |
library(geoquetzal)
# Todos los departamentos
deptos <- departamentos()
# Por nombre (con o sin acentos)
departamentos("Sacatepequez")
departamentos("Sacatepéquez")
# Por código INE
departamentos(3)
# Por región
departamentos(region = "V - Central")municipios()
Retorna los 340 municipios de Guatemala con sus códigos INE y geometría.
Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
departamento |
character | integer |
Filtra por departamento |
name |
character | integer |
Retorna un municipio específico por nombre o código |
library(geoquetzal)
# Todos los municipios de un departamento
municipios("Sacatepequez")
# Un municipio específico
municipios(name = "Antigua Guatemala")
municipios(name = 301)lagos()
Retorna los dos principales lagos de Guatemala (Amatitlán y Atitlán) para superposición en mapas.
library(geoquetzal)
library(ggplot2)
ggplot() +
geom_sf(data = departamentos(), fill = "lightyellow", color = "gray") +
geom_sf(data = lagos(), fill = "lightblue", color = "steelblue")Microdatos Censales
Funciones para acceder a los microdatos del XII Censo Nacional de Población y VII de Vivienda 2018 (INE). Los datos se descargan en formato Parquet desde GitHub Releases y se almacenan en caché localmente.
Para administrar el caché:
gq_cache_dir() # Ver la ubicación del caché
gq_clear_cache() # Limpiar el caché
gq_set_cache("/ruta/custom") # Cambiar la ubicaciónTodas las funciones de microdatos comparten los mismos parámetros de filtro:
| Parámetro | Tipo | Descripción |
|---|---|---|
departamento |
character | integer |
Filtra por departamento (descarga solo ese archivo) |
municipio |
character | integer |
Filtra por municipio (descarga el archivo del departamento padre) |
personas()
Microdatos a nivel de persona. 14,901,286 registros, 84 variables. Cada fila representa una persona.
Variables principales: sexo (PCP6), edad (PCP7), autoidentificación étnica (PCP12), comunidad lingüística maya (PCP13), lengua materna (PCP15), discapacidad (PCP16_A–PCP16_F), escolaridad (PCP17_A), alfabetismo (PCP22), acceso a tecnología (PCP26_A–PCP26_C), empleo (PCP27), fecundidad (PCP35–PCP39).
library(geoquetzal)
df <- personas(departamento = "Huehuetenango")
df <- personas(municipio = "Antigua Guatemala")
df <- personas() # Todo Guatemala (~333 MB)hogares()
Microdatos a nivel de hogar. 3,275,931 registros, 37 variables. Cada fila representa un hogar.
Variables principales: fuente de agua (PCH4), saneamiento (PCH5), electricidad (PCH8), equipamiento — radio, TV, refrigeradora, internet, carro (PCH9_A–PCH9_M), combustible para cocinar (PCH14), remesas (PCH15).
library(geoquetzal)
df <- hogares(departamento = "Sacatepequez")
df <- hogares(municipio = "Antigua Guatemala")
df <- hogares() # Todo Guatemala (~38 MB)viviendas()
Microdatos a nivel de vivienda. ~3,300,000 registros, 11 variables. Cada fila representa una vivienda.
Variables principales: tipo de vivienda (PCV1), material de paredes (PCV2), techo (PCV3), condición (PCV4), piso (PCV5).
library(geoquetzal)
df <- viviendas(departamento = "Sacatepequez")
df <- viviendas() # Todo Guatemala (~30 MB)emigracion()
Registros de emigración internacional. 242,203 registros, 11 variables. Cada fila es una persona que emigró desde un hogar.
Variables principales: sexo (PEI3), edad al emigrar (PEI4), año de partida (PEI5).
library(geoquetzal)
df <- emigracion(departamento = "Huehuetenango")
df <- emigracion() # Todo Guatemala (~1.6 MB)Datos Sub-Municipales
lugares_poblados()
Indicadores pre-agregados a nivel de lugar poblado. 20,254 localidades, 200+ columnas. Cada fila representa un lugar poblado.
Los lugares poblados con códigos terminados en 999 (ej. 102999) representan asentamientos sin nombre oficial (“Otros Lugares Poblados”) y tienen coordenadas nulas. Se incluyen en los datos pero no pueden mapearse.
Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
departamento |
character | integer |
Filtra por departamento (descarga solo ese archivo) |
municipio |
character | integer |
Filtra por municipio |
lugar_poblado |
integer |
Código de 6 dígitos (ej. 301001L) |
library(geoquetzal)
# Todos los lugares poblados
df <- lugares_poblados()
# Filtrar por departamento (descarga solo ese archivo)
df <- lugares_poblados(departamento = "Sacatepéquez")
# Filtrar por municipio
df <- lugares_poblados(municipio = "Antigua Guatemala")
# Un lugar poblado específico
df <- lugares_poblados(lugar_poblado = 301001L)Columnas disponibles por tema:
| Tema | Prefijo de columna | Fuente |
|---|---|---|
| Escalares (población, PEA, años de estudio) | poblacion_total, pea_total, aneduca_promedio… |
persona |
| Autoidentificación étnica | pcp12_maya, pcp12_ladino… |
persona |
| Comunidad lingüística maya | pcp13_kiche, pcp13_mam… |
persona |
| Lengua materna | pcp15_espanol, pcp15_kiche… |
persona |
| Discapacidad | pcp16_a_sin_dificultad… |
persona |
| Escolaridad | pcp17_a_ninguno, pcp17_a_primaria… |
persona |
| Alfabetismo | pcp22_alfabeto, pcp22_no_alfabeto |
persona |
| Empleo | pcp30_1d_agropecuarios… |
persona |
| Tipo de vivienda | pcv1_casa_formal, pcv1_rancho… |
vivienda |
| Material de paredes | pcv2_block, pcv2_adobe… |
vivienda |
| Material de piso | pcv5_tierra, pcv5_torta_cemento… |
vivienda |
| Fuente de agua | pch4_tuberia_dentro, pch4_rio… |
hogar |
| Saneamiento | pch5_inodoro_red_drenajes… |
hogar |
| Electricidad | pch8_red_electrica, pch8_candela… |
hogar |
| Equipamiento del hogar | pch9_i_si (internet), pch9_m_si (carro)… |
hogar |
| Combustible para cocinar | pch14_lena, pch14_gas_propano… |
hogar |
| Remesas | pch15_si, pch15_no |
hogar |
| Emigración desde 2002 | pei1_si, pei1_no |
hogar |
voronoi_lugares_poblados()
Genera polígonos Voronoi aproximados como límites de lugares poblados, recortados a los límites municipales. Estos polígonos son aproximaciones para visualización coroplética — el INE no publica límites oficiales de lugares poblados.
Los lugares poblados con coordenadas nulas (códigos terminados en 999) son excluidos automáticamente. Los municipios con un solo lugar poblado retornan el polígono completo del municipio.
Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
departamento |
character | integer |
Filtra por departamento |
municipio |
character | integer |
Filtra por municipio |
library(geoquetzal)
library(mapview)
# Polígonos Voronoi para un municipio
vor <- voronoi_lugares_poblados(municipio = "Antigua Guatemala")
# Para un departamento completo
vor <- voronoi_lugares_poblados(departamento = "Sacatepéquez")
# Patrón típico: unir con datos censales para coropleta
lp <- lugares_poblados(municipio = "Antigua Guatemala")
lp <- lp[, !names(lp) %in% c("nombre", "lat", "longitud", "area")]
gdf <- merge(vor, lp, by = c("departamento", "municipio", "lugar_poblado"))
gdf$pct_internet <- gdf$pch9_i_si / (gdf$pch9_i_si + gdf$pch9_i_no) * 100
mapview(gdf, zcol = "pct_internet",
col.regions = RColorBrewer::brewer.pal(9, "YlGnBu"),
layer.name = "% con Internet")Funciones de Descripción
Todas las funciones de descripción retornan un data.frame con todas las variables si no se especifica ninguna, o una list con los detalles de la variable solicitada.
| Función | Dataset |
|---|---|
describe_personas(variable) |
Personas |
describe_hogares(variable) |
Hogares |
describe_viviendas(variable) |
Viviendas |
describe_emigracion(variable) |
Emigración |
describe_lugares_poblados(variable) |
Lugares Poblados |
library(geoquetzal)
# Listar todas las variables
describe_personas()
describe_hogares()
# Detalle de una variable específica
describe_personas("PCP12")
# $variable: "PCP12"
# $etiqueta: "Según su origen o historia, ¿cómo se considera o auto identifica?"
# $tipo: "étnica"
# $valores: list(1 = "Maya", 2 = "Garífuna", 3 = "Xinka", ...)
describe_lugares_poblados("pcp12_maya")
# $variable: "pcp12_maya"
# $etiqueta: "Conteo: se identifica como Maya"
# $tipo: "étnica"
# $fuente: "persona"