Metadata-Version: 2.4
Name: addereq
Version: 1.4.3
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: pymysql
Requires-Dist: cx_Oracle
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: python-pptx
Requires-Dist: python-docx
Requires-Dist: pyarrow
Dynamic: license-file

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

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

## 主要功能

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

## 新增功能

### v1.4.3

1. **修复数据库连接兼容性问题**：修复 `pd.read_sql` 因 DBAPI2 连接对象不兼容导致的 `UserWarning` 和 `AttributeError`。
2. **升级 SQLAlchemy 至 2.x**：解除 SQLAlchemy 1.4.48 版本锁定，升级至 2.x，提升与 pandas 2.x 的兼容性。
3. 移除 `.pyd` 编译文件的 Git 跟踪。

### v1.4.2.dev1

1. **核心逻辑重构**：从“硬编码推断采样率”彻底转向“数据库 ID 驱动”。
   - 移除 `fetching` 模块对返回列的强制过滤，保留所有原始数据字段。
   - `fetching` 和 `plotting` 模块现在通过数据中自带的 `SAMPLERATE` 列 ID（01, 02, 60, 90）动态匹配频率。
2. 优化了 `split_lines` 逻辑，确保在大规模数据展开时的鲁棒性。

### v1.4.1

1. **紧急修复模块导入问题**：修复了由于 `setup.py` 缺失导致的 `export` 模块无法导入的问题。
2. 同步更新包结构，确保 Cython 编译环境下的兼容性。

### v1.4.0

1. **新增 QZAD (Qianzhao Arrow Data) 行业标准格式支持**：基于 Apache Arrow 开发的地震前兆数据存储格式，支持元数据（台站、测项、采样率等）自动嵌入。
2. 统一了数据导出接口，支持高效的跨平台数据交换。

### v1.3.7.dev2

1. 修改日志目录

### v1.3.7.dev1

1. 继续修复产品数据不能下载整点值的问题

### v1.3.6

1. 发布新版，自定义每条曲线类型
2. 紧急修复产品数据不能下载整点值的问题

### v1.3.5

1. 发布新版，不再支持python 3.7

### v1.3.4

1. 升级支持python 3.13
2. 修复绘图字体乱码

### v1.3.3

1. 永久性解决数据分割中存在非数值型的情况。

### v1.3.0

1. 更新了调用方式，同时兼容旧的调用方式
```python
plotter = plotting.TSPlotter(
    conn,
    mean_color='r',       # 均值线颜色
    std_color='gray',     # 标准差线颜色
    mean_linestyle='--',  # 均值线样式
    std_linestyle=':'     # 标准差线样式
)

plotter.plot(
    data,
    groupby='item',           # 分组方式：'item' 或 'station'
    show_mean=True,           # 显示均值线
    show_std=True             # 显示标准差线
)
```

2. 添加了地震标注功能

```python
plotter.plot(df, 
             groupby='item', 
             show_mean=False,
             show_std=True,
             set_zero=False,
             plot_type='line',
             std_multiplier=2.0,
             eqt_dir='D:/tests/HuaBei.EQT',
             eqt_filters=[(200, 4.5), (350, 5.0)]
             )
```

### v1.2.0

1. 使用Claude进行了代码重构，优化性能。

### v1.1.1

1. 修改了reindex算法；
2. 修改了字符串分割逻辑，去除首尾字符，防止不符合规则的数据报错。

## 安装

1. Python环境安装

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

2. addereq包安装

由于cx_Oracle在Windows系统下的安装需要Visual C++编译环境，配置起来比较复杂，建议先使用conda安装cx_Oracle，然后再安装addereq，安装命令如下：

``` shell
conda install cx_Oracle
```

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

``` shell
pip install addereq
```



## 安装 Oracle 即时客户端

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

## 数据库配置文件

需要将常用的数据库配置到`default.conf`文件中，该文件可以存放在和脚本相同目录中，也可以存放在系统用户目录中，建议存放在系统用户目录中，目录需为`~/.adder/default.conf`。
配置文件格式为：

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

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

## 主要模块功能说明

### 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)
```

### 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>
