# 期货市场研究算法库

## 概述
本目录包含期货市场的各种研究算法和分析工具，用于量化分析期货市场的技术指标、价格走势和交易策略。所有代码基于聚宽API开发，适用于聚宽在线研究平台。

## 算法文件结构

### 1. 期货多均线穿越分析 (`future_ma_cross_analysis.py`)

#### 功能描述
分析期货合约的多均线穿越事件，识别同时穿越至少3条均线的K线，并分析后续收益表现。

#### 主要特点
- **多均线系统**: 使用MA5、MA10、MA20、MA30四条移动平均线
- **穿越识别**: 精确判断K线实体上穿或下穿至少3条均线
- **后续跟踪**: 分析穿越后5日、10日、20日、30日的收益率表现
- **批量处理**: 自动分析所有期货主力合约

#### 核心算法
```python
def check_multi_ma_cross(row):
    """检查单日K线是否向上或向下穿越了至少3条均线"""
    # 条件：开盘价在均线一侧，收盘价在均线另一侧
    # 上穿：开盘价 < 均线 且 收盘价 > 均线
    # 下穿：开盘价 > 均线 且 收盘价 < 均线
```

#### 输出结果
- CSV文件：包含所有穿越事件的详细信息和后续收益率
- 统计报告：穿越方向分布、收益率统计、品种统计等

### 2. 期货市场整体变化趋势分析 (`future_all_change_trend.py`)

#### 功能描述
分析期货市场整体的价格变化趋势，计算每日市场平均变化率和正负变化分布。

#### 主要特点
- **市场全貌**: 分析所有期货品种的价格变化
- **趋势识别**: 计算滚动平均值识别市场趋势
- **异常检测**: 使用标准差检测异常市场波动
- **可视化**: 生成趋势图表展示市场变化规律

#### 核心算法
```python
def process_data(df, std_dev_multiplier=3):
    """处理数据并过滤异常值"""
    # 计算每日平均变化率
    # 统计正负变化数量
    # 计算滚动平均值
    # 过滤异常值
```

#### 输出结果
- 每日市场平均变化率
- 正负变化品种数量统计
- 滚动平均值和趋势图表
- 异常市场行为检测报告

### 3. 期货技术形态规律分析 (`future_pattern_comprehensive.py`)

#### 功能描述
**核心研究项目** - 研究期货品种在大幅下跌后出现特定K线形态的规律，并分析后续走势表现。这是一个综合性的技术形态分析工具。

#### 主要特点
- **全自动化**: 从数据获取到结果输出全程自动化
- **多维度筛选**: 结合回撤、K线形态、时间位置等条件
- **量化验证**: 通过10周跟踪验证形态有效性
- **可视化展示**: 自动生成K线图标记技术形态
- **综合集成**: 单文件包含配置、分析、测试全部功能

#### 文件结构
```
第一部分：分析配置参数 (AnalysisConfig类)
第二部分：技术形态分析器主类 (FuturePatternAnalyzer类)  
第三部分：测试和演示代码 (PatternAnalysisTests类)
第四部分：主程序入口 (main函数)
```

#### 分析流程
1. **构建期货品种数据**: 创建80+个期货品种的8888主连合约代码
2. **筛选大幅下跌品种**: 识别最大回撤>30%的期货品种
3. **获取主力合约映射**: 获取下跌期间的主力合约变化
4. **获取周线K线数据**: 扩展时间范围的周线OHLCV数据
5. **识别目标K线形态**: 十字星+长上影线组合形态识别
6. **分析后续10周走势**: 量化跟踪后续收益率表现
7. **生成可视化图表**: K线图展示和统计报告
8. **保存分析结果**: 完整的CSV数据文件输出

#### 技术形态条件
- **条件A**: 开盘价与收盘价差异 ≤ 1% (十字星特征)
- **条件B**: 最高价相对开盘价涨幅 ≥ 3% (长上影线特征)
- **位置条件**: 形态出现在大幅下跌期间或附近

#### 配置参数
```python
# 时间设置
START_DATE = '2022-01-01'  # 建议至少2年数据
END_DATE = '2024-12-31'

# 筛选条件
MIN_DRAWDOWN_THRESHOLD = 0.30  # 30%最小回撤
KLINE_CONDITIONS = {
    'max_open_close_diff': 0.01,  # 1%开收差异
    'min_high_open_gain': 0.03,   # 3%最高涨幅
}

# 分析参数
FOLLOW_UP_WEEKS = 10           # 后续跟踪10周
SUCCESS_RETURN_THRESHOLD = 0.05 # 5%成功率阈值
```

