examples/README.md

# 示例和使用教程

本目录包含了情绪与生理状态变化预测模型的完整示例和使用教程，帮助用户快速上手使用项目。

## 目录结构

```
examples/
├── README.md                    # 本文件 - 示例目录说明
├── sample_data.json            # JSON格式示例数据
├── sample_data.csv             # CSV格式示例数据
├── quick_start.py              # 快速开始教程
├── training_tutorial.py        # 详细训练教程
├── inference_tutorial.py       # 推理教程
├── data/                       # 教程生成的数据目录
├── models/                     # 教程生成的模型目录
├── training_outputs/           # 训练教程输出目录
└── inference_outputs/          # 推理教程输出目录
```

## 文件说明

### 示例数据文件

#### `sample_data.json`
- **格式**: JSON格式，包含10个样本的完整数据
- **内容**: 每个样本包含7维输入特征和5维输出标签
- **用途**: 用于快速测试和演示模型功能

#### `sample_data.csv`
- **格式**: CSV格式，包含20个样本的完整数据
- **内容**: 包含表头，便于批量处理和数据分析
- **用途**: 用于批量测试和数据分析

### 教程脚本

#### `quick_start.py` - 快速开始教程
**目的**: 为新用户提供最简单的上手体验

**功能**:
- 生成合成训练数据
- 训练基础模型
- 进行推理预测
- 解释预测结果

**运行方式**:
```bash
cd examples
python quick_start.py
```

**输出**:
- `examples/data/training_data.csv` - 训练数据
- `examples/models/quick_start_model.pth` - 训练好的模型
- `examples/models/quick_start_preprocessor.pkl` - 数据预处理器

#### `training_tutorial.py` - 详细训练教程
**目的**: 深入演示模型训练的完整流程

**功能**:
- 数据准备和探索性分析
- 数据预处理和特征工程
- 模型配置和架构选择
- 训练过程监控和可视化
- 模型评估和验证
- 超参数调优示例

**运行方式**:
```bash
cd examples
python training_tutorial.py
```

**输出**:
- `examples/training_outputs/` - 训练过程的所有输出文件
  - `train_data.csv`, `val_data.csv`, `test_data.csv` - 数据分割
  - `feature_distribution.png` - 特征分布图
  - `label_distribution.png` - 标签分布图
  - `correlation_heatmap.png` - 相关性热力图
  - `training_curves.png` - 训练曲线
  - `prediction_visualization.png` - 预测结果可视化
  - `preprocessor.pkl` - 数据预处理器
  - `best_model.pth` - 最佳训练模型
  - `training_history.json` - 训练历史记录
  - `evaluation_results.json` - 评估结果
  - `hyperparameter_tuning.json` - 超参数调优结果

#### `inference_tutorial.py` - 推理教程
**目的**: 全面演示模型推理的各种方法和技巧

**功能**:
- 单样本推理
- 批量推理
- 不同输入格式处理（列表、NumPy数组、字典、JSON、CSV）
- 结果解释和可视化
- 性能优化和基准测试
- 实际应用场景演示

**运行方式**:
```bash
cd examples
python inference_tutorial.py
```

**输出**:
- `examples/inference_outputs/` - 推理过程的所有输出文件
  - `single_inference_results.json` - 单样本推理结果
  - `batch_inference_results.json` - 批量推理结果
  - `prediction_distributions.png` - 预测分布对比图
  - `test_input.json`, `test_input.csv` - 测试输入文件
  - `result_interpretations.json` - 结果解释
  - `performance_optimization.json` - 性能优化结果
  - `real_world_scenarios.json` - 实际应用场景结果

## 数据格式说明

### 输入特征（7维）
1. `user_pleasure` (float, [-1, 1]) - 用户快乐度
2. `user_arousal` (float, [-1, 1]) - 用户激活度
3. `user_dominance` (float, [-1, 1]) - 用户支配度
4. `vitality` (float, [0, 100]) - 活力水平
5. `current_pleasure` (float, [-1, 1]) - 当前快乐度
6. `current_arousal` (float, [-1, 1]) - 当前激活度
7. `current_dominance` (float, [-1, 1]) - 当前支配度

### 输出标签（5维）
1. `delta_pleasure` (float, [-0.5, 0.5]) - 快乐度变化量
2. `delta_arousal` (float, [-0.5, 0.5]) - 激活度变化量
3. `delta_dominance` (float, [-0.5, 0.5]) - 支配度变化量
4. `delta_pressure` (float, [-0.3, 0.3]) - 压力变化量
5. `confidence` (float, [0, 1]) - 预测置信度

## 使用建议

### 初学者
1. 从 `quick_start.py` 开始，了解基本流程
2. 查看 `sample_data.json` 了解数据格式
3. 运行 `inference_tutorial.py` 学习推理方法

### 进阶用户
1. 运行 `training_tutorial.py` 学习完整训练流程
2. 修改配置文件进行自定义训练
3. 使用 `inference_tutorial.py` 中的性能优化技巧

### 开发者
1. 参考教程代码集成到自己的项目
2. 使用提供的工具函数进行数据处理
3. 根据实际需求调整模型架构

## 常见问题

### Q: 如何使用自己的数据？
A: 参考 `training_tutorial.py` 中的数据预处理部分，确保数据格式符合要求。

### Q: 如何调整模型架构？
A: 修改 `configs/model_config.yaml` 中的网络架构参数，或直接在代码中修改 `PADPredictor` 的初始化参数。

### Q: 如何提高预测精度？
A: 参考 `training_tutorial.py` 中的超参数调优部分，尝试不同的学习率、批次大小等参数。

### Q: 如何进行批量推理？
A: 使用 `inference_tutorial.py` 中演示的 `predict_batch` 方法。

### Q: 如何解释预测结果？
A: 参考 `inference_tutorial.py` 中的结果解释函数，了解各项指标的含义。

## 依赖要求

运行教程脚本需要安装以下依赖：
- Python 3.8+
- PyTorch
- NumPy
- Pandas
- Matplotlib
- Seaborn
- scikit-learn
- loguru
- PyYAML

安装命令：
```bash
pip install torch numpy pandas matplotlib seaborn scikit-learn loguru pyyaml
```

## 联系方式

如有问题或建议，请通过以下方式联系：
- 项目仓库: [GitHub仓库链接]
- 问题反馈: [Issues链接]
- 文档: [文档链接]

---

**注意**: 这些教程和示例主要用于学习和演示目的。在实际生产环境中使用时，请根据具体需求进行调整和优化。