analyze/README.md

# 🔬 实验对比分析工具

这个目录包含用于对比和分析实验结果的通用工具。

## 📂 目录结构

```
analyze/
├── src/                           # 分析脚本源代码
│   ├── compare_experiments.py     # 通用实验对比工具
│   └── analyze_aux_metrics.py     # 辅助指标分析工具
├── outputs/                       # 默认输出目录（分析结果）
├── run.sh                         # 快速运行实验对比示例
├── run_aux_analysis.sh            # 快速运行辅助指标分析示例
├── example_usage.sh               # 使用示例脚本
└── README.md                      # 本文件
```

## 🚀 快速开始

### 基本用法

对比两个实验run（结果会自动保存到 `analyze/outputs/`）：

```bash
python analyze/src/compare_experiments.py \
  examples/circle_packing/results/exp1_dir \
  examples/circle_packing/results/exp2_dir
```

### 使用 tag 参数组织输出

**推荐方式**：使用 `--tag` 参数将结果保存到 `analyze/outputs/TAG/` 子目录：

```bash
python analyze/src/compare_experiments.py \
  path/to/exp1 \
  path/to/exp2 \
  --tag vision_comparison
```

输出位置：`analyze/outputs/vision_comparison/`

### 使用自定义标签

```bash
python analyze/src/compare_experiments.py \
  path/to/exp1 \
  path/to/exp2 \
  --labels "实验A" "实验B" \
  --tag experiment_a_vs_b
```

### 完全自定义输出目录

如果需要完全自定义输出路径（不在 analyze/outputs 下）：

```bash
python analyze/src/compare_experiments.py \
  path/to/exp1 \
  path/to/exp2 \
  --labels "WITH Vision" "WITHOUT Vision" \
  --output-dir custom/path/my_comparison
```

## 📊 输出内容

每次运行会在指定的输出目录生成：

1. **`comparison_plots.png`** - 包含4个子图的可视化对比：
   - **分数演化曲线** - 两个实验随代数的最佳分数变化
   - **达到分数里程碑所需代数** - 对比达到不同分数阈值（每0.5划分）所需的代数（越低越好）
   - **分数分布直方图** - 所有代数分数的分布情况
   - **累积最优曲线** - 历史最佳分数的演化

2. **`comparison_results.json`** - 详细的对比数据（JSON格式）：
   - 每个实验的统计信息
   - 对比结果和改进百分比
   - 实验元信息

## 🔧 完整参数

```bash
python analyze/src/compare_experiments.py [-h] 
  exp1_path exp2_path 
  [--labels LABEL1 LABEL2]
  [--tag TAG]
  [--output-dir OUTPUT_DIR]
  [--threshold THRESHOLD]
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `exp1_path` | 第一个实验的结果目录 | 必需 |
| `exp2_path` | 第二个实验的结果目录 | 必需 |
| `--labels` | 两个实验的自定义标签 | 从目录名生成 |
| `--tag` | 输出子目录标签（结果保存到 `analyze/outputs/TAG/`） | `None` |
| `--output-dir` | 完全自定义输出目录（优先级高于 `--tag`） | `analyze/outputs` 或 `analyze/outputs/TAG` |
| `--threshold` | 重大改进的阈值 | `0.05` |

**输出目录优先级**：`--output-dir` > `--tag` > 默认 (`analyze/outputs`)

## 📝 使用示例

### 示例1: 对比有无Vision（使用 tag）

```bash
python analyze/src/compare_experiments.py \
  examples/circle_packing/results/results_circle_packing_WITH_vision_20260114_065819 \
  examples/circle_packing/results/results_circle_packing_WITHOUT_vision_20260114_070110 \
  --labels "WITH Vision" "WITHOUT Vision" \
  --tag vision_comparison
```

输出：
- `analyze/outputs/vision_comparison/comparison_plots.png`
- `analyze/outputs/vision_comparison/comparison_results.json`

### 示例2: 对比不同辅助指标配置

```bash
python analyze/src/compare_experiments.py \
  examples/circle_packing/results/results_circle_packing_NO_vision_WITH_aux_20260118_072141 \
  examples/circle_packing/results/results_circle_packing_NO_vision_WITH_refined_aux_20260118_205215 \
  --labels "All 7 Metrics" "Refined 4 Metrics" \
  --tag aux_7vs4
```

输出：
- `analyze/outputs/aux_7vs4/comparison_plots.png`
- `analyze/outputs/aux_7vs4/comparison_results.json`

### 示例3: 快速对比（使用默认设置）

```bash
python analyze/src/compare_experiments.py \
  path/to/exp1 \
  path/to/exp2
```

输出直接保存到 `analyze/outputs/`

### 示例4: 使用 uv 运行

```bash
uv run python analyze/src/compare_experiments.py \
  exp1 exp2 \
  --labels "A" "B" \
  --tag experiment_a_vs_b
```

## 🎯 功能特性

✅ **灵活** - 接受任意两个实验目录作为输入  
✅ **智能** - 自动在多种目录结构中查找数据库  
✅ **可视化** - 生成4个专业的对比图表，包括创新的里程碑达成对比  
✅ **详细** - 输出完整的统计对比和时序分析  
✅ **导出** - JSON格式方便后续处理  

### 📈 里程碑图表说明

**Generations to Reach Score Milestones** 图表特别有用，它显示：
- X轴：分数阈值（按0.5递增，如1.0, 1.5, 2.0, 2.5...）
- Y轴：达到该阈值所需的代数
- 对比：两个实验并排对比，可以清楚看出哪个实验更快达到特定分数
- **越低越好** - 柱子越短表示越快达到目标分数  

## 📄 屏幕输出示例

```
================================================================================
🔬 ANALYZING EXPERIMENTS: WITH Vision vs WITHOUT Vision
================================================================================

