addereq（地震前兆数据自动分析框架）

一个用于从地震系统Oracle数据库中便捷读取数据并批量绘图的工具包。

主要功能

从地震系统的Oracle前兆数据库中提取数据，生成可视化图形，并无缝集成各种地球物理分析方法，以便实现自动化操作。

新增功能

完整变更记录见 CHANGELOG.md。

安装

1. Python环境安装

建议安装Anaconda或者Miniconda，Anaconda安装参考官网链接，Miniconda安装参考官网链接，入门建议安装Anaconda，不需要太多配置，开箱即用。

2. addereq包安装

当前版本已将 Oracle 驱动切换为 oracledb。为了兼容旧版 Oracle 10g，请使用 Thick 模式，并提前安装 Oracle Instant Client。

pip install oracledb

安装好Python环境后，执行以下命令安装addereq。

pip install addereq

如需使用 scripts/report.py 中的 Word / PowerPoint 报告生成功能，再额外安装报告依赖：

pip install "addereq[report]"

安装 Oracle 即时客户端

下载以及安装参见 Oracle Instant Client 官网链接

数据库配置文件

需要将常用的数据库配置到default.conf文件中，该文件可以存放在和脚本相同目录中，也可以存放在系统用户目录中，建议存放在系统用户目录中，目录需为~/.adder/default.conf。 旧版 default.conf 配置保持兼容，最小配置仍然是：

[db1]
HOST = 192.168.181.12
PORT = 1521
USERNAME = test
PASSWORD = test
TNSNAME = pdbqz

建议将常用数据库全部配置进去，一劳永逸。

如需显式指定 Thick 模式使用的 Oracle Client，可额外增加可选项：

ORACLE_CLIENT_LIB_DIR = C:\oracle\instantclient_11_2
ORACLE_CONFIG_DIR = C:\oracle\instantclient_11_2\network\admin

• ORACLE_CLIENT_LIB_DIR：可选，Oracle Instant Client 目录。连接 Oracle 10g 时，如果系统环境中找不到客户端库，再显式配置它。
• ORACLE_CONFIG_DIR：可选，tnsnames.ora 所在目录。只有在你的 TNSNAME 依赖本地 TNS 别名解析时才需要。
• 如果当前连接本来就是基于 HOST + PORT + TNSNAME 直连，并且系统已能找到 Oracle Client，那么这两个字段都可以不写。
• 也就是说，不指定 tnsnames.ora 不是问题；只有依赖本地 TNS 别名解析时才需要它。

主要模块功能说明

fetching 模块

该模块为数据下载模块，可以提供快速批量的数据下载功能。

1. 连接数据库

参数只需要输入default.conf文件中配置的数据库名称即可。

from addereq import fetching as tsf
conn = tsf.conn_to_Oracle('db1')

2. 数据下载

from addereq import fetching as tsf
df = tsf.fetching_data(conn, '20230416', '20230416', '地电场', '北京', '分钟值', '原始库', gzip_flag=False)

plotting 模块

该模块为批量绘图模块，提供类MapSIS的功能，可以批量绘制多个台站或者多个测向的曲线。df变量中可以包含多个台站、多个测向的数据，可以一次性批量绘制，输出文件名自动生成。

1. 按台站绘图

from addereq import plotting as tsp
tsp.plot_by_stations(df, conn)

2. 按测向代码绘图

from addereq import plotting as tsp
tsp.plot_by_items(df, conn)

3. 离线绘图（先缓存元数据，再断网使用）

from addereq import fetching as tsf
from addereq import plotting as tsp

# 第一次在可连库环境执行，刷新本地缓存
conn = tsf.conn_to_Oracle('db1')
tsf.refresh_metadata_cache(conn)

# 之后即使数据库断开，也可以只依赖本地数据和本地缓存绘图
tsp.plot_by_stations(df, None)

# 也可以显式指定缓存目录
tsp.plot_by_items(df, None, metadata_dir='D:/adder_metadata_cache')