#### 支持的期货品种
- **大商所(XDCE)**: A、B、C、I、J、JM、L、M、P、PP、V、Y等
- **郑商所(XZCE)**: AP、CF、FG、MA、RM、SR、TA、ZC等
- **上期所(XSGE)**: AG、AL、AU、CU、RB、RU、ZN等
- **中金所(CCFX)**: IC、IF、IH、T、TF、TS
- **广期所(GFEX)**: SI、LC
- **上海国际能源(XINE)**: SC、BC、LU、NR

#### 使用方法
```python
# 基本使用 - 完整分析
results = run_pattern_analysis(mode='full')

# 快速测试
results = run_pattern_analysis(mode='quick')

# 自定义参数测试
results = run_pattern_analysis(mode='custom')

# 逐步功能测试
run_pattern_analysis(mode='step')

# 直接使用分析器类
analyzer = FuturePatternAnalyzer('2022-01-01', '2024-12-31')
results = analyzer.run_full_analysis()
```

#### 输出文件
- `future_major_decline_YYYYMMDD_HHMMSS.csv` - 大幅下跌期货品种
- `future_kline_patterns_YYYYMMDD_HHMMSS.csv` - 识别的K线形态
- `future_pattern_performance_YYYYMMDD_HHMMSS.csv` - 后续走势分析
- `future_pattern_summary_YYYYMMDD_HHMMSS.csv` - 统计汇总
- `kline_pattern_{品种}_{日期}.png` - K线图表

#### 性能统计示例
```
=== 期货技术形态规律分析报告 ===
总分析期货品种数: 85
大幅下跌品种数: 12
识别出的目标形态数: 8
完成后续走势分析数: 8

=== 后续走势统计分析 ===
10周内最高收益率统计:
  平均值: 15.32%
  正收益比例: 7/8 (87.5%)

=== 交易成功率分析 ===
成功率: 75.0%
```

### 4. 期货烛台影线形态分析 (`future_candlestick_hatch_analysis.py`)

#### 功能描述
分析期货合约中带有明显影线的K线，识别具备预测价值的烛台形态，并分析它们对未来价格走势的预测能力。

#### 主要特点
- **形态识别**: 识别带有明显影线且实体长度符合要求的K线
- **双向过滤**: 主影线长度必须超过实体1.2倍，相反影线必须小于实体0.5倍
- **交易信号**: 上影线做空信号，下影线做多信号
- **未来跟踪**: 分析形态出现后N个交易日的价格表现
- **主力合约**: 自动识别和使用主力合约数据

#### 核心算法
```python
# 形态识别条件
def check_hatch_pattern(row, body_threshold, hatch_ratio=1.2, opposite_ratio=0.5):
    """检查K线是否符合影线形态条件"""
    body_length = abs(close - open)
    upper_hatch = high - max(open, close)
    lower_hatch = min(open, close) - low
    
    # 条件1: 实体长度 >= 历史平均实体长度
    # 条件2: 主影线长度 >= 1.2 × 实体长度  
    # 条件3: 相反影线长度 < 0.5 × 实体长度
```

#### 交易逻辑
- **上影线形态**: 做空信号
  - 收益计算：(收盘价 - 未来最高价) / 收盘价
  - 预期：价格向影线相反方向（下跌）移动
- **下影线形态**: 做多信号  
  - 收益计算：(未来最高价 - 收盘价) / 收盘价
  - 预期：价格向影线相反方向（上涨）移动

#### 配置参数
```python
class CandlestickHatchConfig:
    ANALYSIS_START_DATE = datetime.datetime(2025, 8, 1)   # 分析开始日期
    ANALYSIS_END_DATE = datetime.datetime(2025, 8, 20)    # 分析结束日期
    HISTORICAL_DAYS = 365                                 # 历史数据回溯期
    FORWARD_DAYS = 15                                     # 前向分析期
    FUTURE_MONITOR_DAYS = 10                              # 未来表现跟踪期
    HATCH_TO_BODY_RATIO = 1.2                            # 影线与实体长度比率阈值
    OPPOSITE_HATCH_RATIO = 0.5                           # 相反影线与实体长度比率阈值
    MAX_REVENUE_THRESHOLD = 0.02                         # 最大盈利阈值
    MAX_LOSS_THRESHOLD = 0.005                           # 最大亏损阈值
    MAX_ANALYSIS_CONTRACTS = 10                          # 最大分析合约数
    # 交易仓位管理参数
    INITIAL_TRADE_AMOUNT = 20000                         # 初始交易金额
    LOSS_RATE = 0.01                                    # 亏损交易的亏损率
    PROFIT_DRAWDOWN_RATE = 0.02                         # 盈利交易的回撤率
```

