technical-patterns-lab/USAGE.md

# 使用说明

## 快速启动

```powershell
.\.venv\Scripts\Activate.ps1
python scripts/pipeline_converging_triangle.py
```

**新功能**：清空输出目录并重新生成（确保使用最新算法）
```powershell
# 完整重新生成（清空旧数据） | CSV：所有108只股票的检测结果（包括不满足条件的）图表：只为满足条件的股票生成（比如31只）HTML：只显示满足条件的31只
python scripts/pipeline_converging_triangle.py --clean

# 清空后为所有股票生成图表 | CSV：所有108只股票的检测结果 图表：为所有108只股票生成图（包括不满足条件的）满足条件的：完整收敛三角形图 + 强度分 不满足条件的：基础K线图 + 强度分=0 HTML：显示所有108只股票
python scripts/pipeline_converging_triangle.py --clean --all-stocks

# 清空后指定日期生成
python scripts/pipeline_converging_triangle.py --clean --date 20260120 --all-stocks
```

**为所有108只股票生成图表**（包括不满足条件的）
```powershell
# 生成所有股票的图表，每个都显示强度分
python scripts/pipeline_converging_triangle.py --all-stocks

# 指定日期，生成所有股票的图表
python scripts/pipeline_converging_triangle.py --date 20260120 --all-stocks
```

## 1. 创建与激活虚拟环境

```powershell
# 创建环境（首次）
python -m venv .venv

# 激活环境
.\.venv\Scripts\Activate.ps1
```

## 2. 安装依赖

```powershell
pip install numpy pandas matplotlib
```

## 3. 运行脚本

### 一键流水线（推荐）

```powershell
python scripts/pipeline_converging_triangle.py
```

常用参数：

```powershell
# 指定日期
python scripts/pipeline_converging_triangle.py --date 20260120

# 生成详情模式图片（显示所有枢轴点和拟合点）
python scripts/pipeline_converging_triangle.py --show-details

# 为所有108只股票生成图表（包括不满足收敛三角形条件的）
python scripts/pipeline_converging_triangle.py --all-stocks

# 组合使用
python scripts/pipeline_converging_triangle.py --date 20260120 --show-details --all-stocks

# 跳过检测（仅生成报告与图表）
python scripts/pipeline_converging_triangle.py --skip-detection
```

**参数说明**：
- `--all-stocks`：为所有108只股票生成图表
  - 满足条件的：显示完整的收敛三角形和强度分
  - 不满足条件的：显示基础K线图，强度分为0
  - 适合全面查看整个股票池的情况

### 仅批量检测

```powershell
python scripts/run_converging_triangle.py
```

### 仅生成报告

```powershell
python scripts/report_converging_triangles.py
```

### 仅绘制图表

**K线图模式**（默认）：使用K线图展示价格走势

```powershell
# 简洁模式（默认）- 仅显示K线、上沿、下沿
# 文件名格式: YYYYMMDD_股票代码_股票名称.png
python scripts/plot_converging_triangles.py

# 详细模式 - 额外显示所有枢轴点、拟合点
# 文件名格式: YYYYMMDD_股票代码_股票名称_detail.png
python scripts/plot_converging_triangles.py --show-details

# 为所有108只股票生成图表（包括不满足条件的）
python scripts/plot_converging_triangles.py --all-stocks

# 指定日期
python scripts/plot_converging_triangles.py --date 20260120

# 组合使用：所有股票 + 详细模式
python scripts/plot_converging_triangles.py --all-stocks --show-details

# 同时生成两种模式进行对比（先后运行两次）
python scripts/plot_converging_triangles.py              # 生成简洁版
python scripts/plot_converging_triangles.py --show-details # 生成详细版

# 边界线拟合选项（默认使用高低价）
python scripts/pipeline_converging_triangle.py --plot-boundary-source hl      # 使用高低价（默认，推荐）
python scripts/pipeline_converging_triangle.py --plot-boundary-source close   # 使用收盘价
```

**提示**: 
- 简洁模式和详细模式的文件名不同（详细模式带 `_detail` 后缀），两种模式的图表会同时保留，方便对比查看
- `--all-stocks` 会为所有108只股票生成图表，每个都显示强度分（不满足条件的显示0分）
- **K线图说明**：红色实体=涨，绿色实体=跌，影线显示最高最低价
- **边界线拟合**：默认使用高低价拟合（更精确），也可选择收盘价拟合（更平滑）

