GeoQuetzal

Datos geográficos y censales de Guatemala.

GeoQuetzal le da a investigadores acceso programático a los límites administrativos de Guatemala y los microdatos del Censo 2018 (INE), siguiendo la filosofía de tidycensus para Estados Unidos y geobr para Brasil.

¿Qué es GeoQuetzal?

GeoQuetzal unifica en una sola librería tres cosas que normalmente requieren trabajo manual:

Límites administrativos: 22 departamentos y 340 municipios con códigos INE correctos, listos para hacer join con cualquier dataset que mantenga los códigos de departamentos y municipios.
Microdatos censales: personas, hogares, viviendas y emigración del Censo 2018, particionados por departamento para descargas rápidas y eficientes. Se pueden cargar todos los datos a nivel de departamentos o municipios.
Datos sub-municipales: 20,254 lugares poblados con indicadores pre-agregados de demografía, etnicidad, educación, vivienda y servicios. Se pueden cargar todos los datos a nivel de departamentos, municipios, o lugares poblados.

Instalación

pip install geoquetzal

devtools::install_github("geoquetzal/geoquetzal-r")

Ejemplo

GeoQuetzal permite el análisis y la visualización de la mayoría de variables del censo 2018 a nivel de país, departamento y municipio. El análisis a nivel geográfico ofrece más detalle, inmersión y comprensión de los resultados. Por ejemplo, ¿qué porcentaje de acceso a Internet existe en Guatemala? (variable PCH9_I). Haga click en el mapa y pase el puntero encima de las áreas para ver su nombre y porcentaje de acceso a Internet.

Análisis a nivel país

import geoquetzal as gq

# Límites administrativos, carga instantánea, sin necesidad de internet
deptos = gq.departamentos()

# Microdatos censales
df = gq.hogares() #Todos los departamentos, esto puede llevar unos segundos dependiendo de la velocidad de descarga, pero quedan en caché

⬇  Descargando hogares para los 22 departamentos...
   ✓ 3,275,931 hogares cargados

# % de hogares con internet por departamento
acceso_internet = (
    df.groupby("DEPARTAMENTO")["PCH9_I"]
    .apply(lambda x: (x == 1).mean() * 100)
    .round(1)
    .reset_index(name="pct_internet")
)

# Unir con geometría y visualizar
resultado = deptos.merge(acceso_internet, left_on="codigo_depto", right_on="DEPARTAMENTO")
resultado.explore(
    column="pct_internet",
    cmap="YlGnBu",
    tooltip=["departamento", "pct_internet"],
    tooltip_kwds={"aliases": ["Departamento", "% Internet"]},
    tiles="CartoDB positron",
    style_kwds={"weight": 1, "color": "white", "fillOpacity": 0.8},
)

Make this Notebook Trusted to load map: File -> Trust Notebook

if (!requireNamespace("geoquetzal", quietly = TRUE)) {
  remotes::install_github("geoquetzal/geoquetzal-r")
}
library(geoquetzal)
library(dplyr)


Attaching package: 'dplyr'

The following objects are masked from 'package:stats':

    filter, lag

The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union

library(mapview)

# Límites administrativos, carga instantánea, sin necesidad de internet
deptos <- departamentos()

# Microdatos censales
df <- hogares()  # Todos los departamentos, queda en caché

⬇  Descargando hogar para los 22 departamentos...

⬇  Descargando hogar depto 01 (Guatemala)...

⬇  Descargando hogar depto 02 (El Progreso)...

⬇  Descargando hogar depto 03 (Sacatepéquez)...

⬇  Descargando hogar depto 04 (Chimaltenango)...

⬇  Descargando hogar depto 05 (Escuintla)...

⬇  Descargando hogar depto 06 (Santa Rosa)...

⬇  Descargando hogar depto 07 (Sololá)...

⬇  Descargando hogar depto 08 (Totonicapán)...

⬇  Descargando hogar depto 09 (Quetzaltenango)...

⬇  Descargando hogar depto 10 (Suchitepéquez)...

⬇  Descargando hogar depto 11 (Retalhuleu)...

