PyGeoD - Python地理探测器

地理探测器的Python实现，用于空间分层异质性分析

PyGeoD是一个全面的Python库，实现了地理探测器方法，用于测量空间分层异质性和分析因子交互作用。该库是流行的R包GD的Python移植版本，在Python生态系统中提供相同的功能。

🌟 功能特性

四大核心探测器

• 因子探测器：使用q统计量测量空间分层异质性
• 交互探测器：分析因子对之间的交互作用
• 风险探测器：检验因子层间的差异性
• 生态探测器：比较不同因子的影响力

高级功能

• 最优离散化：自动寻找连续变量的最佳离散化参数
• 多种方法：支持6种离散化方法（等距、分位数、自然断点、K-means、几何级数、标准差）
• 全面可视化：为所有分析类型提供内置绘图功能
• 灵活接口：支持R式公式或直接数组输入
• 示例数据集：包含NDVI和H1N1示例数据集

📊 什么是地理探测器？

地理探测器是用于检测空间分层异质性并揭示其驱动力的统计方法。该方法基于这样的假设：如果一个自变量对因变量有重要影响，那么它们的空间分布应该相似。

核心概念

q统计量：量化空间分层异质性的核心度量：

q = 1 - (SSW/SST)

其中SSW是层内方差之和，SST是总方差。

• q = 0：无空间分层
• q = 1：完全空间分层
• q越大：解释力越强

🚀 快速开始

安装

# 从PyPI安装（可用时）
pip install pygeod

# 从源码安装
git clone https://github.com/pygeod/pygeod
cd pygeod
pip install -e .

基本用法

import pygeod as gd
import matplotlib.pyplot as plt

# 加载示例数据
data = gd.load_sample_data('ndvi')
print(data.head())

# 基础因子探测器分析
result = gd.gd('NDVIchange ~ Climatezone + Mining', data)
print(result.summary)

# 可视化结果
fig = gd.plot_factor_detector(result)
plt.show()

综合分析

# 主探测器 - 含离散化的综合分析
result = gd.gdm(
    'NDVIchange ~ Climatezone + Mining + Tempchange',
    data,
    continuous_vars=['Tempchange'],
    disc_method=['equal', 'quantile', 'natural'],
    disc_intervals=[3, 4, 5, 6]
)

# 查看摘要
print(result.summary)

# 创建综合可视化
fig = gd.plot_master_detector_summary(result)
plt.show()

📋 详细示例

1. 因子探测器分析

import pygeod as gd

# 加载数据
data = gd.load_sample_data('ndvi')

# 执行因子探测器分析
factor_result = gd.gd('NDVIchange ~ Climatezone + Mining', data)

# 结果解释
print("q值（解释力）：")
for var, qv, pv in zip(factor_result.variables, factor_result.q_values, factor_result.p_values):
    significance = "***" if pv < 0.001 else "**" if pv < 0.01 else "*" if pv < 0.05 else ""
    print(f"{var}: q = {qv:.4f} (p = {pv:.4f}) {significance}")

2. 交互分析

# 交互探测器 - 分析因子交互作用
interaction_result = gd.gdinteract('NDVIchange ~ Climatezone + Mining + Tempchange', data)

print("因子交互作用：")
for _, row in interaction_result.interactions.iterrows():
    print(f"{row['var1']} ∩ {row['var2']}: {row['interaction']} (q = {row['qv12']:.4f})")

# 可视化交互作用
fig = gd.plot_interaction_detector(interaction_result)
plt.show()

3. 风险分析

# 风险探测器 - 检验层间差异
risk_result = gd.gdrisk('NDVIchange ~ Climatezone + Mining', data)

# 查看各因子的风险均值
for var, means in risk_result.mean_values.items():
    print(f"\n{var}的风险均值：")
    for stratum, mean_val in means.sort_values(ascending=False).items():
        print(f"  {stratum}: {mean_val:.4f}")

4. 最优离散化

from pygeod.core.discretization import OptimalDiscretizer

# 寻找连续变量的最优离散化
opt_discretizer = OptimalDiscretizer()
opt_result = opt_discretizer.find_optimal(
    y=data['NDVIchange'],
    x=data['Tempchange'],
    methods=['equal', 'quantile', 'natural', 'kmeans'],
    intervals=[3, 4, 5, 6, 7]
)

print(f"最优离散化：")
print(f"方法：{opt_result.optimal_method}")
print(f"区间数：{opt_result.optimal_n_intervals}")
print(f"q值：{opt_result.optimal_qvalue:.4f}")

🔬 高级用法

自定义分析流程

# 步骤1：数据准备
data = gd.load_sample_data('h1n1')
print(gd.summary_statistics(data))

# 步骤2：识别变量类型
from pygeod.utils.data_utils import check_data_types
var_types = check_data_types(data.drop('H1N1', axis=1))
continuous_vars = [var for var, vtype in var_types.items() if vtype == 'continuous']

# 步骤3：综合分析
master_result = gd.gdm(
    'H1N1 ~ PopDensity + Healthcare + EconomicIndex',
    data,
    continuous_vars=continuous_vars,
    disc_method=['equal', 'quantile', 'natural'],
    disc_intervals=[3, 4, 5]
)

# 步骤4：详细检查
print("=== 因子探测器结果 ===")
print(master_result.factor_result.summary)

print("\n=== 交互作用结果 ===")
if master_result.interaction_result:
    print(master_result.interaction_result.interactions)

print("\n=== 生态比较结果 ===")
if master_result.ecological_result:
    print(master_result.ecological_result.comparisons)

