pysungeo 0.1.0

Sub-National Geospatial Data Archive: Geoprocessing Toolkit (Python)

pysungeo

Sub-National Geospatial Data Archive: Geoprocessing Toolkit for Python

pysungeo is a Python port of the SUNGEO R package, providing tools for integrating geospatial datasets that use different geographic boundary systems. It solves the change-of-support problem — transferring data between misaligned spatial units (e.g., electoral precincts to administrative districts to hexagonal grids).

Key Features

• Polygon-to-polygon transfer — Area-weighted interpolation with pycnophylactic (mass-preserving) correction
• Point-to-polygon interpolation — Simple aggregation, Voronoi tessellation, and Ordinary/Universal Kriging
• Line-to-polygon metrics — Road length, density, and distance calculations within polygons
• Nesting diagnostics — 12 metrics measuring how well one boundary set nests within another
• Raster conversion — Polygon/point to raster and back, with round-trip fidelity
• Spatial statistics — Getis-Ord Gi* hot spot analysis
• Geocoding — Address-to-coordinate conversion via OpenStreetMap Nominatim
• SUNGEO API access — Download sub-national data for 180+ countries directly

Installation

pip install pysungeo

From source

git clone https://github.com/zhukov/pysungeo.git
cd pysungeo
pip install -e ".[dev]"

Quick Start

import geopandas as gpd
from sungeo.utm_select import utm_select
from sungeo.poly2poly_ap import poly2poly_ap
from sungeo.hot_spot import hot_spot

# Load source and destination boundary sets
precincts = gpd.read_file("precincts.gpkg")
districts = gpd.read_file("districts.gpkg")

# Transfer turnout data from precincts to districts (area-weighted)
result = poly2poly_ap(
    poly_from=precincts,
    poly_to=districts,
    poly_to_id="DISTRICT_ID",
    varz="turnout",
)

# Identify spatial clusters
hotspots = hot_spot(insert=result, variable="turnout_aw")

Available Functions

Spatial Interpolation

Function	Description
poly2poly_ap	Area-weighted polygon-to-polygon transfer
point2poly_simp	Simple point-in-polygon aggregation
point2poly_tess	Voronoi tessellation interpolation
point2poly_krige	Ordinary and Universal Kriging
line2poly	Line length, density, and distance within polygons

Spatial Analysis

Function	Description
nesting	12 metrics for boundary set compatibility
hot_spot	Getis-Ord Gi* local spatial clustering
sf2raster	Polygon/point ↔ raster conversion

Utilities

Function	Description
utm_select	Auto-select optimal projected CRS
fix_geom	Repair invalid geometries
df2sf	DataFrame with coordinates → GeoDataFrame
update_bbox	Refresh GeoDataFrame bounding box
smart_round	Round with significant digit preservation
make_ticker	Date-to-ID mapping table
merge_list	Recursive outer-join merge

Data Access

Function	Description
get_data	Download from the SUNGEO API
get_info	Browse the SUNGEO data catalog
geocode_osm	Geocode addresses via Nominatim
geocode_osm_batch	Batch geocoding with rate limiting

Examples

Transfer data between boundary sets

from sungeo.poly2poly_ap import poly2poly_ap

# Area-weighted transfer of election turnout from precincts to hex grid
result = poly2poly_ap(
    poly_from=precincts,
    poly_to=hex_grid,
    poly_to_id="HEX_ID",
    varz="turnout",
)

Kriging interpolation from weather stations to districts

from sungeo.point2poly_krige import point2poly_krige

result = point2poly_krige(
    pointz=weather_stations,
    polyz=districts,
    yvarz="temperature",
)
# Result includes temperature.pred, temperature.var, temperature.stdev

Check boundary compatibility

from sungeo.nesting import nesting

metrics = nesting(
    poly_from=precincts,
    poly_to=districts,
    metrix="all",
)
# metrics["rn"] close to 1.0 = good nesting

Download SUNGEO data

from sungeo.get_data import get_data

df = get_data(
    country_names="Germany",
    topics="Demographics:Population:GHS",
    year_min=2000,
    year_max=2020,
)

Requirements

• Python ≥ 3.10
• geopandas ≥ 0.14
• shapely ≥ 2.0
• numpy ≥ 1.24
• pandas ≥ 2.0
• scipy ≥ 1.10
• rasterio ≥ 1.3
• rasterstats ≥ 0.19
• pyproj ≥ 3.5
• pykrige ≥ 1.7
• esda ≥ 2.5
• libpysal ≥ 4.9
• requests ≥ 2.31

Testing

pip install -e ".[dev]"
pytest

533 tests passing, covering all 20 functions with R cross-validation.

Citation

If you use this package in published research, please cite:

Zhukov, Yuri M., Jason S. Byers, Marty Davidson, and Ye Chan Kim. 2025. "pysungeo: Sub-National Geospatial Data Archive — Geoprocessing Toolkit for Python." https://github.com/zhukov/pysungeo

And the original R package:

Zhukov, Yuri M., Jason S. Byers, and Marty Davidson. 2024. "SUNGEO: Sub-National Geospatial Data Archive: Geoprocessing Toolkit." R package. https://github.com/zhukov/SUNGEO

License

GPL-2.0. See LICENSE for details.

Links

• SUNGEO Project
• R Package (original)
• API Documentation