GNNWR - Geographically Neural Network Weighted Regression
Quick Reference
from gnnwr import models, datasets, utils
import pandas as pd
data = pd.read_csv("data.csv")
train, val, test = datasets.init_dataset(
data=data, test_ratio=0.2, valid_ratio=0.1,
x_column=["x1", "x2", "x3"], y_column=["y"],
spatial_column=["lon", "lat"], # REQUIRED: geographic coords
batch_size=32, process_fn="minmax_scale"
)
model = models.GNNWR(train, val, test, use_gpu=True, optimizer="Adam", start_lr=0.01)
model.run(max_epoch=200, early_stop=30)
result = model.reg_result(only_return=True) # DataFrame: coef_x1, coef_x2, ..., Pred_y
print(model.result()) # R², AIC, RMSE, F-tests summary
Spatiotemporal (GTNNWR)
train, val, test = datasets.init_dataset(
data=data, ...,
spatial_column=["lon", "lat"],
temp_column=["year", "month"], # add temporal coords
use_model="gtnnwr"
)
model = models.GTNNWR(train, val, test, use_gpu=True)
Large-Scale (N > 10k) — KNN Mode
train, val, test = datasets.init_dataset(
data=data, ..., knn_k=500 # only k nearest neighbor distances
)
# Memory: N=100k full=55GB → knn_k=2000 only 763MB
Key Classes
| Class |
Purpose |
models.GNNWR |
Spatial regression with neural network geographic weighting |
models.GTNNWR |
Spatiotemporal regression with temporal + spatial weighting |
datasets.init_dataset |
Data splitting, normalization, distance matrix construction |
utils.Visualize |
Built-in folium interactive maps for coefficients and predictions |
Essential Operations
init_dataset Parameters
| Parameter |
Default |
Notes |
knn_k |
None |
KNN sparse distance; None=full matrix |
process_fn |
"minmax_scale" |
or "standard_scale" |
spatial_fun |
BasicDistance |
Euclidean; or ManhattanDistance |
Reference |
None |
"train", "train_val", or custom DataFrame |
sample_seed |
42 |
Reproducibility |
Model Hyperparameters
| Parameter |
Recommended |
Notes |
optimizer |
"Adam" |
Also: SGD, AdamW, Adagrad, RMSprop |
start_lr |
0.01–0.1 |
Critical tuning point |
drop_out |
0.2 |
0.0–0.5 |
dense_layers |
None (auto) |
Auto: power-of-2 sequence from input_dim to n_coef |
early_stop |
20–50 |
Patience; -1=disabled |
batch_norm |
True |
Stabilizes training |
use_ols |
True |
OLS-initialized output layer |
Diagnostics
diag = model._test_diagnosis
diag.R2() # always available
diag.RMSE() # always available
diag.AIC() # needs lite=False (auto for N<10k)
diag.AICc() # corrected AIC
diag.F1_Global() # GNNWR vs OLS significance
diag.F2_Global() # spatial weight significance
diag.F3_Local() # per-variable significance → (dict1, dict2)
lite=True (auto when N>10k): only R²/RMSE; Hat-matrix diagnostics skipped.
Visualization Patterns
Folium Interactive Maps (built-in)
viz = utils.Visualize(model, lon_lat_columns=["lon", "lat"], zoom=5)
m1 = viz.display_dataset(name="all", y_column="y")
m1.save("dataset_map.html")
for col in [c for c in result.columns if c.startswith("coef_")]:
m = viz.coefs_heatmap(data_column=col, steps=20)
m.save(f"map_{col}.html")
Matplotlib Static Maps (publication-ready)
import matplotlib.pyplot as plt
fig, axes = plt.subplots(2, 3, figsize=(18, 12))
coef_cols = [c for c in result.columns if c.startswith("coef_")]
for ax, col in zip(axes.flat, coef_cols):
sc = ax.scatter(
result["lon"], result["lat"],
c=result[col], cmap="RdYlBu_r", s=5, alpha=0.8,
vmin=result[col].quantile(0.02), vmax=result[col].quantile(0.98)
)
ax.set_title(col.replace("coef_", "β_"), fontsize=14)
plt.colorbar(sc, ax=ax, shrink=0.8)
plt.suptitle("Spatially Varying Coefficients (GNNWR)", fontsize=16)
plt.tight_layout()
plt.savefig("coefficients_map.png", dpi=300, bbox_inches="tight")
GeoPandas + Contextily (with basemap)
import geopandas as gpd
import contextily as ctx
gdf = gpd.GeoDataFrame(result, geometry=gpd.points_from_xy(result.lon, result.lat), crs="EPSG:4326")
gdf_web = gdf.to_crs(epsg=3857)
fig, ax = plt.subplots(figsize=(12, 10))
gdf_web.plot(column="coef_x1", ax=ax, cmap="RdYlBu_r", legend=True,
markersize=5, alpha=0.7, legend_kwds={"shrink": 0.6})
ctx.add_basemap(ax, source=ctx.providers.CartoDB.Positron)
ax.set_title("β_x1 Spatial Variation")
ax.set_axis_off()
plt.savefig("coef_basemap.png", dpi=300, bbox_inches="tight")
When to Use vs Alternatives
| Use Case |
Tool |
Why |
| Spatially varying coefficients (neural net) |
GNNWR |
Non-linear weighting, scalable, coefficient maps |
| Classical geographically weighted regression |
mgwr / GWR4 |
Traditional bandwidth-based, well-established theory |
| Spatial interpolation (no covariates) |
verde / scikit-gstat |
Gridding / kriging without regression |
| Global regression baseline |
statsmodels / scikit-learn |
No spatial non-stationarity assumed |
| Spatiotemporal varying coefficients |
GTNNWR |
GNNWR extended with temporal dimension |
| Large-scale spatial regression (N > 100k) |
GNNWR + knn_k |
Sparse distance matrix, O(n·k²) diagnostics |
| Geostatistical simulation |
geostatspy / SGeMS |
Stochastic realizations, uncertainty quantification |
Choose GNNWR when: You need spatially varying regression coefficients with neural
network-based geographic weighting, especially for large datasets where classical GWR
is computationally infeasible.
Choose classical GWR when: You need well-established inferential statistics,
bandwidth-based weighting, and simpler model interpretation.
Choose verde/kriging when: You need spatial interpolation without explanatory
variables — pure spatial prediction from observed values.
Common Workflows
Spatial Regression Analysis
Common Issues
| Issue |
Solution |
| Model degenerates to global regression |
Forgot spatial_column — always pass it |
| OOM on distance matrix |
N > 10k without knn_k; use knn_k=500–2000 |
| Loss explodes during training |
start_lr too high; start with 0.01 |
| Overfitting |
No early_stop; always set 20–50 |
| Coefficients on wrong scale |
Use reg_result() for denormalized predictions |
| GTNNWR behaves like GNNWR |
Missing temp_column; silently falls back |
References
- Diagnostics — DIAGNOSIS methods, F-tests, residual analysis
- Visualization — Detailed visualization patterns and publication figures
1---2name: gnnwr3description: |4 Spatial and spatiotemporal regression with GNNWR (Geographically Neural Network5 Weighted Regression). Use when Claude needs to: (1) Build spatially varying coefficient6 regression models, (2) Analyze geographic non-stationarity in spatial data,7 (3) Generate spatial coefficient maps for publication, (4) Run spatiotemporal8 regression with GTNNWR, (5) Scale geographically weighted regression to large9 datasets (N > 10k) with KNN mode, (6) Diagnose spatial model performance with10 F-tests, AIC, and residual maps.11version: 1.0.012author: Geoscience Skills13license: MIT14tags: [Spatial Regression, GNNWR, GTNNWR, GWR, Non-Stationarity, Coefficient Mapping, Spatial Analysis, Geographic Weighting]15dependencies: [gnnwr>=0.1.0, pandas, torch]16complements: [verde, geostatspy, scikit-gstat, pyvista, xarray]17workflow_role: analysis18metadata:19 source: https://skillmd.com/skills/steadfastasart/gnnwr20---2122# GNNWR - Geographically Neural Network Weighted Regression2324## Quick Reference2526```python27from gnnwr import models, datasets, utils28import pandas as pd2930data = pd.read_csv("data.csv")3132train, val, test = datasets.init_dataset(33 data=data, test_ratio=0.2, valid_ratio=0.1,34 x_column=["x1", "x2", "x3"], y_column=["y"],35 spatial_column=["lon", "lat"], # REQUIRED: geographic coords36 batch_size=32, process_fn="minmax_scale"37)3839model = models.GNNWR(train, val, test, use_gpu=True, optimizer="Adam", start_lr=0.01)40model.run(max_epoch=200, early_stop=30)4142result = model.reg_result(only_return=True) # DataFrame: coef_x1, coef_x2, ..., Pred_y43print(model.result()) # R², AIC, RMSE, F-tests summary44```4546### Spatiotemporal (GTNNWR)4748```python49train, val, test = datasets.init_dataset(50 data=data, ...,51 spatial_column=["lon", "lat"],52 temp_column=["year", "month"], # add temporal coords53 use_model="gtnnwr"54)55model = models.GTNNWR(train, val, test, use_gpu=True)56```5758### Large-Scale (N > 10k) — KNN Mode5960```python61train, val, test = datasets.init_dataset(62 data=data, ..., knn_k=500 # only k nearest neighbor distances63)64# Memory: N=100k full=55GB → knn_k=2000 only 763MB65```6667## Key Classes6869| Class | Purpose |70|-------|---------|71| `models.GNNWR` | Spatial regression with neural network geographic weighting |72| `models.GTNNWR` | Spatiotemporal regression with temporal + spatial weighting |73| `datasets.init_dataset` | Data splitting, normalization, distance matrix construction |74| `utils.Visualize` | Built-in folium interactive maps for coefficients and predictions |7576## Essential Operations7778### init_dataset Parameters7980| Parameter | Default | Notes |81|-----------|---------|-------|82| `knn_k` | None | KNN sparse distance; None=full matrix |83| `process_fn` | "minmax_scale" | or "standard_scale" |84| `spatial_fun` | BasicDistance | Euclidean; or ManhattanDistance |85| `Reference` | None | "train", "train_val", or custom DataFrame |86| `sample_seed` | 42 | Reproducibility |8788### Model Hyperparameters8990| Parameter | Recommended | Notes |91|-----------|-------------|-------|92| `optimizer` | "Adam" | Also: SGD, AdamW, Adagrad, RMSprop |93| `start_lr` | 0.01–0.1 | Critical tuning point |94| `drop_out` | 0.2 | 0.0–0.5 |95| `dense_layers` | None (auto) | Auto: power-of-2 sequence from input_dim to n_coef |96| `early_stop` | 20–50 | Patience; -1=disabled |97| `batch_norm` | True | Stabilizes training |98| `use_ols` | True | OLS-initialized output layer |99100### Diagnostics101102```python103diag = model._test_diagnosis104diag.R2() # always available105diag.RMSE() # always available106diag.AIC() # needs lite=False (auto for N<10k)107diag.AICc() # corrected AIC108diag.F1_Global() # GNNWR vs OLS significance109diag.F2_Global() # spatial weight significance110diag.F3_Local() # per-variable significance → (dict1, dict2)111```112113`lite=True` (auto when N>10k): only R²/RMSE; Hat-matrix diagnostics skipped.114115## Visualization Patterns116117### Folium Interactive Maps (built-in)118119```python120viz = utils.Visualize(model, lon_lat_columns=["lon", "lat"], zoom=5)121m1 = viz.display_dataset(name="all", y_column="y")122m1.save("dataset_map.html")123124for col in [c for c in result.columns if c.startswith("coef_")]:125 m = viz.coefs_heatmap(data_column=col, steps=20)126 m.save(f"map_{col}.html")127```128129### Matplotlib Static Maps (publication-ready)130131```python132import matplotlib.pyplot as plt133134fig, axes = plt.subplots(2, 3, figsize=(18, 12))135coef_cols = [c for c in result.columns if c.startswith("coef_")]136137for ax, col in zip(axes.flat, coef_cols):138 sc = ax.scatter(139 result["lon"], result["lat"],140 c=result[col], cmap="RdYlBu_r", s=5, alpha=0.8,141 vmin=result[col].quantile(0.02), vmax=result[col].quantile(0.98)142 )143 ax.set_title(col.replace("coef_", "β_"), fontsize=14)144 plt.colorbar(sc, ax=ax, shrink=0.8)145146plt.suptitle("Spatially Varying Coefficients (GNNWR)", fontsize=16)147plt.tight_layout()148plt.savefig("coefficients_map.png", dpi=300, bbox_inches="tight")149```150151### GeoPandas + Contextily (with basemap)152153```python154import geopandas as gpd155import contextily as ctx156157gdf = gpd.GeoDataFrame(result, geometry=gpd.points_from_xy(result.lon, result.lat), crs="EPSG:4326")158gdf_web = gdf.to_crs(epsg=3857)159160fig, ax = plt.subplots(figsize=(12, 10))161gdf_web.plot(column="coef_x1", ax=ax, cmap="RdYlBu_r", legend=True,162 markersize=5, alpha=0.7, legend_kwds={"shrink": 0.6})163ctx.add_basemap(ax, source=ctx.providers.CartoDB.Positron)164ax.set_title("β_x1 Spatial Variation")165ax.set_axis_off()166plt.savefig("coef_basemap.png", dpi=300, bbox_inches="tight")167```168169## When to Use vs Alternatives170171| Use Case | Tool | Why |172|----------|------|-----|173| Spatially varying coefficients (neural net) | **GNNWR** | Non-linear weighting, scalable, coefficient maps |174| Classical geographically weighted regression | **mgwr / GWR4** | Traditional bandwidth-based, well-established theory |175| Spatial interpolation (no covariates) | **verde / scikit-gstat** | Gridding / kriging without regression |176| Global regression baseline | **statsmodels / scikit-learn** | No spatial non-stationarity assumed |177| Spatiotemporal varying coefficients | **GTNNWR** | GNNWR extended with temporal dimension |178| Large-scale spatial regression (N > 100k) | **GNNWR + knn_k** | Sparse distance matrix, O(n·k²) diagnostics |179| Geostatistical simulation | **geostatspy / SGeMS** | Stochastic realizations, uncertainty quantification |180181**Choose GNNWR when**: You need spatially varying regression coefficients with neural182network-based geographic weighting, especially for large datasets where classical GWR183is computationally infeasible.184185**Choose classical GWR when**: You need well-established inferential statistics,186bandwidth-based weighting, and simpler model interpretation.187188**Choose verde/kriging when**: You need spatial interpolation without explanatory189variables — pure spatial prediction from observed values.190191## Common Workflows192193### Spatial Regression Analysis194- [ ] EDA: Check spatial distribution, feature correlations, OLS baseline195- [ ] Data split: `init_dataset` with appropriate ratios and `sample_seed=42`196- [ ] Train: Start with defaults, tune `start_lr` and `early_stop`197- [ ] Diagnose: R², RMSE, F1 (GNNWR vs OLS), F2 (spatial weight significance)198- [ ] Visualize: Coefficient maps, residual spatial distribution, pred vs obs199- [ ] Interpret: Where do coefficients vary most? Which variables show strongest non-stationarity? (F3_Local)200- [ ] Report: Model summary table + coefficient maps + diagnostic statistics201202## Common Issues203204| Issue | Solution |205|-------|----------|206| Model degenerates to global regression | Forgot `spatial_column` — always pass it |207| OOM on distance matrix | N > 10k without `knn_k`; use `knn_k=500–2000` |208| Loss explodes during training | `start_lr` too high; start with 0.01 |209| Overfitting | No `early_stop`; always set 20–50 |210| Coefficients on wrong scale | Use `reg_result()` for denormalized predictions |211| GTNNWR behaves like GNNWR | Missing `temp_column`; silently falls back |212213## References214215- **[Diagnostics](references/diagnostics.md)** — DIAGNOSIS methods, F-tests, residual analysis216- **[Visualization](references/visualization.md)** — Detailed visualization patterns and publication figures