GaMMA 关联器库

GaMMA 是什么？

GaMMA 是一种地震震相关联算法，将关联问题建模为无监督聚类问题。它使用多元高斯分布对某次地震事件的所有震相拾取结果进行建模，并通过期望最大化（Expectation-Maximization, EM）算法完成拾取分配，同时估计震源参数——即地震位置、发震时刻和震级。

GaMMA 是该算法的 Python 实现库。对于输入的地震波形数据，本库假设 P 波与 S 波的拾取结果（P/S wave picks）已预先提取完成。本文档介绍其核心 API 的使用方法。

Zhu, W., McBrearty, I. W., Mousavi, S. M., Ellsworth, W. L., & Beroza, G. C. (2022). Earthquake phase association using a Bayesian Gaussian mixture model. Journal of Geophysical Research: Solid Earth, 127(5).

本技能基于代码仓库 https://github.com/AI4EPS/GaMMA 衍生而来。

安装 GaMMA

pip install git+https://github.com/wayneweiqiang/GaMMA.git

GaMMA 核心 API

association

函数签名

def association(picks, stations, config, event_idx0=0, method="BGMM", **kwargs)

功能说明

使用贝叶斯高斯混合模型（BGMM）或标准高斯混合模型（GMM）对地震震相拾取（P 波与 S 波）进行事件关联。该函数基于拾取的到时与振幅信息进行聚类，并拟合高斯混合模型以估计地震的位置、发震时刻与震级。

1. 输入参数

2. DataFrame 所需列名

picks DataFrame

注意事项：

• 时间戳必须为 UTC 时间，或已转换为 UTC
• 震相类型在内部被强制转为小写
• 当 use_amplitude=True 时，amp == 0 或 amp == -1 的拾取将被过滤
• DataFrame 的索引将用于在输出中追踪拾取项的身份

stations DataFrame

注意事项：

• 坐标应采用投影后的局部坐标系（例如可使用 pyproj 包进行转换）
• id 列内容必须与 picks DataFrame 中的 id 值完全一致（如 network.station. 或 network.station.location.channel）
• 相同 id 的多条台站记录将按唯一 id 分组；属性一致者合并为单值，属性冲突者保留为排序后的列表

3. 配置字典（config）键说明

必需键

关于 dims 的说明：

• 可选值：["x(km)", "y(km)", "z(km)"]、["x(km)", "y(km)"] 或 ["x(km)"]

关于 bfgs_bounds 的说明：

• 格式：((x_min, x_max), (y_min, y_max), (z_min, z_max), (None, None))
• 最后一个元组对应时间维度（无界）

速度模型相关键

DBSCAN 预聚类相关键（可选）

• dbscan_eps 可由 estimate_eps 函数自动估算

筛选相关键（可选）

其他可选键

4. 返回值

返回元组 (events, assignments)：

events（list[dict]）

字典列表，每个字典代表一次已关联的地震事件：

assignments（list[tuple]）

元组列表，每个元组形如 (pick_index, event_index, gamma_score)：

• pick_index：原始 picks DataFrame 中的行索引
• event_index：所关联事件的索引
• gamma_score：该分配的概率 / 置信度

estimate_eps 函数文档

函数签名

def estimate_eps(stations, vp, sigma=2.0)

功能说明

根据台站空间分布估算适用于地震震相拾取聚类的 DBSCAN epsilon（eps）参数。该参数控制 DBSCAN 聚类算法中视为邻近点的最大时间距离。

1. 输入参数

2. DataFrame 所需列名

stations DataFrame

3. 返回值

4. 使用示例

from gamma.utils import estimate_eps

# 假设 stations DataFrame 已准备就绪，且包含 x(km)、y(km)、z(km) 列
vp = 6.0  # P 波速度（单位：km/s）

# 基于台站间距自动估算 eps
eps = estimate_eps(stations, vp, sigma=2.0)

# 在 config 中使用
config = {
    "use_dbscan": True,
    "dbscan_eps": eps,  # 或使用 estimate_eps(stations, config["vel"]["p"])
    "dbscan_min_samples": 3,
    # ... 其他配置项
}

典型使用模式

from gamma.utils import association, estimate_eps

# 自动估算 eps
config["dbscan_eps"] = estimate_eps(stations, config["vel"]["p"])

# 或手动指定（实践中更常见）
config["dbscan_eps"] = 15  # 单位：秒

5. 实践建议

• 在示例 notebook 中，该函数常被注释掉，而直接采用硬编码值（10–15 秒）
• 实际应用中，用户往往倾向针对特定台网或区域手动调优
• 典型输出值范围约为 10–20 秒，具体取决于台站密度
• 当最优 eps 值未知，或面对新布设台网时尤为有用

6. 相关配置项

该函数输出通常用于以下配置项：

config["dbscan_eps"] = estimate_eps(stations, config["vel"]["p"])
config["dbscan_min_samples"] = 3
config["dbscan_min_cluster_size"] = 500
config["dbscan_max_time_space_ratio"] = 10