tqsdk-python tafunc 序列计算函数完全指南:从 K 线指标、时间转换到期权希腊值的实战速查手册
tqsdk-python tafunc 序列计算函数完全指南:从 K 线指标、时间转换到期权希腊值的实战速查手册
导读:tqsdk.tafunc 是 tqsdk-python(天勤量化开发包)中负责序列计算的底层工具模块,包含了移动平均、极值、穿越判断、时间戳转换、期权 BS 定价与希腊值、tick 开平方向识别、复权因子以及绩效评估等 30 余个函数。本文以 doc/reference/tqsdk.tafunc.rst 对应的 tqsdk/tafunc.py 为骨架,完整覆盖每个函数的签名、计算公式、边界行为与源码实现,并结合仓库内策略示例(如 tqsdk/demo/example/doublema.py)与期权用例,带你掌握在实时行情、历史回测与期权分析中直接调用这些序列函数的方法。读完本文,你将能够脱离 tqsdk.ta 的固定指标封装,自由组合底层序列函数搭建自己的技术分析与定价逻辑。
一、模块定位:与 tqsdk.ta 的分工关系
在 tqsdk-python 中,技术指标计算被拆分成两个层次:
tqsdk.ta:封装了一批"开箱即用"的技术指标,函数名全大写,第一个参数总是 K 线序列(pandas.DataFrame),返回值也是 DataFrame,例如MACD、ATR、RSI、BIAS等(详见 doc/usage/ta.rst 与 tqsdk/ta.py)。tqsdk.tafunc:提供更底层的序列计算函数,输入输出多为pandas.Series,它们是构成tqsdk.ta技术指标的基础积木。当你想"按最高价而不是收盘价计算均线"这类tqsdk.ta未覆盖的定制需求时,应直接使用本模块。
模块头部 docstring 明确了其约定:
"tqsdk.tafunc 模块包含了一批用于技术指标计算的函数(函数基本保持 参数为 pandas.Series 类型则返回值为 pandas.Series 类型)"
源码中能清晰看到这种"底层支撑上层"的依赖关系:例如 tqsdk/ta.py 的 ATR 函数在计算 atr 列时直接调用 tqsdk.tafunc.ma(tqsdk/ta.py#L53);tqsdk/report.py 导入 get_sharp、get_sortino、get_calmar、_cum_counts 用于生成策略绩效报告;tqsdk/api.py 导入 get_dividend_df、get_dividend_factor 处理股票复权,并在文档示例中使用 tafunc.time_to_datetime 把 K 线纳秒时间戳转成 datetime.datetime。
从函数用途看,本模块可划分为六大类:
| 类别 | 函数 |
|---|---|
| 移动平均/统计类 | ma、sma、ema、ema2、trma、harmean、std、median、avedev、numpow |
| 位移与极值类 | ref、hhv、llv、abs、min、max |
| 条件逻辑类 | crossup、crossdown、count、exist、every、barlast |
| 时间转换类 | time_to_ns_timestamp、time_to_s_timestamp、time_to_str、time_to_datetime |
| 期权定价类 | get_t、get_his_volatility、get_bs_price、get_delta、get_gamma、get_theta、get_vega、get_rho、get_impv |
| 行情/复权/绩效类 | get_ticks_info、get_dividend_df、get_dividend_factor、get_sharp、get_sortino、get_calmar |
二、数据来源:K 线序列与行情对象
本模块几乎所有序列函数都要求传入 pandas.Series,而 tqsdk-python 中最常见的数据来源是 api.get_kline_serial() 返回的 K 线序列(DataFrame),其 open、high、low、close、volume、datetime 等列即为 Series。典型用法:
from tqsdk import TqApi, TqAuth, tafunc
api = TqApi(auth=TqAuth("快期账户", "账户密码"))
klines = api.get_kline_serial("CFFEX.IF1908", 24 * 60 * 60) # 日线
ma5 = tafunc.ma(klines.close, 5) # 收盘价 5 周期简单移动平均
其中 24 * 60 * 60 表示日线周期(秒),60 表示 1 分钟线。在回测环境中,同样的代码配合 TqBacktest 即可工作,例如 tqsdk/demo/example/RSI.py 中先用 api.get_kline_serial(SYMBOL, 60 * 60 * 24) 获取日线,再用 time_to_str(klines.datetime.iloc[-1]) 打印可读时间。
三、移动平均与统计函数
移动平均族是本模块使用频率最高的一组函数,覆盖简单、指数、线性加权、三角、调和平均以及标准差、中位数、平均绝对偏差等统计量。它们的共同边界行为是:n 为 0,或序列元素个数不足 n 个时,返回 NaN 序列(个别函数除外,已逐一注明)。
3.1 ma:简单移动平均
公式:ma(x, 5) = (x(1) + x(2) + x(3) + x(4) + x(5)) / 5,周期内各元素权重相等。实现为 series.rolling(n).mean()(tqsdk/tafunc.py#L107):
ma = tafunc.ma(klines.close, 5)
3.2 sma:扩展指数加权移动平均
公式:sma(x, n, m) = sma(x, n, m).shift(1) * (n - m) / n + x(n) * m / n,要求 n 必须大于 m。实现为 series.ewm(alpha=m / n, adjust=False).mean()(tqsdk/tafunc.py#L139):
sma = tafunc.sma(klines.close, 5, 2) # 5 周期、权重 m=2
3.3 ema:指数加权移动平均
公式:ema(x, n) = 2 * x / (n + 1) + (n - 1) * ema(x, n).shift(1) / (n + 1),n 需大于等于 1,对距离当前较近的 K 线赋予更大权重。实现为 series.ewm(span=n, adjust=False).mean()(tqsdk/tafunc.py#L171)。
3.4 ema2:线性加权移动平均(WMA)
公式:ema2(x, n) = <a href="https://link.gitcode.com/i/c19411d1f0793149afbb8e70f79d99e0" target="_blank">n * x(0) + (n - 1) * x(1) + ... + 1 * x(n - 1)] / [n + (n - 1) + ... + 1]。实现中构造权值列表 weights = [1..n] 并用 rolling(window=n).apply(np.average, weights=weights, raw=True) 滚动计算([tqsdk/tafunc.py#L201-L206)。
3.5 trma:三角移动平均
采用"对移动平均再做一次算术移动平均"的方法(tqsdk/tafunc.py#L317-L324):周期 n 为偶数时拆为 n1 = n/2、n2 = n/2 + 1,为奇数时 n1 = n2 = (n+1)/2,然后 trma = ma(ma(series, n1), n2)。
3.6 harmean:调和平均值
公式:harmean(x, 5) = 1 / <a href="https://link.gitcode.com/i/c9f64e5a3334cbe7e71396cef8f7626c" target="_blank">(1/x(1) + 1/x(2) + 1/x(3) + 1/x(4) + 1/x(5)) / 5],即"倒数的简单平均值"的倒数。实现为 n / ((1 / series).rolling(n).sum())([tqsdk/tafunc.py#L355)。
3.7 std:标准差
求每 n 个周期的标准差,实现为 series.rolling(n).std()(tqsdk/tafunc.py#L75):
std = tafunc.std(klines.close, 5) # 收盘价每 5 项一个标准差
3.8 median:中位数
n 为奇数取排序后第 (n+1)/2 个,n 为偶数取第 n/2 与 n/2+1 的平均数。docstring 给出了两个数值示例(tqsdk/tafunc.py#L484-L490):
# 最近3日收盘价为 2727, 2754, 2748,则 median(close, 3) 返回 2748
median3 = tafunc.median(df["close"], 3)
# 最近4日开盘价为 2752, 2743, 2730, 2728,则 median(open, 4) 返回 2736.5
median4 = tafunc.median(df["open"], 4)
3.9 avedev:平均绝对偏差
表示 n 个周期内每个收盘价与 n 周期均值之差的绝对值的平均,用于衡量价格与其均值的偏离程度。docstring 给出了 3 周期的手算过程(tqsdk/tafunc.py#L606-L610):对窗口内每个元素计算 abs(x - 窗口均值) 后取均值。实现为 rolling(n).apply(mad),其中 mad(x) = np.fabs(x - x.mean()).mean()(tqsdk/tafunc.py#L633-L636)。
3.10 numpow:自然数幂方和
公式:numpow(x, n, m) = n^m * x + (n-1)^m * x.shift(1) + ... + 1^m * x.shift(n-1)。实现为 sum((n - i) ** m * series.shift(i) for i in range(n))(tqsdk/tafunc.py#L387),其中 n 为自然数、m 为实数。
四、位移与极值函数
4.1 ref:简单位移
将序列位移 n 个周期。n 为 0 时返回原序列;元素个数不足 n + 1 时返回 NaN 序列。实现为 series.shift(n)(tqsdk/tafunc.py#L48)。最典型的应用是构造"昨收盘"序列:
pre_close = tafunc.ref(klines.close, 1) # 收盘价右移一位 → 昨收盘
change = klines.close - pre_close # 涨跌序列
4.2 hhv / llv:N 周期最高值 / 最低值
分别求 n 个周期内的最高价/最低价,包含当前 K 线。实现为 series.rolling(n).max() / series.rolling(n).min()(tqsdk/tafunc.py#L571、tqsdk/tafunc.py#L598):
hhv = tafunc.hhv(klines.high, 4) # 4 周期高点
llv = tafunc.llv(klines.low, 5) # 5 根 K 线最低点
4.3 abs / min / max
abs(series):取绝对值,实现为np.absolute(tqsdk/tafunc.py#L412);min(series1, series2)/max(series1, series2):逐元素取两序列的最小/最大值,实现为np.minimum/np.maximum(tqsdk/tafunc.py#L437、tqsdk/tafunc.py#L462):
min_price = tafunc.min(klines.close, klines.open)
五、条件逻辑函数:穿越、计数与存在性判断
这类函数以条件(布尔序列)或两条序列为输入,输出 0/1 标志序列,是编写交易信号的核心工具。
5.1 crossup / crossdown:向上 / 向下穿越
crossup(a, b):当a从下方向上穿过b时返回 1,否则 0。实现:(a > b) & (a.shift(1) <= b.shift(1))(tqsdk/tafunc.py#L231);crossdown(a, b):当a从上方向下穿b时返回 1,否则 0。实现:(a < b) & (a.shift(1) >= b.shift(1))(tqsdk/tafunc.py#L256)。
经典用法是判断短周期均线上穿长周期均线:
cross = tafunc.crossup(tafunc.ma(klines.close, 5), tafunc.ma(klines.close, 10))
5.2 count:统计 n 周期内满足条件的个数
注意:n 为 0 时从第一个有效值开始统计(等价于条件序列的累计和 cumsum);n 大于 0 时按滚动窗口求和(tqsdk/tafunc.py#L284-L288):
# 统计自行情申请以来,5 周期均线上穿 10 周期均线的总次数
count = tafunc.count(tafunc.crossup(tafunc.ma(klines.close, 5), tafunc.ma(klines.close, 10)), 0)
5.3 exist / every:区间内"存在" / "一直"满足
exist(cond, n):n 个周期内任一时刻满足条件即返回 1(滚动求和 > 0),否则 0(tqsdk/tafunc.py#L518);every(cond, n):n 个周期内一直满足条件才返回 1(滚动求和 == n),否则 0(tqsdk/tafunc.py#L544)。
# 判断 4 个周期内是否存在"收盘价大于前一个周期的最高价"
exist = tafunc.exist(klines.close > klines.high.shift(1), 4)
# 判断 4 周期内 3 周期均线是否一直大于 5 周期均线
every = tafunc.every(tafunc.ma(klines.close, 3) > tafunc.ma(klines.close, 5), 4)
5.4 barlast:距上次条件成立的周期数
返回一个序列,每个值表示"从上一次条件成立到当前的周期数"(tqsdk/tafunc.py#L781-L820)。边界规则:
- 若从序列第一个值到某个位置之间没有 True,则该位置返回 -1;
- 条件成立的位置本身返回 0;
- 若条件序列长度为 0 或没有 True,返回全 -1 序列。
常用 n.iloc[-1] 取得最后一根 K 线到上次满足条件的周期数:
from tqsdk import TqApi, TqAuth
from tqsdk.tafunc import barlast
api = TqApi(auth=TqAuth("快期账户", "账户密码"))
klines = api.get_kline_serial("SHFE.cu1912", 60)
n = barlast(klines.close > klines.open) # 距上次"收阳"的周期数
print(list(n))
print(n.iloc[-1]) # 最后一根 K 线的周期数
api.close()
六、时间转换函数
tqsdk-python 中行情时间戳统一使用纳秒级 int(如 K 线/tick 的 datetime 字段 1.57103449e+18 这类值),同时 Quote 的 datetime 字段是字符串(如 2019-10-14 14:26:01.000000)。tafunc 提供 4 个转换函数与一个底层判定逻辑 _to_ns_timestamp(tqsdk/tafunc.py#L640-L668),判定规则如下:
int / float / numpy 数值:若大于2**32判定为纳秒级时间戳直接返回,否则判定为秒级时间戳并乘以1e9;str:按%Y-%m-%d %H:%M:%S.%f解析(调用_str_to_timestamp_nano);datetime.datetime:调用_datetime_to_timestamp_nano转换;- 其他类型抛出
TypeError("暂不支持此类型的转换")。
四个公开函数(tqsdk/tafunc.py#L671-L778):
from tqsdk.tafunc import time_to_ns_timestamp, time_to_s_timestamp, time_to_str, time_to_datetime
import datetime
# 各类输入统一转为纳秒级时间戳
print(time_to_ns_timestamp("2019-10-14 14:26:01.000000"))
print(time_to_ns_timestamp(1571103122)) # 秒级 → 纳秒
print(time_to_ns_timestamp(datetime.datetime(2019, 10, 14, 14, 26, 1)))
# 转为秒级时间戳
print(time_to_s_timestamp(1.57103449e+18)) # 纳秒 → 秒
print(time_to_s_timestamp("2019-10-14 14:26:01.000000"))
# 转为 %Y-%m-%d %H:%M:%S.%f 字符串
print(time_to_str(1.57103449e+18))
print(time_to_str(1571103122))
# 转为 datetime.datetime 类型
print(time_to_datetime(1.57103449e+18))
print(time_to_datetime("2019-10-14 14:26:01.000000"))
其中 time_to_datetime 在 tqsdk/api.py#L706-L712 的文档示例中用于把最后一根 K 线的纳秒时间转成 datetime.datetime 并提取年月日。注意:time_to_str 与 time_to_datetime 的输入为 int/float 或(time_to_datetime 另支持)str,不接收 datetime 类型。
七、期权定价与希腊指标
tafunc 内置了一整套基于 Black-Scholes(BS)模型的期权计算函数,仓库中与之配套的期权交易教程见 tqsdk/demo/option_tutorial(如 o72.py、o73.py),文档层面的函数索引见 doc/usage/option_trade.rst。
7.1 get_t:年化到期时间
根据 K 线序列的 datetime、duration 与到期日 expire_datetime(秒级时间戳)计算年化到期时间,默认按一年 360 天计(源码见 tqsdk/tafunc.py#L842-L845):
quote = api.get_quote('SHFE.cu2006C45000')
klines = api.get_kline_serial(['SHFE.cu2006C45000', 'SHFE.cu2006'], 24 * 60 * 60, 50)
t = tafunc.get_t(klines, quote.expire_datetime)
7.2 get_his_volatility:历史波动率
计算某合约的历史波动率(tqsdk/tafunc.py#L908-L935)。内部通过收益率对数差 log(close.shift(1) / close) 的协方差估算:sqrt((250 * 每秒交易时长 / dur) * np.cov(log 收益率))。两个值得注意的实现细节:
- 若传入的
quote与df["symbol"][0]一致,会读取quote.trading_time中的日盘/夜盘时段(_get_period_timestamp),把"一天"修正为实际交易时长; - 收益率样本数小于 2(自由度不足)时返回
float("nan")。
quote = api.get_quote('SHFE.cu2006')
klines = api.get_kline_serial('SHFE.cu2006', 24 * 60 * 60, 50)
v = tafunc.get_his_volatility(klines, quote)
7.3 期权参数约定
波动率 v、年化到期时间 t、初始波动率 init_v 既可以是标量 float(对序列每个元素取同值),也可以是长度与标的价格序列相同的 pandas.Series(逐元素取值);期权方向 option_class 只能是 "CALL" 或 "PUT" 字符串,或逐元素取值于二者的 Series——传入其他值时返回全 NaN 序列。方向映射由 _get_options_class 完成:CALL→1、PUT→-1(tqsdk/tafunc.py#L863-L879)。BS 公式中的 d1 计算位于 _get_d1(tqsdk/tafunc.py#L848-L850),当波动率 v <= 0 或到期时间 t <= 0 时返回 NaN;正态分布累积概率 _get_cdf 与概率密度 _get_pdf 基于 scipy.stats.norm,且会保留原始序列的 NaN 位置(tqsdk/tafunc.py#L853-L860)。
7.4 希腊值与理论价
五个希腊指标与 BS 理论价均支持可选参数 d1(提前传入可复用、避免重复计算):
get_bs_price(series, k, r, v, t, option_class):BS 理论价格(tqsdk/tafunc.py#L951-L1004),公式为o * (S * N(o*d1) - k * e^{-r*t} * N(o*d2)),其中o为方向(CALL=1/PUT=-1),d2 = d1 - v * sqrt(t);get_delta(series, k, r, v, t, option_class, d1=None):o * N(o*d1)(tqsdk/tafunc.py#L1007-L1064);get_gamma(series, k, r, v, t, d1=None):pdf(d1) / (S * v * sqrt(t))(tqsdk/tafunc.py#L1067-L1117);get_theta(series, k, r, v, t, option_class, d1=None):-v*S*pdf(d1)/(2*sqrt(t)) - o*r*k*e^{-r*t}*N(o*d2)(tqsdk/tafunc.py#L1120-L1179);get_vega(series, k, r, v, t, d1=None):S * sqrt(t) * pdf(d1)(tqsdk/tafunc.py#L1182-L1232);get_rho(series, k, r, v, t, option_class, d1=None):o * k * t * e^{-r*t} * N(o*d2)(tqsdk/tafunc.py#L1235-L1293)。
7.5 get_impv:隐含波动率
通过牛顿迭代法反解隐含波动率(tqsdk/tafunc.py#L1296-L1361):以 init_v 为迭代初值,用 get_bs_price 计算理论价、get_vega 计算修正步长 diff = (期权价 - 理论价) / vega,迭代直到理论价与期权价的绝对误差小于 1e-8;当 vega < 1e-8 时停止修正(此时对波动率不敏感)。同时处理了"理论价跌破内在价值下界"(series_option < o * (S - k*e^{-r*t}))与 t <= 0 的非法情形(返回 NaN),并对修正结果做非负与幅度约束(x+diff<0 时取 x/2,diff > x/2 时取 x*1.5)。
7.6 期权完整示例
以下组合示例摘自 get_impv 的 docstring(tqsdk/tafunc.py#L1331-L1346),串联了历史波动率、年化到期时间、隐含波动率与各希腊值:
import pandas as pd
from tqsdk import TqApi, TqAuth, tafunc
api = TqApi(auth=TqAuth("快期账户", "账户密码"))
quote = api.get_quote("SHFE.cu2006")
ks = api.get_kline_serial("SHFE.cu2006", 24 * 60 * 60, 10)
v = tafunc.get_his_volatility(ks, quote) # 历史波动率
option = api.get_quote("SHFE.cu2006C45000")
klines = api.get_kline_serial(["SHFE.cu2006C45000", "SHFE.cu2006"], 24 * 60 * 60, 10)
t = tafunc.get_t(klines, option.expire_datetime)
impv = tafunc.get_impv(klines["close1"], klines["close"], 45000, 0.025, v, t, "CALL")
bs_price = tafunc.get_bs_price(klines["close1"], 45000, 0.025, v, t, option.option_class)
delta = tafunc.get_delta(klines["close1"], 45000, 0.025, v, t, "CALL")
print("impv", list((impv * 100).round(2)))
print(list(bs_price.round(2)))
print("delta", list(delta))
api.close()
其中 klines["close1"] 是多合约 K 线序列中**第一个合约(期权)的收盘价列,klines["close"] 是第二个合约(标的)**的收盘价列;get_impv 的第二个参数 series_option 传入的是期权价格序列。
八、get_ticks_info:tick 开平方向识别
输入 api.get_tick_serial() 返回的 tick 序列(DataFrame),输出每笔 tick 的开平方向标签序列(tqsdk/tafunc.py#L1364-L1410)。若传入的是 K 线(缺少 open_interest 列),函数会抛出 Exception("get_ticks_info 参数必须是 ticks,由 api.get_tick_serial 返回的对象。")。
判定逻辑综合了买卖价主动方向、持仓量变化与成交量变化:
- 以
pc标记主动方向:last_price <= 前一笔 bid_price1记为 -1(主动卖),last_price >= 前一笔 ask_price1记为 +1(主动买),否则用sign(last_price 变化); oi_diff > 0→ "多开"(主动买)/ "空开"(主动卖);oi_diff < 0→ "空平" / "多平";oi_diff == 0→ "多换" / "空换";- 特殊情形:
pc == 0标为"换手";oi_diff < 0 且 oi_diff + vol_diff == 0标为"双平";oi_diff > 0 且 oi_diff == vol_diff标为"双开";vol_diff == 0标为空字符串。
ticks = api.get_tick_serial('SHFE.cu2006', 100)
ticksinfo = tafunc.get_ticks_info(ticks)
for i, v in ticksinfo.items():
print(f"{tafunc.time_to_str(ticks['datetime'][i])[5:21]} {ticks['last_price'][i]} {v}")
# 预计输出形如:
# 04-27 10:54:11.5 42640.0 多换
# 04-27 10:55:14.0 42670.0 双平
九、股票复权:get_dividend_df 与 get_dividend_factor
针对股票行情,tafunc 提供复权支持(源码在 tqsdk/tafunc.py#L1413-L1465,被 tqsdk/api.py 与 tqsdk/utils.py 导入使用):
get_dividend_df(stock_dividend_ratio, cash_dividend_ratio):将quote.stock_dividend_ratio(除权表)与quote.cash_dividend_ratio(除息表)合并为"除权除息矩阵",返回含["datetime", "stock_dividend", "cash_dividend"]三列的 DataFrame,缺失值以 0.0 填充;get_dividend_factor(dividend_df, last_item, item):根据前一个数据项last_item与当前数据项item(tick/kline 对象,需含datetime,取close否则last_price)返回复权因子,公式为(1 - cash_dividend / c) / (1 + stock_dividend);两时间戳之间无除权除息事件时返回 1。
十、绩效评估:年化夏普 / 索提诺 / 卡玛比率
这三个函数计算年化风险调整收益指标,被 tqsdk/report.py 用于生成回测/实盘绩效报告。共同约定(tqsdk/tafunc.py#L1478-L1539):
series:每日收益率序列(不是价格序列);trading_days_of_year:年化交易日数量,默认 250;r:无风险利率,默认 0.025;内部先经_get_daily_risk_free(tqsdk/tafunc.py#L1542-L1544)转为日化无风险利率pow(r+1, 1/trading_days_of_year) - 1;- 收益率序列标准差为 0 时返回
float("inf")。
| 函数 | 公式要点 |
|---|---|
get_sharp(series, trading_days_of_year=250, r=0.025) |
sqrt(250) * (mean - rf) / pstdev,其中 _tq_pstdev 为总体标准差(因 Python 3.7 的 statistics.pstdev 不支持指定均值,故单独实现,见 tqsdk/tafunc.py#L1468-L1475) |
get_sortino(series, trading_days_of_year=250, r=0.025) |
只取低于日化无风险利率的收益率计算下行标准差,并按实际低于 rf 的天数比例 sqrt(250 * n_low / n_total) 年化 |
get_calmar(series, max_drawdown, trading_days_of_year=250, r=0.025) |
sqrt(250) * (mean - rf) / max_drawdown;max_drawdown 为 0 或 NaN 时返回 inf |
此外,模块内还有未公开但被 report.py 使用的 _cum_counts(s):统计序列中连续为 1 的个数,用于计算最大连续盈利/亏损天数(tqsdk/tafunc.py#L1547-L1553)。
十一、实战组合:用底层序列函数搭建双均线策略
将本模块函数与 TargetPosTask 组合即可实现完整策略。仓库中 tqsdk/demo/example/doublema.py 即以此模式编写:
from tqsdk import TqApi, TqAuth, TargetPosTask
from tqsdk.tafunc import ma
SHORT = 30 # 短周期
LONG = 60 # 长周期
SYMBOL = "SHFE.bu2012"
api = TqApi(auth=TqAuth("快期账户", "账户密码"))
klines = api.get_kline_serial(SYMBOL, duration_seconds=60, data_length=LONG + 2)
target_pos = TargetPosTask(api, SYMBOL)
while True:
api.wait_update()
if api.is_changing(klines.iloc[-1], "datetime"): # 产生新 K 线时重新计算
short_avg = ma(klines["close"], SHORT)
long_avg = ma(klines["close"], LONG)
# 均线下穿 → 做空
if long_avg.iloc[-2] < short_avg.iloc[-2] and long_avg.iloc[-1] > short_avg.iloc[-1]:
target_pos.set_target_volume(-3)
# 均线上穿 → 做多
if short_avg.iloc[-2] < long_avg.iloc[-2] and short_avg.iloc[-1] > long_avg.iloc[-1]:
target_pos.set_target_volume(3)
也可用 crossup / crossdown 直接表达穿越信号。若需要更高层指标(MACD、RSI、KDJ 等),直接使用 tqsdk/ta.py 中的 DataFrame 风格指标即可;若需要定制"任意价格序列的均线"(如 ma(klines.high, 9)),本模块是最直接的入口(doc/usage/ta.rst 亦如此推荐)。
十二、速查表与注意事项汇总
12.1 函数签名速查表
| 函数 | 签名 | 关键注意点 |
|---|---|---|
ref |
ref(series, n) |
n=0 返回原序列;不足 n+1 个元素返回 NaN |
std / ma / median / avedev / hhv / llv |
(series, n) |
n=0 或不足 n 个元素返回 NaN |
sma |
(series, n, m) |
n 必须大于 m |
ema |
(series, n) |
n ≥ 1 |
ema2 |
(series, n) |
即 WMA,权值 1..n 由远及近 |
trma |
(series, n) |
对 MA 再求 MA |
harmean |
(series, n) |
倒数平均的倒数 |
numpow |
(series, n, m) |
自然数幂方加权和 |
abs / min / max |
(series) / (s1, s2) |
逐元素运算 |
crossup / crossdown |
(a, b) |
输出 0/1 序列 |
count |
(cond, n) |
n=0 时从首个有效值累计 |
exist / every |
(cond, n) |
区间内"存在"/"一直" |
barlast |
(cond) |
无 True 位置为 -1,成立处为 0 |
time_to_ns_timestamp / time_to_s_timestamp / time_to_str / time_to_datetime |
(input_time) |
支持 str/int/float/datetime,见第 6 节判定规则 |
get_t |
(df, expire_datetime) |
年化到期时间,一年按 360 天 |
get_his_volatility |
(df, quote) |
样本 < 2 返回 NaN;trading_time 修正日时长 |
get_bs_price / get_delta / get_gamma / get_theta / get_vega / get_rho |
见 7.4 节 | option_class 非法时全 NaN;可传 d1 复用 |
get_impv |
(series, series_option, k, r, init_v, t, option_class) |
牛顿迭代,收敛精度 1e-8 |
get_ticks_info |
(df) |
输入必须是 tick 序列,否则抛异常 |
get_dividend_df / get_dividend_factor |
见第 9 节 | 用于股票复权 |
get_sharp / get_sortino / get_calmar |
见第 10 节 | 输入为每日收益率序列 |
12.2 使用要点
- NaN 传播:多数滚动函数在窗口数据不足时返回 NaN,组合使用时建议保证
data_length足够(如双均线示例取LONG + 2),或在策略中跳过数据不足的早期阶段(参见 tqsdk/demo/example/RSI.py 中len(klines) < RSI_PERIOD + 10的判断)。 - 性能:
ema2、avedev使用rolling().apply()逐窗口调用 Python 函数,数据量大时计算开销高于纯向量化的rolling().mean()等函数,长周期回测中需权衡。 - 入参类型:除特别说明外,序列类入参要求
pandas.Series;min/max/get_bs_price等底层依赖 numpy 广播,实际也可接受等长数组。 - 时间戳口径:K 线/tick 的
datetime为纳秒级 int,Quote 的datetime为字符串,转换前请先确认输入类型,避免混用。
延伸阅读
- 技术指标与序列计算函数的整体使用说明:doc/usage/ta.rst
- 期权指标与查询函数清单:doc/usage/option_trade.rst
- 高层技术指标模块(DataFrame 风格):tqsdk/ta.py
- 策略示例:双均线 tqsdk/demo/example/doublema.py、RSI 反转 tqsdk/demo/example/RSI.py
- 绩效指标的实际调用方:tqsdk/report.py