Harmonized geospatial dataset from the 2022 Brazilian Demographic Census by IBGE

Harmonized geospatial dataset from the 2022 Brazilian Demographic Census by IBGE This dataset provides a harmonized geospatial version of the 2022 Brazilian Demographic Census results at the census tract level. The data are distributed as separate, gzip-compressed files (one per table and per geography layer) together with the script that builds a single GeoPackage from them. The resulting database contains cleaned, standardized, and consistently typed attribute tables linked to official census tract geometries. Variable names were harmonized, data types were explicitly enforced, and structural inconsistencies were resolved to facilitate reproducible spatial analysis and integration with GIS and data science workflows. The original data source is the 2022 Brazilian Demographic Census conducted by the Instituto Brasileiro de Geografia e Estatística (IBGE): the aggregated results by census tract (basic characteristics, households, persons, deaths, indigenous and quilombola populations, income of household heads, and the surroundings of households, residents and block faces) and the official 2022 territorial boundaries. What is in this deposit Files: attribute tables *.csv.gz — basico, alfabetizacao, corraca, demografia, domicilio01–03, domicilioindigena, domicilioquilombola, entornodomicilio, entornoface, entornomorador, obitos, parentesco, pessoaindigena, pessoaquilombola, responsavelrenda. One row per census tract, first column setor_code, then the variables V + number (3,511 variables in total). geospatial layers *.gpkg.gz — setores, subdistritos, distritos, municipios, sedes and bairros. metadata catalogs: IBGE_CENSO-2022_LAYERS_X_X.csv, IBGE_CENSO-2022_FIELDS_X_X.csv, IBGE_CENSO-2022_VARIABLES_X_X.csv — the metadata catalogs (uncompressed, readable on the repository). builder script build_database.py — the script that builds a GeoPackage database from the sources files. database file DATABASE_*.gpkg.zip — database file build from the script. Files are kept separate on purpose, so that new versions of the deposit only replace the files that changed. The .csv.gz files can be read directly by pandas, pyarrow, DuckDB, R and most other tools; the .gpkg.gz files must be decompressed before use in GIS software. Rebuilding the database 1. Download all files into one folder (keep the .gz files as they are; no need to decompress).2. Create and edit build_database_2022.json: set input_folder (the folder above), output_folder and the three catalog paths.3. Run python build_database.py --config build_database_2022.json --overwrite. Requirements: Python 3 (standard library only) and the GDAL command line tool ogr2ogr available in the PATH. The script reads the compressed files directly (geography layers are unpacked temporarily next to the output and removed), builds the database from zero, and writes a log with checks (row counts, column types, sector key cross-check). The header of the script documents every option of the configuration. Layers The GeoPackage has 26 layers, named without census or year (e.g. basico, setores): Geospatial (SIRGAS 2000, EPSG:4674): - setores - census tract polygons. It holds only the key setor_code and the geometry; the tract attributes (names, codes, situation, type, area, totals) live in basico, so nothing is duplicated. - subdistritos, distritos, municipios - the administrative polygons. - sedes - points of the municipal seats (city hall or analogous), linked to municipios by municipio_code. - bairros - neighborhood polygons. Attribute tables: the 17 tables listed above, linked to setores by setor_code. Three structured metadata layers: - layers - Describes all database layers contained in the GeoPackage, including geometry type, spatial reference system, thematic scope, and relational structure where applicable. - fields - Documents major attribute fields and naming conventions, including standardized prefixes, identifier variables, geographic codes, and structural variables used for relational integrity and joins. - variables - Provides a complete listing of the census variables, including official variable names, harmonized names, and their corresponding descriptions (Portuguese and English) as defined in the 2022 census documentation. Together, these metadata layers provide full transparency regarding database structure, schema harmonization, and variable provenance. Conventions - Names follow <entity>_code / <entity>_name (e.g. setor_code, municipio_code, municipio_name, unidade_alias), with no abbreviations such as "cd" or "nm". Variables are named V + number and identified in variables by variable_code (<table>_<variable>, e.g. demografia_V01006).- Identifiers: every column ending in _code is stored as text, so leading zeros and long codes are never altered.- Variables are numeric: integers, except six that actually hold decimals and are stored as real numbers: V0005 and V0006 in basico (average residents per household, share of imputed households) and V06003–V06006 in responsavelrenda (variance and mean of residents, variance, mean and median of income).- Missing and protected values use fixed codes in every table (documented in the fields layer): -9999 no data (empty in the source), -1 hidden for statistical confidentiality (X in the source), -2 uncertain (. in the source). Text fields use NA for no data or not applicable.- In the source, X hides the whole tract in a table for anonymity, so in the affected tracts every variable of that table is -1. Data quality notes - Tables do not cover the same set of tracts: basico has 468,099, most other tables 458,772, and the three entorno tables about 341 to 345 thousand. Join on setor_code and expect unmatched rows.- The setores layer has 472,780 polygons for 468,099 distinct setor_code values: 914 codes appear in several rows (multi-part tracts), so a join with basico is one-to-many for them.- municipios has 5,572 polygons: the 5,570 municipalities plus the two lagoons (Lagoa Mirim and Lagoa dos Patos, codes 4300001 and 4300002), which have no seat in sedes.- area_km2 is the area published by IBGE and includes water bodies inside the tract or municipality.- The aggregated layers distributed by IBGE as copies of the tracts with the indigenous or quilombola data already joined are not included: they duplicate setores plus the corresponding tables.- Descriptions in the variables layer come from the IBGE data dictionaries; the English text was translated for this dataset, and the bracketed descriptions of the entorno tables were rewritten as plain lists. Data sources Instituto Brasileiro de Geografia e Estatística (IBGE). (2022). Censo Demográfico 2022: resultados do universo por setores censitários. https://censo2022.ibge.gov.br/FTP: https://ftp.ibge.gov.br/Censos/Censo_Demografico_2022/ Version log 3.0.0 Inclusion of União and Unidades geography layers. 2.0.0 Improvements in description. 1.0.0 First version of the 2022 census tract dataset. Tables and geospatial layers are distributed as separate compressed files, and users can rebuild the database by running the build_database.py script.