# 模型分析工具使用指南

## 概述

本工具包为土壤酸化模型提供了全面的分析和诊断功能，特别针对模型24的性能问题分析。工具包包含两个主要组件：

- **ModelAnalyzer**: 综合性能分析工具
- **ModelDiagnostic**: 问题诊断工具

## 文件结构

```
model_optimize/
├── model_analyzer.py       # 综合性能分析工具
├── model_diagnostic.py     # 问题诊断工具
├── run_analysis.py         # 快速运行脚本
├── README.md              # 使用说明
├── analysis_results/      # 分析结果输出目录
└── diagnostic_results/    # 诊断结果输出目录
```

## 功能特性

### ModelAnalyzer (综合性能分析)

- **模型性能评估**: R²、RMSE、MAE、MAPE等多种指标
- **特征重要性分析**: 模型内置重要性 + 排列重要性
- **预测行为分析**: 用户参数预测 + 预测值分布统计
- **参数敏感性分析**: 各参数对预测结果的影响程度
- **可视化图表**: 散点图、残差图、特征重要性图、敏感性曲线
- **综合报告**: 详细的分析报告和优化建议

### ModelDiagnostic (问题诊断)

- **异常预测检测**: 训练数据异常值检测 + 测试预测异常检测
- **数据分布分析**: 特征分布、目标变量分布、相关性分析
- **模型稳定性测试**: 参数扰动测试、敏感性评估
- **边界条件测试**: 极值情况下的模型表现
- **数据质量检查**: 缺失值、异常值、高相关性检测
- **诊断可视化**: 分布图、箱线图、Q-Q图、相关性热图
- **诊断报告**: 问题识别和改进建议

## 使用方法

### 方法1: 使用快速运行脚本 (推荐)

```bash
cd model_optimize
python run_analysis.py
```

脚本会提供交互式菜单，您可以选择：
1. 综合性能分析
2. 问题诊断分析  
3. 同时执行两种分析
4. 退出

### 方法2: 直接调用分析工具

#### 综合性能分析

```python
from model_analyzer import ModelAnalyzer

# 创建分析器实例
analyzer = ModelAnalyzer()

# 用户参数（来自API调用）
user_params = {
    "OM": 100,
    "CL": 3.1,
    "CEC": 3.44584,
    "H_plus": 0.5,
    "N": 12.4,
    "Al3_plus": 0.8,
    "target_pH": 7.0
}

# 运行完整分析
results = analyzer.run_full_analysis(model_id=24, sample_params=user_params)
```

#### 问题诊断分析

```python
from model_diagnostic import ModelDiagnostic

# 创建诊断器实例
diagnostic = ModelDiagnostic()

# 运行完整诊断
results = diagnostic.run_full_diagnostic(model_id=24, test_params=user_params)
```

## 输出结果

### 分析结果文件

所有分析结果会保存在相应目录中：

- `analysis_results/`: 性能分析结果
  - 散点图: `model_24_scatter_YYYYMMDD_HHMMSS.png`
  - 残差图: `model_24_residuals_YYYYMMDD_HHMMSS.png`
  - 特征重要性图: `model_24_feature_importance_YYYYMMDD_HHMMSS.png`
  - 敏感性分析图: `model_24_sensitivity_YYYYMMDD_HHMMSS.png`
  - 敏感性曲线: `model_24_sensitivity_curves_YYYYMMDD_HHMMSS.png`
  - 分析报告: `model_24_analysis_report_YYYYMMDD_HHMMSS.txt`

- `diagnostic_results/`: 诊断结果
  - 数据分布图: `model_24_data_distribution_YYYYMMDD_HHMMSS.png`
  - 异常值分析图: `model_24_outlier_analysis_YYYYMMDD_HHMMSS.png`
  - 敏感性图: `model_24_sensitivity_YYYYMMDD_HHMMSS.png`
  - 相关性矩阵: `model_24_correlation_YYYYMMDD_HHMMSS.png`
  - 诊断报告: `model_24_diagnostic_report_YYYYMMDD_HHMMSS.txt`

### 报告内容示例

#### 分析报告包含：
- 模型基本信息
- 性能指标详情 (R²、RMSE、MAE等)
- 特征重要性排序
- 参数敏感性排序
- 用户参数预测结果
- 优化建议

#### 诊断报告包含：
- 异常检测结果
- 数据质量分析
- 稳定性测试结果
- 边界条件测试
- 问题诊断和改进建议

## 针对模型24的分析

基于您提供的API调用参数：
```json
{
    "model_id": "24",
    "parameters": {
        "OM": 100,
        "CL": 3.1,
        "CEC": 3.44584,
        "H_plus": 0.5,
        "N": 12.4,
        "Al3_plus": 0.8
    }
}
```

工具会自动：
1. 加载模型24的信息和文件
2. 确定模型数据类型 (reduce/reflux)
3. 加载相应的训练/测试数据
4. 对用户参数进行预测和分析
5. 生成详细的分析和诊断报告

## 依赖环境

确保安装了以下Python包：
```bash
pip install pandas numpy matplotlib seaborn scikit-learn scipy sqlite3
```

## 注意事项

1. **数据库路径**: 工具默认使用 `SoilAcidification.db`，确保文件存在
2. **模型文件**: 确保模型pickle文件路径正确
3. **测试数据**: 需要存在对应的测试数据文件 (`uploads/data/X_test_*.csv`, `uploads/data/Y_test_*.csv`)
4. **权限**: 确保有创建输出目录和写入文件的权限

## 故障排除

### 常见问题

1. **模型文件不存在**
   - 检查数据库中模型的 `ModelFilePath` 字段
   - 确保pkl文件确实存在于指定路径

2. **测试数据加载失败**
   - 检查 `uploads/data/` 目录下是否有对应的CSV文件
   - 确保文件格式正确

3. **中文字体显示问题**
   - 图表可能无法正确显示中文标签
   - 这不影响分析功能，只是显示问题

### 调试模式

如需查看详细的调试信息，在代码中设置：
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

## 扩展使用

### 分析其他模型

修改 `run_analysis.py` 中的 `model_id` 参数：
```python
model_id = 25  # 改为其他模型ID
```

### 批量分析

可以编写循环来分析多个模型：
```python
for model_id in [24, 25, 26]:
    analyzer.run_full_analysis(model_id, user_params)
```

### 自定义参数

修改 `user_params` 字典来测试不同的参数组合：
```python
user_params = {
    "OM": 50,      # 修改有机质含量
    "CL": 2.5,     # 修改粘土含量
    # ... 其他参数
}
```

## 技术支持

如有问题，请检查：
1. 控制台输出的错误信息
2. 生成的日志文件
3. 确保所有依赖文件都存在

---

**使用愉快！此工具将帮助您深入了解模型24的性能特征和潜在问题。**