geometrics 0.1.0

Regional growth, convergence, and inequality analysis on the PySAL stack.

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: every function returns a typed result object with .df, .fig, plain-language .interpret(), and concept .explain().

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[all]"          # everything, incl. PNG export

Quickstart: the Indian case study

The bundled case study covers 520 Indian districts observed by satellite nighttime lights (1996-2010), from Mendez, Kabiraj & Li (quarcs-lab/project2025s-py).

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)

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