# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个专门的期货数据分析项目，专注于中国期货市场的成交量-成交价序列可视化分析。项目采用创新的分析方法，通过按累计成交量排序来展示价格在交易过程中的真实变化轨迹。

**项目特色**: 提供高解释力的期货数据可视化工具，相比传统时间序列图表具有更强的业务相关性和决策价值。

## 核心工具

### volume_price_sequence.py
这是项目的主要分析工具，专门用于生成成交量-成交价序列图表。

**功能特性**:
- 按累计成交量升序排列数据
- 生成高解释力的可视化图表
- 提供详细的统计分析和业务洞察
- 支持命令行参数，使用简单

**使用方法**:
```bash
python volume_price_sequence.py [data_file]
python volume_price_sequence.py --help
```

## 数据文件结构

### 数据存储位置
所有数据文件位于 `/data/` 目录下：
- `au2512_20251013.parquet` - AU2512合约2025年10月13日数据 (默认分析文件)
- `au2512_20251013.csv` - AU2512合约CSV格式数据
- `jm2509_20250709.csv` - JM2509合约2025年7月9日数据
- `jm2509_20250710.csv` - JM2509合约2025年7月10日数据
- `jm2509_20250711.csv` - JM2509合约2025年7月11日数据
- `jm2509_20250717.csv` - JM2509合约2025年7月17日数据

### 数据格式
数据包含以下字段（中文表头）：
```
UTC,UTC.1,时间,累积成交量,成交价,成交额,
买1价,卖1价,买1量,卖1量,
买2价,卖2价,买2量,卖2量,
买3价,卖3价,买3量,卖3量,
买4价,卖4价,买4量,卖4量,
买5价,卖5价,买5量,卖5量
```

### 关键字段说明
- `UTC`, `UTC.1`: UTC时间戳（毫秒级）
- `时间`: 当日累计时间（格式：MM:SS.秒，从00:00:00开始）
- `成交价`: 最新成交价格
- `累积成交量`: 当日累计成交量
- `买1价`~`买5价`: 买方五档价格
- `卖1价`~`卖5价`: 卖方五档价格
- `买1量`~`买5量`: 买方五档挂单量
- `卖1量`~`卖5量`: 卖方五档挂单量

## 分析方法

### 核心理念
**为什么选择成交量序列分析？**

传统时间序列的局限性：
- 无法展示交易过程对价格的真实影响
- 时间间隔不均等，影响趋势判断
- 业务解释力有限

成交量序列的优势：
- 清晰展示价格随交易推进的演变轨迹
- 便于识别不同交易阶段的价格水平
- 可以量化成交量对价格的影响
- 更符合期货交易的实际业务逻辑

### 图表输出
生成的图表 `au2512_volume_price_sequence.png` 包含：
- 成交价序列线（蓝色）- 展示价格随成交量变化
- 移动平均线（红色）- 平滑价格趋势
- 价格波动区间（红色阴影）- 显示不确定性范围
- 关键节点标注 - 重要成交量时点的价格信息
- 分析结论框 - 完整的统计摘要

## 项目文件结构

```
jm_ces/
├── volume_price_sequence.py          # 核心分析脚本
├── au2512_volume_price_sequence.png  # 生成的分析图表
├── README.md                         # 项目说明文档
├── CLAUDE.md                         # 本指导文档
└── data/                             # 数据文件目录
    ├── au2512_20251013.parquet       # 默认分析数据
    └── *.csv                          # 其他期货数据文件
```

## 技术要求

### 依赖库
- pandas (数据处理)
- numpy (数值计算)
- matplotlib (数据可视化)

### 系统要求
- Python 3.7+
- 支持中文字体的环境

## 使用指南

### 快速开始
1. 确保安装了必要的依赖库
2. 运行分析脚本：`python volume_price_sequence.py`
3. 查看生成的图表和分析报告

### 高级用法
- 指定不同的数据文件进行分析
- 使用命令行参数自定义输出目录
- 参考详细的README.md文档

## 分析价值

这个工具特别适用于：
- 期货交易策略研究
- 市场微观结构分析
- 价格发现机制研究
- 风险管理和决策支持

相比传统分析方法，成交量序列分析能够提供更具业务洞察力的可视化结果。