!pip install -q geo4boliviaThe data model: scales, geo IDs, datasets and metadata
Every function of geo4bolivia rests on a small set of conventions in the data repository. Once you know them, you can predict what any function returns, join any two tables, and read the data without the package at all. Four rules hold everything together:
- Every spatial unit has one geo ID (
geo_id), at every scale, and the IDs nest by prefix. - Every dataset is a long panel: one row per unit and year, one column per variable.
- The metadata are the source of truth: each variable’s label, definition, unit, source and aggregation rule are written once, and everything else reads them.
- Nothing published is edited by hand: the files are generated from the original inputs and checked by a validator.
import geo4bolivia as geo1. Scales
A scale is a set of units that covers the country: departments, provinces, municipalities, and later grid cells. The scales are listed in a registry, which geo.scales() returns as a table.
geo.scales()| label | kind | parent | children | id_pattern | example | status | |
|---|---|---|---|---|---|---|---|
| scale | |||||||
| country | Country | admin | None | None | ^BO$ | BO | active |
| department | Department | admin | country | None | ^BO-\d{2}$ | BO-04 | active |
| province | Province | admin | department | None | ^BO-\d{2}-\d{2}$ | BO-04-17 | active |
| municipality | Municipality (343) | admin | province | None | ^BO-\d{2}-\d{2}-\d{2}$ | BO-04-17-04 | active |
| municipality_ine | Municipality (current INE map) | custom | None | None | ^BO-INE-\d{6}$ | BO-INE-020101 | planned |
| grid10k | 10 km grid cell | grid | None | None | ^BO-G10K-r\d{3}c\d{3}$ | BO-G10K-r012c034 | planned |
| Column | Meaning |
|---|---|
kind |
admin: administrative units that nest by ID prefix. grouping: unions of whole units of another scale. grid: regular cells. custom: any other zones |
parent |
The next coarser scale every unit lies in exactly. It defines the hierarchy geo.aggregate() climbs |
id_pattern |
A regular expression every ID of the scale matches. The patterns do not overlap, so an ID tells its scale |
status |
active: published. planned: the scale and its ID scheme are reserved, with no data yet |
Four scales are active: 1 country, 9 departments, 113 provinces and 343 municipalities. Two helper functions answer the usual questions about the hierarchy: what a scale nests in, and what scale an ID belongs to.
print(geo.ancestors("municipality"))
print(geo.scale_of("BO-04-17"), "|", geo.scale_of("BO-04-17-04"))['province', 'department', 'country']
province | municipality
2. Geo IDs
A geo ID is the country code followed by one two-digit number per administrative level. Each ID contains the IDs of the units it lies in:
| Scale | Pattern | Example |
|---|---|---|
country |
BO |
BO (Bolivia) |
department |
BO-NN |
BO-04 (La Paz) |
province |
BO-NN-NN |
BO-04-17 (Murillo) |
municipality |
BO-NN-NN-NN |
BO-04-17-04 (Nuestra Señora de La Paz) |
geo.units() lists the units of a scale. Each row carries the ID of every coarser unit it lies in (province_id, department_id, country_id), so a join across scales never needs string surgery:
units = geo.units("municipality")
units[units["geo_id"] == "BO-04-17-04"].T| 161 | |
|---|---|
| geo_id | BO-04-17-04 |
| scale | municipality |
| name | Nuestra Señora de La Paz |
| parent_id | BO-04-17 |
| country_id | BO |
| department_id | BO-04 |
| province_id | BO-04-17 |
| municipality_id | BO-04-17-04 |
| gid | BOL.4.17.4_2 |
| ine_code | 020101 |
| asdf_id | 176 |
| mun_id | 20101 |
| name_ds4bolivia | La Paz |
| name_gadm | NuestraSeñoradeLaPaz |
| area_km2 | 2042.28 |
The same row shows the source keys: the codes other sources use for this unit. They are kept as columns and never used as the identifier.
| Column | Code of |
|---|---|
ine_code |
Bolivia’s National Statistics Institute (INE), as text with leading zeros (020101) |
mun_id |
the same INE code as a number (20101), as many tables store it |
gid |
GADM 4.1 (BOL.4.17.4_2) |
asdf_id |
the polygon of the DS4Bolivia repository on which pop, ntl and the embeddings were computed; empty for the 10 units whose territory changed (section 4) |
name_ds4bolivia, name_gadm |
older spellings of the name |
The numbers in a geo ID follow the order of GADM, a global database of administrative areas. INE orders the departments differently, so the two codes of a unit do not match:
geo.units("department")[["geo_id", "name", "ine_code", "gid"]]| geo_id | name | ine_code | gid | |
|---|---|---|---|---|
| 0 | BO-01 | Chuquisaca | 01 | BOL.1_1 |
| 1 | BO-02 | Cochabamba | 03 | BOL.2_1 |
| 2 | BO-03 | Beni | 08 | BOL.3_1 |
| 3 | BO-04 | La Paz | 02 | BOL.4_1 |
| 4 | BO-05 | Oruro | 04 | BOL.5_1 |
| 5 | BO-06 | Pando | 09 | BOL.6_1 |
| 6 | BO-07 | Potosí | 05 | BOL.7_1 |
| 7 | BO-08 | Santa Cruz | 07 | BOL.8_1 |
| 8 | BO-09 | Tarija | 06 | BOL.9_1 |
La Paz is BO-04 here and 02 for INE; the province Murillo is BO-04-17 here and 0201 for INE. The numbers are not always consecutive either: the provinces of La Paz run from BO-04-02 to BO-04-21, because GADM skips number 1. Treat a geo ID as a label that nests, and take the official codes from ine_code.
Why not use names? Because they repeat:
repeated = units[units.duplicated("name", keep=False)]
repeated.groupby("name")["department_id"].agg(list)name
El Puente [BO-08, BO-09]
Entre Ríos [BO-02, BO-09]
San Javier [BO-03, BO-08]
San Lorenzo [BO-06, BO-09]
San Pedro [BO-06, BO-07, BO-08]
San Ramón [BO-03, BO-08]
Santa Rosa [BO-03, BO-06]
Totora [BO-02, BO-05]
Name: department_id, dtype: object
Eight municipality names belong to two or three municipalities in different departments, and four provinces are called Cercado. To attach a table of your own to the geo IDs, match on a code; Building your own indicators shows how geo.link() does it.
3. Units, boundaries and crosswalks
The geography is three kinds of table, all keyed by geo_id.
Units. Without an argument, geo.units() returns every unit of every scale: 466 rows.
geo.units().groupby("scale").size()scale
country 1
department 9
municipality 343
province 113
dtype: int64
Boundaries. geo.boundaries() returns the polygons of a scale as a GeoDataFrame (a table with a geometry column, from the geopandas library), in longitude and latitude (WGS 84):
departments = geo.boundaries("department")
print(type(departments).__name__, "|", departments.crs.name)
print(list(departments.columns))GeoDataFrame | WGS 84
['geo_id', 'name', 'geometry']
Crosswalks. geo.crosswalk() links the units of a finer scale to those of a coarser one. weight_area is the share of the finer unit’s area that lies in the coarser unit; it is 1 for scales that nest.
geo.crosswalk("municipality", "department").head(3)| geo_id_from | geo_id_to | weight_area | |
|---|---|---|---|
| 0 | BO-01-01-01 | BO-01 | 1.0 |
| 1 | BO-01-01-02 | BO-01 | 1.0 |
| 2 | BO-01-02-01 | BO-01 | 1.0 |
The 343-unit map
The boundaries are SDSN Bolivia’s municipal map of 2025: 343 municipalities and indigenous autonomies, the units of the SDG Atlas 2026. They are lightly simplified (about 100 m), and provinces, departments and the country are exact unions of the municipalities, so the scales nest without gaps or overlaps. The map states no open license and is used and shared with SDSN Bolivia’s permission; credit it as SDSN Bolivia (2025). Límites Municipales Bolivia 2025 [Archivo shapefile]. https://sdsnbolivia.org/datos-espaciales/.
Municipalities are created over time, and the IDs are built to survive that. The previous map, of 2015, had 339 municipalities. All 339 kept their geo IDs in the 2025 map, and the four units created since were numbered after the last municipality of their province (one of them, TIOC-Territorio Indígena Multiétnico, is alone in a new province, BO-03-09). An ID therefore never changes meaning. What did change is the territory of the six municipalities that gave land to the new units. These ten units are the ones without an asdf_id:
changed = units[units["asdf_id"].isna()]
changed[["geo_id", "name", "ine_code", "area_km2"]]| geo_id | name | ine_code | area_km2 | |
|---|---|---|---|---|
| 61 | BO-02-12-02 | Mizque | 031301 | 1316.19 |
| 63 | BO-02-12-04 | TIOC-Raqaypampa | 031304 | 568.33 |
| 91 | BO-03-06-01 | San Ignacio | 080501 | 21195.80 |
| 95 | BO-03-08-02 | Santa Ana | 080401 | 18754.08 |
| 96 | BO-03-09-01 | TIOC-Territorio Indígena Multiétnico | 080901 | 6474.63 |
| 236 | BO-07-02-01 | Porco | 051203 | 1007.07 |
| 237 | BO-07-02-02 | Tomave | 051202 | 6110.22 |
| 239 | BO-07-02-04 | TIOC-Jatun Ayllu Yura | 051204 | 2128.33 |
| 242 | BO-07-04-01 | Colquechaca | 050401 | 673.34 |
| 246 | BO-07-04-05 | San Pedro de Macha | 050405 | 1071.33 |
Holes in the map
The map leaves the salt flats of Uyuni and Coipasa and lakes Poopó and Uru Uru outside every municipality. They are therefore holes at every scale, and area_km2 does not count them. A map of the municipal areas shows them as gaps in the south-west:
geo.map(units, "area_km2", scheme="quantiles",
title="Area of the municipalities (km²)")The areas of the 343 municipalities add up to the area of the country unit, which confirms that the scales nest exactly:
print(round(units["area_km2"].sum()), round(geo.units("country")["area_km2"].sum()))1068783 1068783
4. Datasets are panels
A dataset is a set of variables from one source. geo.datasets() is the catalog:
geo.datasets()[["dataset", "scale", "title", "years", "units", "variables"]]| dataset | scale | title | years | units | variables | |
|---|---|---|---|---|---|---|
| 0 | pop | municipality | Population | 2001–2020 | 333 | 2 |
| 1 | ntl | municipality | Night-time lights per capita | 2012–2020 | 333 | 2 |
| 2 | sdg | municipality | Sustainable Development Index, IDS (SDG Atlas ... | 2012, 2024 | 343 | 4 |
| 3 | sdg01 | municipality | SDG 1: No poverty (SDG Atlas of Bolivia 2026) | 2012, 2024 | 343 | 5 |
| 4 | sdg02 | municipality | SDG 2: Zero hunger (SDG Atlas of Bolivia 2026) | 2012, 2024 | 343 | 8 |
| 5 | sdg03 | municipality | SDG 3: Good health and well-being (SDG Atlas o... | 2012, 2024 | 343 | 8 |
| 6 | sdg04 | municipality | SDG 4: Quality education (SDG Atlas of Bolivia... | 2012, 2024 | 343 | 12 |
| 7 | sdg05 | municipality | SDG 5: Gender equality (SDG Atlas of Bolivia 2... | 2012, 2024 | 343 | 7 |
| 8 | sdg06 | municipality | SDG 6: Clean water and sanitation (SDG Atlas o... | 2012, 2024 | 343 | 4 |
| 9 | sdg07 | municipality | SDG 7: Affordable and clean energy (SDG Atlas ... | 2012, 2024 | 343 | 5 |
| 10 | sdg08 | municipality | SDG 8: Decent work and economic growth (SDG At... | 2012, 2024 | 343 | 8 |
| 11 | sdg09 | municipality | SDG 9: Industry, innovation and infrastructure... | 2012, 2024 | 343 | 5 |
| 12 | sdg10 | municipality | SDG 10: Reduced inequalities (SDG Atlas of Bol... | 2012, 2024 | 343 | 7 |
| 13 | sdg11 | municipality | SDG 11: Sustainable cities and communities (SD... | 2012, 2024 | 343 | 8 |
| 14 | sdg13 | municipality | SDG 13: Climate action (SDG Atlas of Bolivia 2... | 2012, 2024 | 343 | 6 |
| 15 | sdg15 | municipality | SDG 15: Life on land (SDG Atlas of Bolivia 2026) | 2012, 2024 | 343 | 5 |
| 16 | sdg16 | municipality | SDG 16: Peace, justice and strong institutions... | 2012, 2024 | 343 | 5 |
| 17 | sdg17 | municipality | SDG 17: Partnerships for the goals (SDG Atlas ... | 2012, 2024 | 343 | 3 |
| 18 | emb | municipality | Satellite embeddings 2017 (area-weighted) | 2017 | 333 | 64 |
| 19 | embpw | municipality | Satellite embeddings 2017 (population-weighted) | 2017 | 333 | 64 |
geo.load() returns a dataset as a long panel: one row per unit (geo_id) and year, one column per variable. Every dataset has this shape, which is what lets the same functions work on all of them.
geo.load("sdg").head(4)| geo_id | year | mun_id | index_sdg | rank_sdg | population | urbanization | |
|---|---|---|---|---|---|---|---|
| 0 | BO-01-01-01 | 2012 | 10201 | 40.8 | 332 | 10652 | NaN |
| 1 | BO-01-01-01 | 2024 | 10201 | 54.5 | 297 | 7903 | 0.0 |
| 2 | BO-01-01-02 | 2012 | 10202 | 44.5 | 287 | 14261 | NaN |
| 3 | BO-01-01-02 | 2024 | 10202 | 53.9 | 306 | 16812 | 0.0 |
The arguments of load select and decorate the panel; they do not change its shape, with two exceptions noted below.
| Argument | Effect |
|---|---|
years= |
one year (2024), a list ([2012, 2024]) or an inclusive range as a tuple ((2015, 2020)) |
variables= |
one variable or a list; geo_id and year are always kept |
names=True |
adds the unit’s name |
groups=[...] |
adds the names of the coarser units each unit lies in, e.g. a department column |
wide= |
changes the shape: one row per unit, one column per year of the variable given |
geometry=True |
changes the type: a GeoDataFrame with the boundaries attached |
geo.load("sdg", variables="index_sdg", years=2024,
groups=["province", "department"]).head(3)| geo_id | name | year | province | department | index_sdg | |
|---|---|---|---|---|---|---|
| 0 | BO-01-01-01 | Azurduy | 2024 | Azurduy | Chuquisaca | 54.5 |
| 1 | BO-01-01-02 | Tarvita | 2024 | Azurduy | Chuquisaca | 53.9 |
| 2 | BO-01-02-01 | Villa Serrano | 2024 | Belisario Boeto | Chuquisaca | 63.9 |
geo.load("pop", wide="pop").iloc[:3, :5]| geo_id | pop2001 | pop2002 | pop2003 | pop2004 | |
|---|---|---|---|---|---|
| 0 | BO-01-01-01 | 11718.431 | 11621.795 | 11556.641 | 11482.748 |
| 1 | BO-01-01-02 | 15737.872 | 15611.149 | 15519.731 | 15289.985 |
| 2 | BO-01-02-01 | 12278.948 | 12186.130 | 12079.739 | 11962.021 |
gdf = geo.load("ntl", years=2020, geometry=True)
print(type(gdf).__name__, gdf.shape)GeoDataFrame (333, 7)
A year or a variable that does not exist raises an error that says what the dataset has:
try:
geo.load("sdg", years=2015)
except ValueError as error:
print(error)'sdg' has no rows for 2015; its years are 2012, 2024
Two features of the catalog above need explaining.
Two periods stored as 2012 and 2024. The SDG Atlas measures each indicator twice, near the census of 2012 and near the census of 2024, from sources of different years. Its datasets (sdg and one per goal, sdg01 to sdg17, with none for goals 12 and 14) store the two periods at the nominal years 2012 and 2024, so that every variable can be compared between them. The actual years are in the metadata (next section).
333 units instead of 343. pop, ntl, emb and embpw were computed on the polygons of the 2015 map. Their values are valid for the 333 municipalities whose territory has not changed, and they have no rows for the ten units listed in section 3. The analysis functions work on the units with data: a spatial function, for example, builds the neighbour relations among them and reports their number in the result’s w_spec.
5. The metadata
Each dataset comes with a metadata file, a Frictionless Data Package, that describes the dataset and every one of its columns. The package reads it whenever it needs to know something about a variable. You read it through five functions.
geo.dictionary() is the variable dictionary:
cols = ["variable", "label", "unit", "role", "aggregation", "reference_years"]
geo.dictionary("sdg")[cols]| variable | label | unit | role | aggregation | reference_years | |
|---|---|---|---|---|---|---|
| 0 | geo_id | Municipality ID | id | |||
| 1 | year | Period | time | |||
| 2 | mun_id | INE municipality code | source_key | |||
| 3 | index_sdg | Sustainable Development Index, IDS (0-100) | index (0-100) | variable | weighted_mean:population | 2012: ~2012; 2024: ~2024 |
| 4 | rank_sdg | IDS national ranking (1 = best) | rank | variable | none | 2012: ~2012; 2024: ~2024 |
| 5 | population | Population (census) | people | variable | sum | 2012: 2012; 2024: 2024 |
| 6 | urbanization | Urbanization rate (% of population) | % of population | variable | weighted_mean:population | 2024: 2024 |
| Column | Meaning |
|---|---|
label |
a readable name, used on axes, legends and tables |
description |
how the variable was built (not shown above: it is long) |
unit |
the unit of measure |
role |
id, time, source_key (a code kept from the source) or variable |
aggregation |
how the variable moves to coarser scales |
reference_years |
the actual years behind each stored year, when they differ |
Aggregation rules. A population can be summed over the municipalities of a department; a rate cannot. The rule of each variable tells geo.aggregate() and geo.combine() what to do:
| Rule | For | Examples |
|---|---|---|
sum |
counts and totals | population, pop |
weighted_mean:<field> |
rates and averages, weighted by another variable | every SDG indicator and index, weighted by census population |
mean, min, max |
unweighted summaries | to be used with care |
none |
values that cannot be aggregated without more data | logarithms (ln_NTLpc), rankings (rank_sdg), densities |
The SDG indicators are weighted by the census population of the same period, which the package loads from the dataset sdg by itself. The department values it produces approximate, but are not, the Atlas’s own department figures.
Reference years. geo.reference_years() gives the actual years behind each stored year. In the hunger goal, for example, the nutrition indicators come from the health surveys of 2008 and 2023, and the agricultural ones are three-year averages:
geo.reference_years("sdg02").drop_duplicates("reference")| variable | label | year | reference | |
|---|---|---|---|---|
| 0 | index_sdg2 | Zero hunger index (0-100) | 2012 | ~2012 |
| 1 | index_sdg2 | Zero hunger index (0-100) | 2024 | ~2024 |
| 2 | sdg2_2_smu | Obesity in women 15-49 (%) | 2012 | 2008 |
| 3 | sdg2_2_smu | Obesity in women 15-49 (%) | 2024 | 2023 |
| 10 | sdg2_3_pac | Agricultural production (t per person per year) | 2012 | average 2013–2015 |
| 11 | sdg2_3_pac | Agricultural production (t per person per year) | 2024 | average 2022–2024 |
Labels. geo.labels() returns the labels as a dictionary, for the labels= argument of Plotly Express. The package’s own figures use them without being asked.
geo.labels("ntl"){'geo_id': 'Municipality ID',
'year': 'Year',
'asdf_id': 'DS4Bolivia polygon ID',
'ln_NTLpc': 'Log night-time lights per capita',
'ln_t400NTLpc': 'Log night-time lights per capita (trend)'}
Documentation and licenses. geo.info() gathers what a dataset is: description, coverage, actual years, the license of the published files, the sources with their own licenses, the citation and notes on its use.
print(geo.info("ntl"))Night-time lights per capita [ntl]
Annual night-time lights per capita for 333 of Bolivia's 343 municipalities, 2012–2020, in
natural logs: the total VIIRS Day/Night Band radiance of each municipality divided by its
population. A Hodrick–Prescott trend (λ = 400) of the same series isolates its long-run path.
Night-time lights are a widely used proxy for local economic activity and electrification.
Coverage
- 333 municipality units, 2012–2020, 2 variables
License of the published files
- Creative Commons Attribution 4.0 International License
Sources
- Elvidge, C. D., Zhizhin, M., Ghosh, T., Hsu, F.-C., & Taneja, J. (2021). Annual time series
of global VIIRS nighttime lights derived from monthly averages: 2012 to 2019. Remote Sensing,
13(5), 922.
License: Creative Commons Attribution 4.0 International License
- WorldPop & CIESIN (2018). Global High Resolution Population Denominators Project (1 km
aggregated, 2000–2020). University of Southampton and Columbia University. Funded by the Bill
and Melinda Gates Foundation (OPP1134076).
License: Creative Commons Attribution 4.0 International License
- Goodman, S., BenYishay, A., Lv, Z., & Runfola, D. (2019). GeoQuery: Integrating HPC systems
and public web-based geospatial data tools. Computers & Geosciences, 122, 103–112.
License: Open Data Commons Attribution License 1.0
- Runfola, D., Anderson, A., Baier, H., et al. (2020). geoBoundaries: A global database of
political administrative boundaries. PLoS ONE, 15(4), e0231866.
License: Creative Commons Attribution 4.0 International License
- Mendez, C., Gonzales, E., Leoni, P., Andersen, L., & Peralta, H. (2026). DS4Bolivia: A Data
Science Repository to Study GeoSpatial Development in Bolivia [Data set]. GitHub.
License: MIT License
Cite as (geo.cite)
GeoDevelopment Observatory of Bolivia (2026). Night-time lights per capita (333 of 343
municipalities, 2012–2020). https://github.com/quarcs-
lab/gdo4bolivia/blob/main/docs/datasets/ntl.md
Notes
- The values belong to DS4Bolivia's polygons of the 2015 map, so they are published for the
333 municipalities whose territory is unchanged in the 343-unit map of 2025. The six
municipalities that lost territory to the units created since (Colquechaca, Mizque, Porco,
Tomave, San Ignacio and Santa Ana) and the four new units (San Pedro de Macha, TIOC-
Raqaypampa, TIOC-Jatun Ayllu Yura and TIOC-Territorio Indígena Multiétnico) have no rows.
- Both variables are logs of a ratio, so they cannot be summed or averaged up the hierarchy;
their aggregation rule is `none`. Aggregate the levels instead, e.g. NTL = exp(ln_NTLpc) ×
pop, summed with `pop` from the population dataset.
- Computed by DS4Bolivia on its own municipal polygons (`asdf_id`), geoBoundaries v4 polygons
that differ slightly from the SDSN Bolivia 2025 boundaries in geo/boundaries/.
- Population is the gridded estimate of the `pop` dataset.
Notebooks
- Find, load and understand Bolivia's subnational data with geo4bolivia
- Exploratory data analysis of multidimensional poverty
- Spatial inequality of poverty and night-time lights
- Where do lights predict poverty? GWR and MGWR
- Poverty in Bolivia: an extended EDA and ESDA
- Predicting poverty from satellite embeddings
Documentation: https://github.com/quarcs-lab/gdo4bolivia/blob/main/docs/datasets/ntl.md
Two levels of license appear. The published files are under CC BY 4.0. Each source keeps its own terms: the SDG Atlas 2026 states no open license and is used and shared with SDSN Bolivia’s permission, as geo.info("sdg") reports.
Citation. geo.cite() returns the dataset’s citation, in APA style or BibTeX, followed by the credits its sources ask for:
print(geo.cite("sdg"))GeoDevelopment Observatory of Bolivia (2026). Sustainable Development Index (IDS), from the Atlas de los ODS en Bolivia 2026 (343 municipalities, ~2012 and ~2024). https://github.com/quarcs-lab/gdo4bolivia/blob/main/docs/datasets/sdg.md
Please also credit the original sources:
- Please cite the Atlas and its data as: Andersen, L.E. & Argandoña, F. (2026). Atlas de los ODS en Bolivia 2026: Brechas y tendencias del desarrollo sostenible en las Entidades Territoriales Autónomas, 2012–2024. La Paz: Universidad Privada Boliviana, SDSN Bolivia.
- SDSN Bolivia (2025). Límites Municipales Bolivia 2025 [Archivo shapefile]. https://sdsnbolivia.org/datos-espaciales/
6. Where the data are read from
The package does not carry the data. It reads the files of the data repository when you ask for them:
| Where you run it | What it reads |
|---|---|
| Anywhere (Google Colab, an installed package) | the files on GitHub, from the branch main; each file is downloaded once per session |
With ref="..." in any function that reads data |
the same files at a git tag or commit, which freezes the data for a reproducible analysis |
With the environment variable GEO4BOLIVIA_REF |
that tag or commit, as the default for every call |
Inside a clone of the data repository, or with GEO4BOLIVIA_DATA_DIR pointing to one |
the local files, with no download |
geo.load("ntl") # the current data (branch main)
geo.load("ntl", ref="v0.5.0") # the data as they were at a release taggeo.config() shows the settings in use, among them the repository and the default branch:
config = geo.config()
print(config["repository"], "|", config["default_ref"])quarcs-lab/gdo4bolivia | main
Without the package
Because the data are plain files with stable paths, any tool can read them. There are three kinds of file:
| Path | Contents |
|---|---|
data/<scale>/<dataset>.csv and .parquet |
the panel of a dataset |
geo/units.csv, geo/boundaries/<scale>.geojson, geo/crosswalks/<from>__<to>.csv |
the geography |
metadata/<dataset>.datapackage.json |
the metadata |
The two ways of loading the same panel, side by side:
!pip install -q geo4bolivia
import geo4bolivia as geo
ntl = geo.load("ntl", groups=["department"]) # panel + names
gdf = geo.load("ntl", years=2020, geometry=True) # + boundariesimport pandas as pd
import geopandas as gpd
BASE = "https://raw.githubusercontent.com/quarcs-lab/gdo4bolivia/main/"
ntl = pd.read_csv(BASE + "data/municipality/ntl.csv") # geo_id, year, variables
units = pd.read_csv(BASE + "geo/units.csv", dtype={"ine_code": str})
ntl = ntl.merge(units[["geo_id", "name", "department_id"]], on="geo_id")
shapes = gpd.read_file(BASE + "geo/boundaries/municipality.geojson")
gdf = shapes.merge(ntl[ntl["year"] == 2020], on="geo_id")Replace main in the URL with a release tag for a frozen version. What the package adds to the plain files is the metadata at hand (labels, rules, reference years, citations), the joins done for you, and the analyses.
In short
- A geo ID identifies each unit and nests by prefix (
BO-04-17-04lies inBO-04-17, inBO-04, inBO). It follows GADM’s numbering, not INE’s; the INE codes are columns ofgeo.units(). - Four scales are active (country, department, province, municipality);
geo.scales(),geo.ancestors()andgeo.scale_of()describe the hierarchy. - The boundaries are SDSN Bolivia’s map of 2025 with 343 units. Salt flats and lakes are holes in it. Datasets computed on the 2015 map cover 333 units.
- Every dataset is a panel with one row per
geo_idandyear. The SDG datasets store two periods at the nominal years 2012 and 2024. - The metadata give each variable its label, unit, aggregation rule and reference years, and each dataset its sources, licenses and citation:
geo.dictionary(),geo.reference_years(),geo.labels(),geo.info(),geo.cite(). - The data are read from GitHub by default, from a tag with
ref=, from a local clone, or with plain URLs and no package.
Where next
- Exploring the data: these conventions at work on multidimensional poverty, with the pitfalls they explain.
- Building your own indicators: bring a table or a raster of your own onto the geo IDs, and move data across scales.
- Get started: from finding a variable to a first spatial result.
- Function reference: every option of the functions used here.