#### 数据结构
```python
# 主力合约数据结构 (dict1)
contract_data = {
    'L2601.XDCE': [开始日期, 结束日期],
    'A2505.XDCE': [开始日期, 结束日期]
}

# 影线形态数据结构 (dict2)
pattern_data = {
    'L2601.XDCE': {
        datetime.date(2025, 8, 5): {
            'date': '2025-08-05',
            'high': 6520.0, 'low': 6450.0, 'open': 6480.0, 'close': 6500.0,
            'body_len': 20.0, 'hatch_dire': 'up', 'hatch_len': 50.0,
            'max_revenue_date': '2025-08-08', 'max_revenue': 0.0234,
            'min_revenue_date': '2025-08-06', 'min_revenue': -0.0156,
            'conclusion': 'true',  # 形态有效性判断
            'body_direction': 'up',  # 实体方向
            'direction_consistency': 'false'  # 方向一致性
        }
    }
}
```

#### 形态有效性判断（增强版）
系统自动为每个识别的形态计算`conclusion`字段，判断逻辑：
- **有效 (true)**：满足以下任一条件且无早期过度损失
  1. 最大盈利日期 < 最大亏损日期 且 最大盈利 > 2%
  2. 最大盈利日期 > 最大亏损日期 且 最大盈利 > 2% 且 最大亏损 < 0.5%
- **增强条件**：如果在最大收益日期之前的任何一天，损失超过了最大亏损阈值(0.5%)，则标记为无效
- **无效 (false)**：不满足上述条件或存在早期过度损失

#### 新增分析字段
- **body_direction**: 烛台实体方向
  - 'up': 收盘价 > 开盘价（阳线）
  - 'down': 收盘价 < 开盘价（阴线） 
  - 'flat': 收盘价 = 开盘价（十字星）
- **direction_consistency**: 实体与影线方向一致性
  - 'true': 实体方向与影线方向相反（符合预期）
  - 'false': 实体方向与影线方向不相反
- **动态仓位管理**: 基于交易结果的资金管理
  - 初始交易金额：20,000（可配置）
  - 亏损交易：按1%亏损率调整资金（可配置）
  - 盈利交易：按最大利润减去2%回撤率调整资金（可配置）
- **移动平均线分析**: 形态形成日的技术指标
  - MA5、MA10、MA20、MA30：5日、10日、20日、30日移动平均线
  - trend_strength：趋势强度评估（强趋势/中趋势/弱趋势/震荡/数据不足）
- **hatch/body比率**: 影线与实体长度的比率，用于量化形态强度

#### 使用方法
```python
# 基本使用
results = run_candlestick_hatch_analysis()

# 自定义配置
class CustomConfig(CandlestickHatchConfig):
    HATCH_TO_BODY_RATIO = 1.5       # 更严格的影线要求
    OPPOSITE_HATCH_RATIO = 0.3      # 更严格的相反影线要求
    MAX_REVENUE_THRESHOLD = 0.03    # 更高的盈利阈值要求
    MAX_LOSS_THRESHOLD = 0.003      # 更低的亏损容忍度
    FUTURE_MONITOR_DAYS = 15        # 更长的跟踪期

results = run_candlestick_hatch_analysis(CustomConfig)
```

#### 输出结果
- **CSV文件**: `future_candlestick_hatch_analysis_YYYYMMDD_HHMMSS.csv`
- **包含字段**（按输出顺序）: 
  - contract_code：合约代码
  - date：形态日期
  - conclusion：有效性判断（true/false）
  - trend_strength：趋势强度评估
  - body_direction：实体方向
  - direction_consistency：方向一致性
  - body_len：实体长度
  - hatch_len：影线长度  
  - hatch/body：影线与实体长度比率
  - close：收盘价
  - open：开盘价
  - high：最高价
  - low：最低价
  - ma5：5日移动平均线
  - ma10：10日移动平均线
  - ma20：20日移动平均线
  - ma30：30日移动平均线
  - max_revenue：最大收益率
  - max_revenue_date：最大收益日期
  - min_revenue：最大亏损率
  - min_revenue_date：最大亏损日期
  - profit_loss：单笔盈亏
  - remaining_amount：剩余资金
  - trade_amount：交易金额
- **投资组合汇总**: 整体交易表现统计，包括成功率、总盈亏、总回报率等