# 步骤5：保存所有可视化
from pygeod.utils.visualization import save_all_plots
save_all_plots(master_result, output_dir="./analysis_plots")

处理真实数据

import pandas as pd

# 加载您自己的数据
# data = pd.read_csv('your_data.csv')

# 确保正确的数据类型
# data['categorical_var'] = data['categorical_var'].astype('category')
# data['continuous_var'] = pd.to_numeric(data['continuous_var'])

# 处理缺失值
# data = data.dropna()  # 或使用适当的插补方法

# 执行分析
# result = gd.gdm('response ~ var1 + var2 + var3', data, continuous_vars=['var3'])

📈 示例数据集

NDVI数据集

模拟NDVI（归一化植被指数）变化的合成数据集：

• 响应变量：NDVIchange（连续型）
• 因子：Climatezone（分类型）、Mining（分类型）、Tempchange（连续型）
• 大小：100个观测值

H1N1数据集

模拟H1N1流感发病率的合成数据集：

• 响应变量：H1N1（连续型）
• 因子：PopDensity（分类型）、Healthcare（分类型）、EconomicIndex（连续型）
• 大小：150个观测值

# 加载和探索示例数据集
ndvi_data = gd.load_sample_data('ndvi')
h1n1_data = gd.load_sample_data('h1n1')

print("NDVI数据集：")
print(gd.summary_statistics(ndvi_data))

print("\nH1N1数据集：")
print(gd.summary_statistics(h1n1_data))

🎨 可视化画廊

PyGeoD提供全面的可视化功能：

因子探测器图

显示q值的水平条形图，突出显示显著性

fig = gd.plot_factor_detector(result, sig_only=True)

交互探测器图

显示交互类型和强度的气泡图

fig = gd.plot_interaction_detector(interaction_result)

离散化优化图

显示不同离散化参数下q值的线图

fig = gd.plot_discretization_optimization(discretization_results)

主摘要图

包含多个子图的综合仪表板

fig = gd.plot_master_detector_summary(master_result)

🔄 与R包的比较

功能	R GD包	PyGeoD	说明
因子探测器	✅	✅	算法完全一致
交互探测器	✅	✅	相同的交互类型
风险探测器	✅	✅	配对t检验
生态探测器	✅	✅	F检验比较
最优离散化	✅	✅	支持6种方法
可视化	基础图表	丰富图表	使用seaborn增强
数据接口	R公式	R公式+数组	更灵活
性能	良好	增强	向量化操作

🛠️ API参考

主要函数

• gd() - 因子探测器分析
• gdinteract() - 交互探测器分析
• gdrisk() - 风险探测器分析
• gdeco() - 生态探测器分析
• gdm() - 主探测器（综合分析）

核心类

• FactorDetector - 因子探测器实现
• InteractionDetector - 交互探测器实现
• RiskDetector - 风险探测器实现
• EcologicalDetector - 生态探测器实现
• MasterDetector - 主探测器实现
• Discretizer - 变量离散化
• OptimalDiscretizer - 最优离散化

查看API.md获取完整文档。

📊 数学背景

q统计量公式

q = 1 - SSW/SST = 1 - Σ(N_h * σ_h²)/((N-1) * σ²)

其中：

• N_h = 层h中的观测数
• σ_h² = 层h内的方差
• N = 总观测数
• σ² = 总方差

显著性检验

使用非中心F分布，自由度为：

• df1 = L - 1（L = 层数）
• df2 = N - L

🤝 贡献

欢迎贡献！请查看我们的贡献指南了解详情。

开发环境设置

git clone https://github.com/pygeod/pygeod
cd pygeod
pip install -e ".[dev]"
pytest tests/

贡献领域

• 额外的离散化方法
• 性能优化
• 更多可视化选项
• 文档改进
• 错误修复和测试

📚 引用

如果您在研究中使用PyGeoD，请引用原始方法和本实现：

原始方法：

Song, Y., Wang, J., Ge, Y. & Xu, C. (2020) An optimal parameters-based geographical detector model enhances geographic characteristics of explanatory variables for spatial heterogeneity analysis: Cases with different types of spatial data, GIScience & Remote Sensing, 57(5), 593-610. DOI: 10.1080/15481603.2020.1760434

PyGeoD实现：

PyGeoD开发团队 (2024). PyGeoD: 用于空间分析的Python地理探测器. 版本1.0.0. https://github.com/pygeod/pygeod

BibTeX：

@article{Song2020opgd,
  author = {Yongze Song and Jinfeng Wang and Yong Ge and Chengdong Xu},
  title = {An optimal parameters-based geographical detector model enhances geographic characteristics of explanatory variables for spatial heterogeneity analysis: cases with different types of spatial data},
  journal = {GIScience \& Remote Sensing},
  volume = {57},
  number = {5},
  pages = {593--610},
  year = {2020},
  publisher = {Taylor \& Francis},
  doi = {10.1080/15481603.2020.1760434}
}

@software{pygeod2024,
  title = {PyGeoD: Python地理探测器},
  author = {PyGeoD开发团队},
  year = {2024},
  url = {https://github.com/pygeod/pygeod},
  version = {1.0.0}
}

📄 许可证

本项目采用GNU通用公共许可证v3.0许可 - 详见LICENSE文件。

🙏 致谢

• 原R GD包作者：宋永泽和吕文波
• 王劲峰教授提供的地理探测器理论基础
• Python科学计算社区提供的优秀库

📞 支持

• 文档：API.md
• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• 邮箱：pygeod@example.com

---

PyGeoD：将地理探测器的力量带入Python生态系统！🐍🌍