Metadata-Version: 2.1
Name: addereq
Version: 1.4.4
Summary: 地震前兆数据自动处理框架
Author-email: WANG Qinglin <chd_wql@qq.com>
License: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: oracledb
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: openpyxl
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: seaborn
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: pyarrow
Provides-Extra: report
Requires-Dist: python-pptx; extra == "report"
Requires-Dist: python-docx; extra == "report"

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

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

## 主要功能

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

## 新增功能

完整变更记录见 [CHANGELOG.md](CHANGELOG.md)。

## 安装

1. Python环境安装

建议安装Anaconda或者Miniconda，Anaconda安装参考[官网链接](https://www.anaconda.com/download/)，Miniconda安装参考[官网链接](https://docs.conda.io/en/latest/miniconda.html)，入门建议安装Anaconda，不需要太多配置，开箱即用。

2. addereq包安装

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

``` shell
pip install oracledb
```

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

``` shell
pip install addereq
```

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

``` shell
pip install "addereq[report]"
```



## 安装 Oracle 即时客户端

下载以及安装参见 Oracle Instant Client [官网链接](https://www.oracle.com/database/technologies/instant-client/downloads.html)

## 数据库配置文件

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

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

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

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

``` shell
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`文件中配置的数据库名称即可。

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

2. 数据下载

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

### plotting 模块

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

1. 按台站绘图

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

2. 按测向代码绘图

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

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

``` python
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`，其中会保存台站、测点、测项、方法、台站测项关联等字典表。离线绘图时，标题、单位、台站名称、经纬度等信息都会优先从本地缓存读取。


When a database connection is provided, metadata cache files are isolated by the `default.conf` database section name. For example, `conn_to_Oracle('DB12')` writes and reads `~/.adder/metadata_cache/DB12/*.parquet`, while `conn_to_Oracle('ctm')` uses `~/.adder/metadata_cache/ctm/*.parquet`. This prevents station, point, item, and station-item dictionaries from different Oracle databases from overwriting or shadowing each other. Offline plotting with `conn=None` continues to read the cache directory specified by `metadata_dir` or the root `~/.adder/metadata_cache` directory.
4. demo 脚本

``` python
python tests/simple_plot_demo.py
```

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

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

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

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

```python
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 文件** (自动从数据库关联元数据)

```python
from addereq import fetching as tsf

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

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

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

```python
import pandas as pd

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

## 联系作者

<chd_wql@qq.com>