默认缓存目录为 ~/.adder/metadata_cache，其中会保存台站、测点、测项、方法、台站测项关联等字典表。离线绘图时，标题、单位、台站名称、经纬度等信息都会优先从本地缓存读取。

提供数据库连接时，元数据缓存按 default.conf 中的 HOST 值隔离。例如，HOST = 10.37.187.12 对应 ~/.adder/metadata_cache/10.37.187.12/*.parquet，HOST = 10.37.187.192 对应 ~/.adder/metadata_cache/10.37.187.192/*.parquet。这样可以避免不同 Oracle 数据库的台站、测点、测项及台站测项关联字典相互覆盖或混用。

未携带 HOST 命名空间的旧连接仍可使用数据库别名作为兼容回退。离线绘图（conn=None）读取 metadata_dir 指定的缓存目录；未指定时读取根目录 ~/.adder/metadata_cache。离线模式无法自动推断 HOST，使用按 HOST 隔离的缓存时，请将 metadata_dir 指向对应的 HOST 子目录。

4. demo 脚本

python tests/simple_plot_demo.py

该脚本基于 tests/simple_plot.py 改写，增加了缓存刷新和离线绘图演示。

export 模块 (QZAD 行业标准格式)

该模块提供统一的 QZAD (Qianzhao Arrow Data) 格式导出功能，基于 Apache Arrow 开发，自动嵌入台站、测项等元数据。

1. 转换为 QZAD 对象 (获取包含元数据的 Arrow Table)

from addereq import fetching as tsf

# 获取数据
df = tsf.fetching_data(conn, '20230416', '20230416', '地电场', '北京', '分钟值', '原始库')

# 转换为包含完整元信息的 QZAD 对象 (Arrow Table)
qzad_table = tsf.DataFetcher.to_qzad(conn, df, sampling_rate=60)

2. 一键导出为 QZAD 文件 (自动从数据库关联元数据)

from addereq import fetching as tsf

# 获取数据
df = tsf.fetching_data(...)

# 一键导出：自动抓取台站、测项、经纬度等元数据并打包
tsf.DataFetcher.export_qzad(conn, df, "data_output.qzad", sampling_rate=60)

3. 加载 QZAD 数据并恢复时间序列

import pandas as pd

# 读取 QZAD 文件并恢复为以时间为索引的 DataFrame
df = pd.read_parquet("data_output.qzad")
df.set_index('STARTDATE', inplace=True)
df.sort_index(inplace=True)

绘图末尾追加全球 Kp 指数

plot_by_items 和 plot_by_stations 支持 show_kp=True，自动从 GFZ 获取同期全球 Kp，并在每张图的末尾追加三小时柱状子图。 无时区的观测时间默认按北京时间（Asia/Shanghai）解释。

from addereq import plotting as tsp
from addereq.kp import fetch_kp

tsp.plot_by_stations(df, conn, show_kp=True)
tsp.plot_by_items(df, conn, show_kp=True, number_of_subplots=7)

kp_data = fetch_kp('2026-01-19', '2026-01-22 23:59:59')
tsp.plot_by_stations(df, None, metadata_dir='D:/adder_metadata_cache',
                     show_kp=True, kp_data=kp_data)

tsp.plot_by_stations(df_utc, conn, show_kp=True, time_timezone='UTC')

kp_data 必须使用带时区的 DatetimeIndex，包含 Kp 和 status 列。 传入数据时不再请求网络；未开启 show_kp 时也不请求网络。 Kp 保留小数，低于 4 为绿色、4 至不足 5 为黄色、5 及以上为红色，缺测不补零。 降雨子图位于 Kp 之前；分页数量只计算观测子图。 网络获取失败时保留末尾提示和原观测图。返回轴数组包含 Kp 轴。 数据源及授权：GFZ Kp API（CC BY 4.0）。

联系作者

chd_wql@qq.com