📁 Experiment 1: examples/circle_packing/results/results_circle_packing_WITH_vision_...
📁 Experiment 2: examples/circle_packing/results/results_circle_packing_WITHOUT_vision_...
📂 Output Dir:   analyze/outputs

🔍 Finding database files...
   ✅ WITH Vision: evolution_db_circle_packing_WITH_vision_20260114_065819.sqlite
   ✅ WITHOUT Vision: evolution_db_circle_packing_WITHOUT_vision_20260114_070110.sqlite

📊 Loading experiment data...
   ✅ Loaded 1250 programs from WITH Vision
   ✅ Loaded 1180 programs from WITHOUT Vision

================================================================================
📊 EXPERIMENT COMPARISON: WITH Vision vs WITHOUT Vision
================================================================================

🎯 FINAL RESULTS:
   WITH Vision         : 2.5786
   WITHOUT Vision      : 2.5507
   Improvement:         +1.09% ✅ WITH Vision Better

📈 STATISTICS:
┌─────────────────────────────────────────────┬──────────────────┬──────────────────┐
│ Metric                                      │   WITH Vision    │  WITHOUT Vision  │
├─────────────────────────────────────────────┼──────────────────┼──────────────────┤
│ Total Programs                              │             1250 │             1180 │
│ Correct Programs                            │              985 │              920 │
...
└─────────────────────────────────────────────┴──────────────────┴──────────────────┘

🏆 KEY MILESTONES:
...

⏱️  IMPROVEMENT TIMING ANALYSIS:
...

🎨 Generating comparison plots...
📊 Plots saved to: analyze/outputs/comparison_plots.png

💾 Saving detailed comparison data...
   ✅ JSON saved to: analyze/outputs/comparison_results.json

================================================================================
✅ ANALYSIS COMPLETE!
================================================================================

📊 Output files:
   • Plots: analyze/outputs/comparison_plots.png
   • Data:  analyze/outputs/comparison_results.json

🏆 Winner: WITH Vision (by 1.09%)
```

## 🆘 故障排除

### 找不到数据库文件

**错误**：`No database file found in: path/to/experiment`

**解决**：确保实验目录包含 `evolution_db_*.sqlite` 文件

### 路径不存在

**错误**：`Results directory not found: path/to/experiment`

**解决**：检查路径是否正确，使用绝对路径或从项目根目录的相对路径

## 📚 相关工具

在 `my/` 目录下还有其他专用的分析脚本：
- `compare_aux_experiments.py` - 专门对比辅助指标实验
- `analyze_vision_results.py` - 专门对比vision实验
- `plot_latest_results.py` - 自动找最新实验对比

本工具 (`compare_experiments.py`) 是**最通用和灵活**的版本，推荐优先使用。

---

## 🔍 辅助指标分析工具

### 工具2: `analyze_aux_metrics.py`

专门分析单个实验中辅助指标（auxiliary metrics）的演化和与主要分数的相关性。

#### 快速开始

```bash
python analyze/src/analyze_aux_metrics.py \
  path/to/experiment \
  --tag aux_analysis
```

#### 功能特性

1. **📈 指标演化分析** - 展示每个辅助指标随代数的变化趋势
2. **🔗 相关性分析** - 计算每个辅助指标与主要分数（combined_score）的Pearson相关系数
3. **📊 可视化对比** - 自动生成3个详细的分析图表
4. **📉 统计显著性** - 提供p值和显著性标记（***, **, *, ns）

#### 输出内容

生成3个PNG图表和1个JSON数据文件：

1. **`aux_metrics_evolution.png`**
   - 所有辅助指标的演化曲线（多子图）
   - 每个指标包含趋势线
   
2. **`aux_metrics_correlation.png`**
   - 相关性条形图（按绝对值排序）
   - Top 4指标的散点图和回归线
   - 颜色编码表示代数
   
3. **`score_and_top_metrics.png`**
   - 主要分数演化
   - Top 3辅助指标演化（归一化）
   
4. **`aux_metrics_correlation.json`**
   - 完整的相关性数据
   - 分类统计（强正相关、弱正相关等）

#### 使用示例

```bash
# 基本用法
python analyze/src/analyze_aux_metrics.py \
  examples/circle_packing/results/results_circle_packing_NO_vision_WITH_aux_20260118_072141

# 使用tag组织输出
python analyze/src/analyze_aux_metrics.py \
  path/to/experiment \
  --tag my_aux_analysis

# 指定自定义标签
python analyze/src/analyze_aux_metrics.py \
  path/to/experiment \
  --label "My Experiment" \
  --tag aux_metrics
```

#### 快速运行

```bash
# 运行预配置的示例
bash analyze/run_aux_analysis.sh
```

#### 相关性解读

- **强正相关 (>0.7)**: 该指标与分数高度一致，可能是有效的优化目标
- **弱负相关 (<-0.4)**: 该指标可能与主要目标冲突，建议移除
- **显著性标记**:
  - `***` p < 0.001 (高度显著)
  - `**` p < 0.01 (显著)
  - `*` p < 0.05 (边缘显著)
  - `ns` 不显著