⬇  Descargando hogar depto 12 (San Marcos)...

⬇  Descargando hogar depto 13 (Huehuetenango)...

⬇  Descargando hogar depto 14 (Quiché)...

⬇  Descargando hogar depto 15 (Baja Verapaz)...

⬇  Descargando hogar depto 16 (Alta Verapaz)...

⬇  Descargando hogar depto 17 (Petén)...

⬇  Descargando hogar depto 18 (Izabal)...

⬇  Descargando hogar depto 19 (Zacapa)...

⬇  Descargando hogar depto 20 (Chiquimula)...

⬇  Descargando hogar depto 21 (Jalapa)...

⬇  Descargando hogar depto 22 (Jutiapa)...

   ✓ 3,275,931 registros cargados

# % de hogares con internet por departamento
acceso_internet <- df |>
  group_by(DEPARTAMENTO) |>
  summarise(pct_internet = round(mean(PCH9_I == 1, na.rm = TRUE) * 100, 1))

# Unir con geometría y visualizar
resultado <- merge(deptos, acceso_internet,
                   by.x = "codigo_depto", by.y = "DEPARTAMENTO")

mapview(resultado,
        zcol        = "pct_internet",
        col.regions = RColorBrewer::brewer.pal(9, "YlGnBu"),
        map.types   = "CartoDB.Positron",
        layer.name  = "% Internet",
        label       = "departamento")

Warning: Found less unique colors (9) than unique zcol values (19)! 
Interpolating color vector to match number of zcol values.

Análisis a nivel de departamento (Sacatepéquez)

import geoquetzal as gq

# Límites administrativos
deptos = gq.departamentos()

# Microdatos censales para Sacatepéquez
df = gq.hogares(departamento="Sacatepequez")

# % de hogares con internet por municipio
acceso_internet = (
    df.groupby("MUNICIPIO")["PCH9_I"]
    .apply(lambda x: (x == 1).mean() * 100)
    .round(1)
    .reset_index(name="pct_internet")
)

# Unir con geometría y visualizar
munis = gq.municipios("Sacatepequez")
resultado = munis.merge(acceso_internet, left_on="codigo_muni", right_on="MUNICIPIO")
resultado.explore(
    column="pct_internet",
    cmap="YlGnBu",
    tooltip=["municipio", "pct_internet"],
    tooltip_kwds={"aliases": ["Municipio", "% Internet"]},
    tiles="CartoDB positron",
    style_kwds={"weight": 1, "color": "white", "fillOpacity": 0.8},
)

Make this Notebook Trusted to load map: File -> Trust Notebook

if (!requireNamespace("geoquetzal", quietly = TRUE)) {
  remotes::install_github("geoquetzal/geoquetzal-r")
}
library(geoquetzal)
library(dplyr)
library(mapview)

# Límites administrativos, carga instantánea, sin necesidad de internet
municipios <- municipios()

# Microdatos censales para Sacatepequez
df <- hogares("Sacatepéquez")  # Departamento de Sacatepéquez, queda en caché

⬇  Descargando hogar depto 03 (Sacatepéquez)...

# % de hogares con internet por municipio
acceso_internet <- df |>
  group_by(MUNICIPIO) |>
  summarise(pct_internet = round(mean(PCH9_I == 1, na.rm = TRUE) * 100, 1))

# Unir con geometría y visualizar
resultado <- merge(municipios, acceso_internet,
                   by.x = "codigo_muni", by.y = "MUNICIPIO")

mapview(resultado,
        zcol        = "pct_internet",
        col.regions = RColorBrewer::brewer.pal(9, "YlGnBu"),
        map.types   = "CartoDB.Positron",
        layer.name  = "% Internet",
        label       = "municipio")

Warning: Found less unique colors (9) than unique zcol values (16)! 
Interpolating color vector to match number of zcol values.

Análisis a nivel de municipio (Sacatepéquez, Antigua Guatemala)

import geoquetzal as gq

# Polígonos Voronoi (aproximación de límites sub-municipales)

