StockStats 详细部署与使用教程

StockStats 是一个强大的 Python 库，它通过包装 pandas.DataFrame，让你能够以极其简洁的方式计算各种股票技术指标。本教程将带你完成从安装到实战的完整流程。

1. 环境准备与安装

首先，确保你的 Python 环境版本为 3.9 或更高，这是 StockStats 的基本要求。

推荐使用 pip 进行安装，它会自动处理依赖项（如 pandas 和 numpy）：

1
pip install stockstats

（可选）从源码安装：如果你想尝试最新开发版，可以克隆仓库并安装：

1
2
3
git clone https://github.com/jealous/stockstats.git
cd stockstats
pip install -e .

安装完成后，可以通过一个简单测试来验证：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import pandas as pd
from stockstats import wrap

# 创建一个包含最基本列的最小数据集
data = pd.DataFrame({
    'date': pd.date_range(start='2024-01-01', periods=5),
    'close': [10, 11, 12, 11, 10],
    'high': [11, 12, 13, 12, 11],
    'low': [9, 10, 11, 10, 9],
    'volume': [100, 150, 200, 180, 120]
})

# 包装为 StockDataFrame
stock_df = wrap(data)
# 尝试计算一个指标，若无报错则安装成功
print(stock_df['rsi'])

2. 核心概念：StockDataFrame

StockDataFrame 是库的核心。它像一个增强版的 DataFrame，但你无需显式调用计算函数，只需通过特定的列名来“索取”指标，值会在第一次访问时自动计算并缓存。

初始化方式：

  1. 使用 wrap 函数（最常用）：

    1
    2
    3
    4
    5
    from stockstats import wrap
    import pandas as pd
    # 假设 df 是你从 CSV、yfinance 等来源加载的 DataFrame
    df = pd.read_csv('your_stock_data.csv')
    stock_df = wrap(df)

  2. 使用 StockDataFrame.retype 方法：

    1
    2
    from stockstats import StockDataFrame
    stock_df = StockDataFrame.retype(df)

数据要求：你的原始 DataFrame 必须包含以下列（大小写不敏感）：

  • close (必需): 收盘价
  • high (必需): 最高价
  • low (必需): 最低价
  • volume (必需): 成交量
  • date (可选): 日期，会被用作索引

提示：如果使用 yfinance 下载数据，建议添加参数 multi_level_index=False 来避免多级索引引发的问题。
data = yf.download('AAPL', multi_level_index=False)

3. 指标计算：列名模式速查

这是 StockStats 最巧妙的部分。你需要记住几种列名模式，就能访问绝大多数指标。

模式一：<indicator>_<window> （单参数指标）

当你只需要为指标指定一个窗口（周期）时使用。例如计算 RSI：

1
2
3
4
5
6
7
# 使用默认窗口 (14)
rsi_14 = stock_df['rsi']
# 指定窗口为 6
rsi_6 = stock_df['rsi_6']
# 同理
cci_10 = stock_df['cci_10']   # 10周期 CCI
atr_13 = stock_df['atr_13']   # 13周期 ATR

模式二：<column>_<window>_<indicator> （基于特定列的指标）

当你想对特定列（如 high, low, close）应用指标时使用：

1
2
3
4
5
6
# 基于收盘价的20周期简单移动平均
sma_20 = stock_df['close_20_sma']
# 基于最高价的10周期指数移动平均
ema_10 = stock_df['high_10_ema']
# 基于成交量的5周期移动标准差
mstd_5 = stock_df['volume_5_mstd']

模式三：多列输出的指标

一些指标会生成多个列（如 MACD、布林带），首次访问时需使用 get 方法：

1
2
3
4
5
6
7
8
9
10
11
12
# 初始化 MACD 相关的所有列
stock_df.get('macd')
# 现在可以访问这三列了
macd_line = stock_df['macd']    # MACD 线
signal_line = stock_df['macds'] # 信号线
histogram = stock_df['macdh']   # 柱状图

# 布林带同理
stock_df.get('boll')
middle_band = stock_df['boll']      # 中轨
upper_band = stock_df['boll_ub']    # 上轨
lower_band = stock_df['boll_lb']    # 下轨

模式四：信号与比较

StockStats 还能直接生成买卖信号列：

1
2
3
4
5
6
7
8
# 检测金叉：10日均线上穿50日均线
golden_cross = stock_df['close_10_sma_xu_close_50_sma']

# 检测死叉：10日均线下穿50日均线
death_cross = stock_df['close_10_sma_xd_close_50_sma']

# 比较运算：RSI >= 70 时为 True
overbought = stock_df['rsi_ge_70']

4. 动手实战：一个完整示例

下面是一个完整流程，展示如何获取数据、计算指标并生成交易信号。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
import pandas as pd
import yfinance as yf
from stockstats import wrap
import matplotlib.pyplot as plt

# 1. 下载股票数据
ticker = 'AAPL'
data = yf.download(ticker, start='2023-01-01', end='2024-01-01', multi_level_index=False)

# 2. 包装为 StockDataFrame
stock_df = wrap(data)

# 3. 计算所需指标
# 计算 RSI (默认14周期) 和 MACD
stock_df.get('macd')
rsi = stock_df['rsi']
macd = stock_df['macd']
signal = stock_df['macds']

# 4. 生成交易信号 (示例策略: RSI超卖/超买 + MACD金叉/死叉)
# 买入信号: RSI < 30 (超卖) 且 MACD 线上穿信号线
buy_signal = (rsi < 30) & (macd > signal) & (macd.shift(1) <= signal.shift(1))
# 卖出信号: RSI > 70 (超买) 且 MACD 线下穿信号线
sell_signal = (rsi > 70) & (macd < signal) & (macd.shift(1) >= signal.shift(1))

# 将信号添加到 DataFrame 以便查看
stock_df['buy_signal'] = buy_signal
stock_df['sell_signal'] = sell_signal

# 5. (可选) 简单可视化
plt.figure(figsize=(12,6))
plt.plot(stock_df.index, stock_df['close'], label='Close Price', color='black')
# 标记买入点
plt.plot(stock_df[stock_df['buy_signal']].index, 
         stock_df[stock_df['buy_signal']]['close'], 
         '^', markersize=10, color='g', label='Buy Signal')
# 标记卖出点
plt.plot(stock_df[stock_df['sell_signal']].index, 
         stock_df[stock_df['sell_signal']]['close'], 
         'v', markersize=10, color='r', label='Sell Signal')
plt.title(f'{ticker} Trading Signals')
plt.legend()
plt.grid(True)
plt.show()

5. 配置与高级用法

  • 修改默认参数：部分指标的默认窗口（如 RSI 的14）可通过类方法全局修改。修改后，需删除已计算的列才能生效。

    1
    2
    3
    4
    5
    from stockstats import StockDataFrame
    # 将 RSI 默认窗口改为 10
    StockDataFrame.set_dft_window('rsi', 10)
    # 将 MACD 的默认参数改为 (10, 30, 5)
    StockDataFrame.set_dft_window('macd', (10, 30, 5))

  • init_all() 方法：可以一次性初始化大量常用指标（如 KDJ, BOLL, MFI），但这会生成非常多列，请谨慎使用。

  • 将结果转回普通 DataFrame：使用 unwrap 函数：

    1
    2
    from stockstats import unwrap
    plain_df = unwrap(stock_df)

通过本教程，你应该已经掌握了 StockStats 的安装、核心概念和基本用法。它通过简洁的列名模式，让你能够快速进行技术分析，非常适合用于量化策略的快速原型开发。