输出（已被 `.gitignore` 忽略，默认不推送远程）：
- `outputs/converging_triangles/all_results.csv` - 所有检测结果
- `outputs/converging_triangles/daily_best.csv` - 每日最佳股票（新增）
- `outputs/converging_triangles/strong_breakout_up.csv` - 向上强突破
- `outputs/converging_triangles/strong_breakout_down.csv` - 向下强突破
- `outputs/converging_triangles/report.md` - 检测报告
- `outputs/converging_triangles/charts/*.png` - K线图（新增）
- `outputs/converging_triangles/stock_viewer.html` - 可视化查看器
- `outputs/converging_triangles/run_log_*.txt` - 运行日志（新增）

## 4. 参数调整

编辑 `scripts/triangle_config.py`（统一配置）：

```python
DETECTION_PARAMS = ConvergingTriangleParams(
    window=120,        # 检测窗口大小
    pivot_k=15,        # 枢轴点检测窗口
    shrink_ratio=0.6,  # 收敛比阈值（严格模式）
    # ...
)

# 实时模式配置
REALTIME_MODE = True      # True=实时模式（默认），False=标准模式
FLEXIBLE_ZONE = 5         # 灵活区域大小（最近5天）

# 显示配置
RECENT_DAYS = 500         # 计算最近 N 天（None=全部历史）
DISPLAY_WINDOW = 500      # 图表显示范围
ONLY_VALID = True         # 只输出有效三角形
SHOW_CHART_DETAILS = False  # 图表详细模式（False=简洁，True=详细）
```

### 实时模式 vs 标准模式

- **实时模式**（推荐，默认）：
  - ✅ 能捕获最近的枢轴点（无15天滞后）
  - ✅ 适合实时选股
  - ⚠️ 候选枢轴点置信度较低

- **标准模式**：
  - ✅ 枢轴点质量高（完整窗口确认）
  - ✅ 适合历史回测
  - ⚠️ 有15天确认滞后

### 图表详细模式

- **简洁模式**（默认，`SHOW_CHART_DETAILS = False`）：
  - 仅显示收盘价、上沿线、下沿线
  - 图表清爽，适合日常使用

- **详细模式**（`SHOW_CHART_DETAILS = True` 或命令行 `--show-details`）：
  - 额外显示所有枢轴点、拟合点、分段线
  - 便于理解算法逻辑和调试

## 5. 数据格式

数据文件位于 `data/` 目录，格式为 pkl：

```python
{
    'mtx': ndarray (n_stocks, n_days),  # 数据矩阵
    'dtes': ndarray (n_days,),          # 日期 (20050104)
    'tkrs': ndarray (n_stocks,),        # 股票代码 (SH600000)
    'tkrs_name': ndarray (n_stocks,),   # 股票名称
}
```

## 6. 备注

### 📊 可视化查看器

使用浏览器打开 `outputs/converging_triangles/stock_viewer.html` 可以：
- 🎚️ 通过滑块调整强度分阈值，实时筛选股票
- 📈 查看所有股票的详细指标和图表
- 🔍 点击图表可放大查看细节
- 📊 实时显示统计信息（总数、筛选数、平均强度分）
- ✨ 支持两种模式：显示所有108只股票 或 仅满足条件的股票

**使用方法**：
```powershell
# 方式1：一键生成所有数据和HTML查看器（显示所有108只股票）
python scripts/pipeline_converging_triangle.py --all-stocks

# 方式2：单独重新生成HTML
python scripts/generate_stock_viewer.py --all-stocks  # 显示所有108只
python scripts/generate_stock_viewer.py              # 仅显示满足条件的

# 方式3：指定日期
python scripts/generate_stock_viewer.py --date 20260120 --all-stocks

# 打开查看器
start outputs/converging_triangles/stock_viewer.html
```

**特点**：
- 📦 数据内嵌在HTML中，可直接双击打开，无需服务器
- 🚀 响应式设计，自适应各种屏幕尺寸
- 🎨 紫色渐变主题，视觉效果优雅
- ⚡ 实时过滤和统计，性能优秀

详见：`outputs/converging_triangles/README_viewer.md` 或 `outputs/converging_triangles/QUICK_START.md`

---

- 关闭环境：`deactivate`
- 权限问题（PowerShell）：
  ```powershell
  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  ```