vor = gq.voronoi_lugares_poblados(municipio="Antigua Guatemala") #También se puede por código de municipio, en este caso el 301

   ℹ 2 lugares poblados excluidos por coordenadas nulas (códigos terminados en 999 — asentamientos sin nombre oficial).
   ✓ 57 polígonos Voronoi generados

# Datos censales pre-agregados por lugar poblado
lp = gq.lugares_poblados(municipio="Antigua Guatemala")

# Eliminar columnas duplicadas antes del merge
lp = lp.drop(columns=["nombre", "lat", "longitud", "area"])

# Join
gdf = vor.merge(lp, on=["departamento", "municipio", "lugar_poblado"])

# Calcular % de hogares con internet
# pch9_i_si = hogares CON internet, pch9_i_no = hogares SIN internet
gdf["pct_internet"] = (
    gdf["pch9_i_si"] / (gdf["pch9_i_si"] + gdf["pch9_i_no"]) * 100
).round(1)

# Mapa interactivo con hover
gdf.explore(
    column="pct_internet",
    cmap="YlGnBu",
    tooltip=["nombre", "pct_internet"],
    tooltip_kwds={"aliases": ["Lugar Poblado", "% con Internet"]},
    popup=["nombre", "pct_internet", "pch9_i_si", "pch9_i_no"],
    popup_kwds={"aliases": [
        "Lugar Poblado", "% con Internet",
        "Hogares con Internet", "Hogares sin Internet"
    ]},
    legend=True,
    tiles="CartoDB positron",
    style_kwds={"weight": 0.5, "color": "white"},
)

Make this Notebook Trusted to load map: File -> Trust Notebook

if (!requireNamespace("geoquetzal", quietly = TRUE)) {
  remotes::install_github("geoquetzal/geoquetzal-r")
}
library(geoquetzal)
library(mapview)

# Polígonos Voronoi (aproximación de límites sub-municipales)
vor <- voronoi_lugares_poblados(municipio = "Antigua Guatemala")

Spherical geometry (s2) switched off

⬇  Descargando lugares poblados depto 03 (Sacatepéquez)...

   ✓ 264 lugares poblados cargados

   ℹ 2 lugares poblados excluidos por coordenadas nulas (códigos terminados en 999).

   ✓ 57 polígonos Voronoi generados

Spherical geometry (s2) switched on

# Datos censales pre-agregados por lugar poblado
lp <- lugares_poblados(municipio = "Antigua Guatemala")

⬇  Descargando lugares poblados depto 03 (Sacatepéquez)...

   ✓ 264 lugares poblados cargados

# Eliminar columnas duplicadas antes del merge
lp <- lp[, !names(lp) %in% c("nombre", "lat", "longitud", "area")]

# Join
gdf <- merge(vor, lp, by = c("departamento", "municipio", "lugar_poblado"))

# Calcular % de hogares con internet
gdf$pct_internet <- round(
  gdf$pch9_i_si / (gdf$pch9_i_si + gdf$pch9_i_no) * 100,
  1
)

# Mapa interactivo con hover
mapview(gdf,
        zcol        = "pct_internet",
        col.regions = RColorBrewer::brewer.pal(9, "YlGnBu"),
        map.types   = "CartoDB.Positron",
        layer.name  = "% Internet",
        label       = "nombre")

Warning: Found less unique colors (9) than unique zcol values (50)! 
Interpolating color vector to match number of zcol values.

Datos disponibles

Dataset	Registros	Almacenamiento
Límites administrativos	22 deptos / 340 municipios	Incluido en el paquete
Personas	14,901,286	GitHub (~333 MB)
Hogares	3,275,931	GitHub (~38 MB)
Viviendas	~3,300,000	GitHub (~30 MB)
Emigración	242,203	GitHub (~1.6 MB)
Lugares Poblados	20,254	GitHub

Autores

Desarrollado por Jorge Yass y Anasilvia Salazar — docentes en la Universidad del Valle de Guatemala (UVG) y estudiantes de doctorado en Iowa State University (ISU).

📦 PyPI · Python GitHub · R GitHub · 📄 Licencia MIT