PGMST

Physics-informed Graph embedding + Multi-objective ST (MST-based) regionalization.

Two-stage API:

1. pgmst.pgnn.PGNN — packaged SGCN pipeline (half-life OD weights + spatial glue on contiguity edges). embed() appends Emb_X / Emb_Y to your zone table.
2. pgmst.mst.MST — build an MST on the spatial adjacency graph with edge costs from embedding distance, then modularity- and constraint-driven partitioning (population / hospital / custom caps, minimum localization index).

Optional: GCN-style embedding via pgmst.physics_graph + PyTorch Geometric (see example notebook).

Install

pip install pgmst

For a development editable install from a clone:

pip install -e ".[dev]"

Quick start

from pgmst import PGNN, MST

coords_emb = PGNN(
    coords_df,
    df_flow,
    id_column="ZoneID",
    w=df_adj,
    k_hops=5,
    w_adj_percentile=75.0,
    coordxy="XCoord,YCoord",
).embed()

pr = MST(
    coords_emb,
    df_flow,
    id_column="ZoneID",
    emb=("Emb_X", "Emb_Y"),
    w=df_adj,
    constraints=[("POPU", "min", 10_000), ("POPU", "max", 500_000), ("hosp", "min", 1)],
    min_local_index=0.3,
).partition()

print(pr.modularity)
print(pr.cluster.head())

Example notebook

After installation, the Florida demo notebook is shipped inside the package:

• pgmst/examples/PGMST_Florida_demo.ipynb

You can copy it to your working directory or open it from site-packages/pgmst/examples/.
The notebook expects OD/adjacency/shapefile paths: point REPO at a checkout of GNNGeoCommunity (or your own data) where data/OD_All_Flows30K.csv, data/FLAdjUpdate.csv, and data/Florida_2011.zip live.

PyPI release

See docs/PYPI.md for local builds (python -m build / twine) and GitHub Actions publishing (Trusted Publisher on PyPI).

Requirements

Python 3.10+, PyTorch, PyTorch Geometric, GeoPandas, NetworkX, SciPy, pandas, NumPy. Queen/Rook contiguity needs libpysal.

License

MIT — see LICENSE.