gnnwr

GNNWR - 地理神经网络加权回归

快速参考

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

时空模型（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)

大规模数据（N > 10k）——KNN 模式

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

关键类

类	用途
models.GNNWR	通过神经网络进行地理加权的空间回归
models.GTNNWR	结合时间和空间加权的时空回归
datasets.init_dataset	数据拆分、归一化、距离矩阵构建
utils.Visualize	内置 folium 交互式系数和预测地图

核心操作

init_dataset 参数

参数	默认值	说明
knn_k	None	KNN 稀疏距离；None=完整矩阵
process_fn	"minmax_scale"	或 "standard_scale"
spatial_fun	BasicDistance	欧几里得距离；或 ManhattanDistance
Reference	None	"train"、"train_val" 或自定义 DataFrame
sample_seed	42	确保结果可复现

模型超参数

参数	推荐值	说明
optimizer	"Adam"	也可以是：SGD、AdamW、Adagrad、RMSprop
start_lr	0.01–0.1	关键调优参数
drop_out	0.2	0.0–0.5
dense_layers	None（自动）	自动生成从 input_dim 到 n_coef 的 2 的幂次序列
early_stop	20–50	耐心值；-1=禁用
batch_norm	True	稳定训练过程
use_ols	True	使用 OLS 初始化输出层

诊断

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（N>10k 时自动启用）：仅计算 R²/RMSE；跳过帽子矩阵诊断。

可视化模式

Folium 交互式地图（内置）

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 静态地图（适用于出版物）

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（含底图）

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")

何时使用及替代方案

使用场景	工具	原因
空间变系数（神经网络）	GNNWR	非线性加权、可扩展、系数地图
经典地理加权回归	mgwr / GWR4	传统的带宽加权，理论成熟
空间插值（无协变量）	verde / scikit-gstat	无需回归即可进行网格化 / 克里金插值
全局回归基线	statsmodels / scikit-learn	不假设存在空间非平稳性
时空变系数	GTNNWR	在 GNNWR 基础上扩展了时间维度
大规模空间回归（N > 100k）	GNNWR + knn_k	稀疏距离矩阵，诊断复杂度为 O(n·k²)
地统计模拟	geostatspy / SGeMS	随机实现、量化不确定性

选择 GNNWR 的情况：需要具有空间变动回归系数和基于神经网络的地理加权，尤其是经典 GWR 在计算上难以处理的大型数据集。

选择经典 GWR 的情况：需要成熟的推断统计、基于带宽的加权，以及更简单的模型解释。

选择 verde/克里金的情况：需要在没有解释变量的情况下进行空间插值——仅根据观测值进行空间预测。

常见工作流

空间回归分析

• EDA：检查空间分布、特征相关性和 OLS 基线
• 数据拆分：使用合适的比例和 sample_seed=42 调用 init_dataset
• 训练：从默认值开始，调优 start_lr 和 early_stop
• 诊断：R²、RMSE、F1（GNNWR 与 OLS 对比）、F2（空间权重显著性）
• 可视化：系数地图、残差空间分布、预测值与观测值对比
• 解释：系数在哪些区域变化最大？哪些变量表现出最强的非平稳性？（F3_Local）
• 报告：模型摘要表 + 系数地图 + 诊断统计量

常见问题

问题	解决方案
模型退化为全局回归	忘记设置 spatial_column — 务必传入
距离矩阵导致内存溢出	N > 10k 且未设置 knn_k；请使用 knn_k=500–2000
训练期间损失爆炸	start_lr 过高；请从 0.01 开始
过拟合	未设置 early_stop；务必设置为 20–50
系数的尺度不正确	使用 reg_result() 获取反归一化后的预测结果
GTNNWR 表现得像 GNNWR	缺少 temp_column；系统会静默回退

参考资料

• 诊断 — DIAGNOSIS 方法、F 检验、残差分析
• 可视化 — 详细的可视化模式和出版级图表