# ETF月线级别均线分析工具

## 概述

基于 `deep_itm_bull_spread_strategy.py` 的ETF获取逻辑，创建了一个专门的ETF价格与移动平均线距离分析工具。该工具用于分析ETF月收盘价与移动平均线的距离关系。

## 功能特性

### 1. ETF数据获取
- **支持的ETF**：
  - 50ETF (510050.XSHG) - 上证50ETF
  - 300ETF (510300.XSHG) - 沪深300ETF  
  - 创业板ETF (159915.XSHE) - 创业板ETF

### 2. 技术分析
- **移动平均线计算**：5日、10日、20日均线
- **月线级别分析**：将日线数据转换为月线数据
- **距离计算**：计算月收盘价与各均线的绝对距离和百分比距离

### 3. 数据可视化
- 生成距离趋势图表
- 显示每个ETF的距离变化曲线
- 包含统计信息标注

### 4. 数据导出
- 导出详细的CSV分析结果
- 包含价格、均线、距离等完整数据

## 文件说明

### 主要文件
- `etf_monthly_ma_analysis.py` - 完整的分析工具（包含分析功能和直接运行代码）
- `README_ETF_MA_Analysis.md` - 本说明文档

### 生成文件
运行后会生成以下文件：
- `ETF月线距离分析_开始日期_结束日期.png` - 分析图表
- `ETF_月线分析_ETF名称_开始日期_结束日期.csv` - 每个ETF的详细数据

## 使用方法

### 直接运行（推荐）

```bash
# 在聚宽环境中直接运行
python etf_monthly_ma_analysis.py
```

文件中已经预设了分析参数，直接运行即可开始分析。如需修改时间范围，编辑文件底部的参数：

```python
# 修改这里的参数来自定义分析
analyzer = ETFMonthlyMAAnalysis(
    start_date='2024-01-01',  # 修改开始日期
    end_date='2024-10-31'     # 修改结束日期
)
```

### 自定义使用

如果需要在其他脚本中使用，可以导入并自定义：

```python
from etf_monthly_ma_analysis import ETFMonthlyMAAnalysis

# 创建分析器
analyzer = ETFMonthlyMAAnalysis(
    start_date='2024-06-01', 
    end_date='2024-12-31'
)

# 运行完整分析
analyzer.run_complete_analysis(
    save_chart=True,  # 保存图表
    export_csv=True   # 导出CSV
)
```

## 输出示例

### 控制台输出
```
==========================================
详细分析结果
==========================================

50ETF 分析结果:
------------------------------
MA5:
  平均距离: 0.0234 元
  距离标准差: 0.0456 元
  平均百分比距离: 1.23%
  高于均线次数: 6
  低于均线次数: 4
  高于均线比例: 60.0%

MA10:
  平均距离: 0.0156 元
  ...
```

### 图表输出
- 多子图显示每个ETF的距离趋势
- 包含统计信息文本框
- 支持保存为PNG文件

### CSV数据格式
| 年月 | close | MA5 | MA10 | MA20 | Distance_MA5 | Distance_MA5_Pct | ... |
|------|-------|-----|------|------|--------------|------------------|-----|
| 2024-01 | 2.845 | 2.834 | 2.821 | 2.808 | 0.011 | 0.39% | ... |
| 2024-02 | 2.892 | 2.856 | 2.843 | 2.835 | 0.036 | 1.26% | ... |

## 配置参数

### 时间范围
```python
analyzer = ETFMonthlyMAAnalysis(
    start_date='2024-01-01',  # 开始日期
    end_date='2024-12-31'     # 结束日期
)
```

### 移动平均线周期
可在类初始化时修改 `self.ma_periods = [5, 10, 20]`

### ETF符号
可在类初始化时修改 `self.etf_symbols` 字典

## 技术原理

### 数据获取
- 使用聚宽的 `get_price()` 函数获取ETF日线数据
- 包含开盘价、最高价、最低价、收盘价、成交量

### 月线转换
- 使用 pandas 的 `resample('M')` 方法
- 月开盘价：取月内第一个交易日开盘价
- 月收盘价：取月内最后一个交易日收盘价
- 月最高/最低价：取月内极值

### 距离计算
- **绝对距离**：`距离 = 月收盘价 - 移动平均线`
- **百分比距离**：`百分比距离 = (月收盘价 - 移动平均线) / 移动平均线 × 100%`

### 统计分析
- 计算距离的均值、标准差、最大值、最小值
- 统计正向/负向距离的次数
- 计算高于均线的比例

## 注意事项

1. **环境要求**：需要在聚宽（JoinQuant）环境中运行
2. **数据依赖**：依赖聚宽的 `jqdata` 包和 `get_price()` 函数
3. **时间范围**：建议选择至少6个月以上的时间范围以获得有意义的分析结果
4. **市场假期**：工具会自动处理交易日历，跳过市场假期

## 应用场景

1. **趋势分析**：观察ETF价格相对于均线的长期趋势
2. **买卖时机**：通过距离分析判断潜在的买卖机会
3. **风险评估**：通过距离的波动性评估风险
4. **策略回测**：为期权策略提供基础的技术分析数据

## 扩展功能

可以基于此工具进一步开发：
- 添加更多技术指标（RSI、MACD等）
- 增加更多均线周期
- 添加自动化交易信号生成
- 集成到现有的期权策略中

## 版本历史

- v1.0 - 初始版本，基于深度实值牛差策略的ETF获取逻辑