#### 统计指标
- **检测形态总数**：识别出的符合条件的影线形态数量
- **有效形态数**：conclusion为'true'的形态数量
- **有效率**：有效形态占总形态的百分比

#### 分析流程
1. **构建主力合约数据结构**: 获取分析期间的主力合约变化
2. **收集扩展数据**: 获取历史和未来的OHLC数据
3. **计算实体长度阈值**: 使用历史数据计算平均实体长度
4. **识别影线形态**: 筛选符合双重条件的K线
5. **分析未来表现**: 跟踪形态后N天的价格走势
6. **计算有效性判断**: 根据收益时序关系评估形态预测能力
7. **生成分析结果**: 输出包含有效性判断的完整CSV数据文件

## 技术架构

### 数据源
- **聚宽API**: 使用jqdata获取期货价格数据
- **数据频率**: 支持日线和周线数据
- **数据字段**: OHLCV (开高低收量)

### 核心库依赖
```python
import pandas as pd      # 数据处理
import numpy as np       # 数值计算  
from jqdata import *     # 聚宽API
import matplotlib.pyplot as plt  # 图表绘制
```

### 代码规范
- **函数命名**: 使用下划线分隔的描述性命名
- **类设计**: 面向对象设计，功能模块化
- **错误处理**: 完善的异常捕获和日志记录
- **配置管理**: 集中的参数配置和管理
- **文档注释**: 详细的函数和类文档字符串

## 使用建议

### 1. 运行环境
- **推荐平台**: 聚宽在线研究环境
- **Python版本**: Python 3.6+
- **内存要求**: 建议至少2GB内存
- **数据权限**: 需要聚宽期货数据访问权限

### 2. 最佳实践
- **时间范围**: 建议使用至少2年的历史数据进行分析
- **品种选择**: 可通过配置文件筛选活跃品种
- **参数调优**: 根据研究目标调整筛选阈值
- **结果验证**: 结合基本面分析验证技术分析结果

### 3. 性能优化
- **批量处理**: 使用并行处理提升大规模数据分析速度
- **内存管理**: 及时释放不需要的数据对象
- **缓存策略**: 对重复查询的数据进行缓存
- **测试模式**: 使用测试模式快速验证算法逻辑

## 更新日志

### v1.5 (2025-09)
- **增强**: 期货烛台影线形态分析算法重大更新
- **新增功能**:
  - 动态仓位管理：基于交易结果的资金调整机制
  - 移动平均线分析：增加MA5/MA10/MA20/MA30技术指标
  - 趋势强度评估：6项比较的量化趋势分析
  - 增强结论逻辑：早期过度损失检测机制
- **字段优化**: 
  - 移除重复的hatch_dire列
  - 新增hatch/body比率列
  - 按指定顺序重排CSV输出字段
- **投资组合管理**: 完整的交易结果汇总和表现分析

### v1.4 (2025-09)
- **新增**: 期货烛台影线形态分析算法 (`future_candlestick_hatch_analysis.py`)
- **算法特点**: 双向过滤条件、主力合约自动识别、未来表现跟踪
- **配置优化**: 新增相反影线比率阈值等可配置参数
- **文档完善**: 更新README文档包含新算法说明

### v1.3 (2025-09)
- **重构**: 将期货技术形态分析整合为单一综合文件
- **优化**: 改进代码结构，增强在线平台适配性
- **新增**: 添加多种测试模式和配置选项
- **完善**: 统一的README文档和算法说明

### v1.2 (2025-06)
- **新增**: 期货技术形态规律分析算法
- **扩展**: 支持更多期货品种和交易所
- **优化**: 改进可视化效果和报告格式

### v1.1 (2024-12)
- **新增**: 多均线穿越分析功能
- **优化**: 改进数据处理效率
- **修复**: 修复部分品种数据获取问题

### v1.0 (2024-06)
- **初始版本**: 基础的期货市场趋势分析
- **核心功能**: 市场整体变化趋势分析

## 研究成果

### 学术价值
- 提供了期货市场技术分析的量化研究框架
- 验证了特定K线形态在期货市场的有效性
- 建立了系统性的期货品种分析方法论

### 实用价值
- 为量化交易策略提供技术分析工具
- 辅助投资决策和风险管理
- 支持期货市场的深度研究和分析

### 未来发展
- 集成机器学习模型提升预测准确性
- 扩展更多技术指标和形态识别
- 建立实时分析和预警系统
- 开发策略回测和评估框架

---
**维护团队**: jukuan研究团队  
**最后更新**: 2025年9月  
**技术支持**: 基于聚宽平台开发，需要相应API权限  
**使用许可**: 仅供研究和学习使用