geometrics

geometrics studies regional growth, convergence, and inequality with explicit spatial methods. It builds on the excellent PySAL family — libpysal, esda, giddy, inequality, mapclassify, spreg, and mgwr — and wraps the standard analyses of the regional convergence literature into illustrative, easy-to-apply functions that return interactive Plotly figures, Great Tables, and tidy DataFrames.

It follows the design language of expdpy and is presented in three modules, each with its own pedagogical walkthrough and Colab notebook:

Module	What it does	Docs	App	Colab
🗺️ Explore	Choropleths, weights, Moran/LISA, space-time views	Explore	explore app	explore.ipynb
🧮 Analyze	β/σ/club convergence, spatial models with impacts, Markov, inequality, GWR	Analyze	analyze app	analyze.ipynb
📚 Learn	11 learn_* concept sandboxes + a 30-topic explainer index; .interpret() / .explain() on every result	Learn	learn app	learn.ipynb

The data model: three inputs

Input	What it is	How it enters
gdf	Geometry with only the entity ID — shapefile, zipped shapefile, GeoJSON, or GeoPackage (or a GeoDataFrame)	gm.read_gdf("districts.gpkg", entity="district_id")
df	A long-form panel — one row per (entity, time)	gm.set_panel(df, entity="district_id", time="year")
df_dict	A data dictionary — var_name, var_def, label, type, role, can_be_na	gm.set_labels(df, df_dict, set_panel=True)

Installation

pip install geometrics                 # core
pip install "geometrics[dynamics]"     # + Markov / spatial Markov (giddy)
pip install "geometrics[streamlit]"    # + the three no-code apps
pip install "geometrics[all]"          # everything, incl. PNG export

Run the apps locally with streamlit run app_explore.py (or app_analyze.py / app_learn.py), or from Python with geometrics.streamlit_app.ExploreApp().

Bundled case studies

• India — 520 districts observed by satellite nighttime lights (1996-2010), from Mendez, Kabiraj & Li (quarcs-lab/project2025s-py): gm.data.load_india(), load_india_states()
• Bolivia — PWT-anchored local GDP (2021 PPP US$, 2012-2022) at three scales, derived from Rossi-Hansberg & Zhang (2026) and Penn World Table 11.0: gm.data.load_bolivia() (112 provinces), load_bolivia_departments() (9 departments), load_bolivia_grid() (1,603 cells) — see datasets/ for the citation-grade documentation

At a glance: the Indian case study

import geometrics as gm

gdf, df, df_dict = gm.data.load_india()      # ID-only geometry, long panel, dictionary
df = gm.set_labels(df, df_dict, set_panel=True)

gm.explore_choropleth_map(df, "ntl_total", gdf=gdf, period=2010).fig
w = gm.make_weights(gdf, method="knn", k=6)
gm.explore_lisa_cluster_map(df, "log_ntl_pc_1996", gdf=gdf, w=w).fig

res = gm.analyze_beta_convergence(
    df, "ntl_total", model="sdm", gdf=gdf, w=w
)
print(res.interpret())                       # plain-language reading
res.fig                                      # convergence scatter

Features

• Maps & ESDA — classified/animated choropleths (explore_choropleth_map), weights connectivity (explore_connectivity_map), Moran scatterplots, LISA cluster maps, Moran over time
• Space-time dynamics — cross-sectional distribution evolution (explore_distribution_over_time), entity-by-time heatmaps
• Convergence — β-convergence with OLS or spatial (SAR/SEM/SLX/SDM) estimators and LeSage-Pace impact decomposition, σ-convergence, Phillips-Sul convergence clubs with club maps
• Spatial econometrics — the spreg suite (analyze_spatial_model), LM diagnostics with a model recommendation (analyze_spatial_diagnostics), alternative-weights robustness (analyze_spatial_model_by_weights)
• Distribution dynamics — Markov and spatial Markov transition analysis (analyze_markov_transitions, analyze_spatial_markov)
• Inequality — Gini/Theil trends with spatial decomposition (analyze_inequality_over_time), Theil between/within decomposition (analyze_theil_decomposition)
• Local models — GWR and multiscale GWR with mapped local coefficients (analyze_gwr, analyze_mgwr)
• Concept sandboxes — 11 learn_* teaching functions that simulate data from a known DGP so you can watch each estimator recover a planted parameter (learn_spatial_autocorrelation, learn_spatial_spillovers, learn_beta_convergence, ...)

Documentation

• Website: https://quarcs-lab.github.io/geometrics/
• The India case study article and Colab notebooks: see docs/ and notebooks/

Development

git clone https://github.com/quarcs-lab/geometrics
cd geometrics
uv sync --locked --all-extras --group dev --group docs
make test && make lint && make typecheck

Citation

If you use geometrics in your research, please cite the repository (see CITATION.cff) and the underlying PySAL packages.

Acknowledgments

Developed at the QuaRCS Lab (Quantitative Regional and Computational Science). geometrics stands on the shoulders of the PySAL project, geopandas, Plotly, and Great Tables.

License

MIT