Metadata-Version: 2.4
Name: autowaterqualitymodeler
Version: 1.3.4
Summary: 一键式水质光谱建模工具
Home-page: 
Author: 周元琦
Author-email: 周元琦 <yzuzhny@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/1034378361/AutoWaterQualityModeler
Project-URL: Bug Tracker, https://github.com/1034378361/AutoWaterQualityModeler/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: cryptography>=36.0.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.3; extra == "dev"
Requires-Dist: black>=23.11.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: setuptools_scm>=6.2.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: requires-python

# 自动水质建模器 (AutoWaterQualityModeler)

自动水质建模器是一个基于光谱分析的水质参数预测系统，支持对不同水体类型的水质指标进行快速建模与预测。

## 主要功能

- 自动光谱预处理：重采样、平滑、异常检测
- 特征提取：基于用户配置的公式计算各种光谱特征
- 模型构建：自动为每个水质指标构建幂函数模型
- 模型加密：使用AES256加密保护模型参数
- 日志系统：提供完整的操作日志记录

## 安装方法

### 方法1：从PyPI安装

```bash
pip install autowaterqualitymodeler
```

### 方法2：从源码安装

```bash
git clone https://github.com/1034378361/AutoWaterQualityModeler.git
cd AutoWaterQualityModeler
pip install -e .
```

## 快速开始

```python
import pandas as pd
from autowaterqualitymodeler import AutoWaterQualityModeler

# 加载数据
spectrum_data = pd.read_csv('光谱数据.csv', index_col=0)  # 波长作为列名
merged_data = pd.read_csv('反演数据.csv', index_col=0)     # 包含初步反演结果
metric_data = pd.read_csv('实测指标.csv', index_col=0)     # 实测水质指标

# 初始化建模器
modeler = AutoWaterQualityModeler(
    features_config_path="config/features_config.json",
    min_wavelength=400,
    max_wavelength=900
)

# 执行建模
model_dict = modeler.fit(
    spectrum_data=spectrum_data,
    merged_data=merged_data,
    metric_data=metric_data,
    data_type="shore_data"  # 可选: "warning_device", "shore_data", "smart_water"
)

# 输出模型结果
print(model_dict)
```

## 命令行工具

安装后，您可以直接使用命令行工具：

```bash
autowaterquality --spectrum 光谱数据.csv --merged 反演数据.csv --metric 实测指标.csv --output 结果.json
```

## 数据格式要求

- **光谱数据(spectrum_data)**: DataFrame格式，列名为波长值，每行代表一个样本的光谱
- **反演数据(merged_data)**: DataFrame格式，包含初步反演结果，用于模型微调
- **实测数据(metric_data)**: DataFrame格式，包含实测的水质指标值

## 特征配置

系统使用`features_config.json`文件配置：

1. 特征定义：在中央特征库定义光谱特征及其计算公式
2. 模型参数：设置建模参数
3. 数据类型配置：为不同数据类型指定特征和参数

### 主要参数

配置文件中支持以下参数配置：

| 参数名 | 说明 | 默认值 |
|-------|------|-------|
| max_features | 最大特征数量限制 | 5 |
| min_samples | 建模所需最小样本数 | 6 |

> **注意**：已移除`correlation_threshold`参数。系统现在直接选取相关性排序后的前N个特征，而不再使用阈值筛选。

### 参数覆盖机制

系统支持三级参数覆盖：全局 < 数据类型 < 指标级别

```json
{
  "model_params": {  // 全局参数
    "max_features": 5 
  },
  "warning_device": {  // 数据类型级别参数
    "model_params": {
      "max_features": 3  // 覆盖全局设置
    },
    "do": {  // 指标级别参数
      "model_params": {
        "min_samples": 10  // 特定指标的参数
      }
    }
  }
}
```

## 日志系统

系统集成了完善的日志记录功能，所有操作会被记录到`logs`目录下。

通过`autowaterqualitymodeler.utils.logger`模块配置日志系统：

```python
from autowaterqualitymodeler.utils.logger import setup_logging

# 配置日志系统
log_file = setup_logging(log_name="my_task")
```

## 支持的特征计算函数

- `ref(band)`: 获取指定波段的反射率
- `sum(start_band, end_band)`: 计算指定波段范围内的积分值
- `mean(start_band, end_band)`: 计算指定波段范围内的均值
- `abs(value)`: 计算绝对值
- `tris(x/y/z)`: 计算XYZ三刺激值

## 项目结构

```
autowaterqualitymodeler/
│
├── src/                       # 源代码目录
│   ├── __init__.py            # 包初始化文件
│   ├── modeler.py             # 主要的建模类
│   └── spectral_calculator.py # 光谱特征计算器
│
├── utils/                     # 工具函数目录
│   ├── __init__.py            # 包初始化文件
│   ├── encryption.py          # 加密工具
│   └── logger.py              # 日志工具
│
├── config/                    # 配置目录
│   └── features_config.json   # 特征定义配置文件
│
├── resources/                 # 资源文件目录
│   └── D65xCIE.xlsx           # 三刺激值系数表
│
├── run.py                     # 主要入口文件
├── __init__.py                # 包初始化文件
└── _version.py                # 自动生成的版本信息
```

## 版本管理

本项目使用 setuptools_scm 管理版本，版本号自动从Git标签获取。要了解当前版本：

```python
from autowaterqualitymodeler import __version__
print(__version__)
```

## 注意事项

1. 光谱数据列名必须是可转换为浮点数的波长值
2. 建议光谱数据和实测指标数据使用相同的索引以便对齐
3. 模型文件使用AES256加密，请妥善保存密码
4. 必须确保三刺激值系数表在正确位置
5. 当样本量不足时，系统会自动切换到模型微调模式，此时需要提供merged_data参数

## 开发者指南

要参与开发，请安装开发依赖：

```bash
pip install -e ".[dev]"
```

### 发布新版本

1. 确保所有更改已提交
2. 创建版本标签：`git tag vX.Y.Z`
3. 推送标签：`git push origin vX.Y.Z`
4. 构建：`python -m build`
5. 发布：`twine upload dist/*` 
