TqSdk 技术指标绘图实战:ATR 计算、副图配置与天勤终端/VS Code 插件可视化
TqSdk 技术指标绘图实战:ATR 计算、副图配置与天勤终端/VS Code 插件可视化
本篇技术指南以 TqSdk(tqsdk-python)中的真实波幅均值 ATR(Average True Range)指标为切入点,完整讲解"指标计算 → K 线附加列 → 主图/副图绘图 → 天勤终端与 VS Code 插件实时展示"的完整链路。读者将掌握 tqsdk.ta 指标函数的调用方式、K 线序列绘图列(.board / .color / .width)的配置规则,以及 api.draw_line / draw_text / draw_box 等图形 API 的用法,可直接迁移到任意策略的指标可视化场景中。
一、绘图能力总览:TqSdk 的"计算 + 可视化"一体化设计
TqSdk 本身不依赖任何 IDE 即可工作,针对习惯使用 VS Code、PyCharm 等 IDE 做 Python 开发的用户,官方通过 IDE 插件补充了三类附加能力:复盘支持、交易监控及报告、在行情图上绘制指标和其它图形(见 doc/devtools/index.rst)。
绘图能力贯穿两条使用路径:
- 天勤终端:TqSdk 客户端程序运行后,把绘图数据推送给天勤终端(快期),由终端渲染 K 线与指标图形;
- VS Code 天勤插件:插件运行策略时会自动显示策略相关合约的 K 线图,策略中有绘图输出时同样会渲染到右侧面板(见 doc/devtools/vscode.rst)。
两者的绘图原理完全一致:以 get_kline_serial 返回的 K 线 DataFrame 为基础,通过"附加列"方式把指标序列挂到 K 线上,再用 .board、.color、.width 等特殊后缀列控制渲染属性。文档 doc/devtools/drawindex.rst 正是以 ATR 为例示范这条链路,下文将据此展开。
二、ATR 指标原理与公式拆解
ATR(Average True Range,平均真实波幅)由 J. Welles Wilder 提出,用于衡量一段时间内的价格波动幅度。文档给出的计算公式分两步:
第 1 步:真实波幅(True Range,TR)
TR = MAX(|最高价 - 最低价|,|最高价 - 昨收|,|昨收 - 最低价|)
TR 不仅考虑当根 K 线内部的高低点差(high - low),还同时考虑与前一个时间点收盘价(昨收 pre_close)之间的跳空缺口,分别取"最高价相对昨收的缺口"与"昨收相对最低价的缺口"中的较大者。
第 2 步:真实波幅均值(ATR)
ATR = TR 的 N 日简单移动平均
一般取 N = 14。ATR 在策略中常用于动态止损、通道类指标(如 Keltner 通道)与波动率过滤,仓库内的 turtle.py 海龟策略即以 ATR(klines, 20)<a href="https://link.gitcode.com/i/0f918dd8b78a1785ffd5780053a32c0a" target="_blank">"atr"].iloc[-1] 作为仓位与止损的核心输入,[hull.py、vortex-indicator.py 等示例也大量用 ATR 设置止损倍数。
三、用 tqsdk.ta.ATR 在 TqSdk 中计算 TR 与 ATR
TqSdk 在 tqsdk.ta 模块中提供了非常丰富的技术指标函数(MA、BOLL、MACD、KDJ、DMI、RSI 等),全部以"传入 K 线 DataFrame、返回指标 DataFrame"的约定工作。ATR 函数定义于 tqsdk/ta.py:
def ATR(df, n):
new_df = pd.DataFrame()
pre_close = df["close"].shift(1) # 昨收:前一根 K 线的收盘价
new_df["tr"] = np.where(df["high"] - df["low"] > np.absolute(pre_close - df["high"]),
np.where(df["high"] - df["low"] > np.absolute(pre_close - df["low"]),
df["high"] - df["low"], np.absolute(pre_close - df["low"])),
np.where(np.absolute(pre_close - df["high"]) > np.absolute(pre_close - df["low"]),
np.absolute(pre_close - df["high"]), np.absolute(pre_close - df["low"])))
new_df["atr"] = tqsdk.tafunc.ma(new_df["tr"], n) # TR 的 N 周期简单移动平均
return new_df
从源码可以确认三点实现细节:
tr列通过np.where三重嵌套逐项比较high - low、|pre_close - high|、|pre_close - low|,与文档中的公式一一对应;atr列调用 tqsdk/tafunc.py 的ma(series, n)简单移动平均实现:即设定周期内各元素等权求平均,且当序列元素不足 n 个时返回 NaN;- 返回的 DataFrame 固定包含
tr与atr两列,可直接通过atr.tr/atr.atr或atr["tr"]/atr["atr"]访问。
3.1 最小可运行示例
文档中的示例(合约 SHFE.au1912,24 小时 K 线,周期 14)整理为可直接运行的程序:
from tqsdk import TqApi, TqAuth
from tqsdk.ta import ATR
api = TqApi(TqAuth("快期账户", "账户密码")) # 使用快期账户登录
klines = api.get_kline_serial("SHFE.au1912", 24 * 60 * 60) # 24小时K线
atr = ATR(klines, 14) # 周期14的真实波幅均值
print(atr.tr) # 真实波幅
print(atr.atr) # 真实波幅均值
# 预计的输出是这样的:
[..., 143.0, 48.0, 80.0, ...]
[..., 95.20000000000005, 92.0571428571429, 95.21428571428575, ...]
api.wait_update() # 等待业务信息更新(同时把绘图/订阅信息推送给天勤)
api.close()
3.2 关于 K 线序列的关键参数
示例中 get_kline_serial("SHFE.au1912", 24 * 60 * 60) 的完整签名定义于 tqsdk/api.py:
symbol:合约代码,可为字符串或合约代码列表(多合约按时间对齐);duration_seconds:K 线周期(秒),如 60 为一分钟线、3600 为一小时线、86400 为日线;日线以内可任意填写,日线以上必须是 86400 的整数倍,最大 28 天;data_length:序列长度,默认 200 根,最大可请求 10000 个数据;返回的 DataFrame 依次包含id、datetime、open、high、low、close、volume、open_oi、close_oi等列;adj_type:可选复权类型(仅股票/基金合约有效,"F"前复权、"B"后复权)。
注意:获取后的 kline 对象不要修改/重命名原始序列字段(如
open/high/low/close),否则可能导致后续 K 线数据不更新。
四、在天勤终端与 VS Code 插件中绘制 ATR 指标线
4.1 以附加列形式绘图:指标名 + .board / .color / .width
拿到 atr.atr 与 atr.tr 两个序列后,直接把它们写回 K 线 DataFrame 的附加列,即可触发绘图。文档中的第一个绘图示例:
# 创建副图以折线显示 atr.atr 数据
klines["ATR_atr"] = atr.atr
# ATR_atr.board 为选择图板,可选,缺省为 "MAIN" 表示绘制在主图
klines["ATR_atr.board"] = "ATR_atr"
# 通过 api.wait_update() 将绘图信息发送给天勤终端
api.wait_update()
api.close()
要点解析:
- 数据列:
klines["ATR_atr"] = atr.atr把指标序列注册为 K 线的一个附加列,列名(此处ATR_atr)会作为该图形的标识; - 图板列:
klines["ATR_atr.board"] = "ATR_atr"指定渲染到哪个图板,值可以是任意字符串,同一字符串表示同一副图;缺省(不设置.board)时默认绘制在主图"MAIN"; - 颜色与宽度列:
klines["ATR_tr.color"]控制颜色、klines["ATR_tr.width"]控制折线宽度。
从源码看,api._process_chart_data_for_web(tqsdk/api.py)在推送绘图数据时读取这些附加列:board = data.get(".board", ["MAIN"])[-1],即未设置时默认主图;color 缺省为 #FF0000(红色)、width 缺省为 1,并支持 LINE、DOT、DASH、BAR 等样式。因此绘图列命名规律是:主列名 xxx + 属性后缀 .board / .color / .width。
4.2 同时绘制 TR 与 ATR 两个副图,并自定义颜色与宽度
文档的完整示例(两副图同时展示 atr.tr 与 atr.atr):
# 在副图以折线形态显示 atr.tr 数据
klines["ATR_tr"] = atr.tr
# ATR_tr.board 为选择图板,可选,缺省为 "MAIN" 表示绘制在主图
klines["ATR_tr.board"] = "ATR_tr"
# ATR_tr.color 为文本颜色,可选,缺省为红色
klines["ATR_tr.color"] = 0xFF00FF00
# ATR_tr.width 为折线宽度,可选
klines["ATR_tr.width"] = 3
# 创建另外副图显示 atr.atr 数据
klines["ATR_atr"] = atr.atr
klines["ATR_atr.board"] = "ATR_atr"
# 通过 api.wait_update() 将绘图信息发送给天勤终端
api.wait_update()
api.close()
颜色取值两种方式(源码 tqsdk/api.py 中 color 既支持字符串也支持整数,字符串原样透传、整数转 int 后按 ARGB 解析):
- 字符串形式:CSS 颜色命名,如
"green"、"#00FF00"、"rgb(0,255,0)"、"rgba(0,125,0,0.5)"; - 整数形式:十六进制 ARGB,如
0xFF00FF00表示不透明绿色(前两位FF为 alpha),0xFF9933CC表示紫色。
运行上述代码后,天勤终端会额外绘制 atr.atr、atr.tr 两个副图,效果如下:
五、进阶绘图:draw_line / draw_text / draw_box 图形 API
除"附加列"方式外,TqSdk 还提供三个直接绘图函数(均定义于 tqsdk/api.py):
| 函数 | 用途 | 关键参数 |
|---|---|---|
api.draw_text(klines, text, x, y, ...) |
在行情图上绘制字符串 | x/y 为坐标(x 以 K 线序列号表示,缺省对齐最后一根 K 线及收盘价),id 相同则后一次覆盖前一次,board 缺省 "MAIN",color 缺省 "red" |
api.draw_line(klines, x1, y1, x2, y2, ...) |
绘制直线/线段/射线 | line_type 目前支持 "SEG" 线段,width 缺省 1,color 缺省 "red" |
api.draw_box(klines, x1, y1, x2, y2, ...) |
绘制矩形方框 | bg_color 填充色缺省 "black",color 边框色缺省 "red",width 缺省 1 |
draw_text / draw_line / draw_box 三者的坐标 x 均支持负偏移(-1 表示最后一根 K 线、-5 表示倒数第 5 根),内部通过 _offset_to_x 转换为绝对序列号;board 参数同样可指定任意副图,例如 board="B2"。典型用法(对应示例程序 t92.py、t93.py):
# 在主图最后一根K线上画线段以标注信号
api.draw_line(klines, -1, klines.iloc[-1].close, -1, klines.iloc[-1].high,
line_type="SEG", color=0xFFFF9900, width=3)
# 绘制字符串
api.draw_text(klines, "信号1", x=-1, y=klines.iloc[-1].high + 5, color=0xFFFF3333)
# 给主图最后5根K线加一个方框
api.draw_box(klines, x1=-5, y1=klines.iloc[-5]["high"], x2=-1, y2=klines.iloc[-1]["low"],
width=1, color=0xFF0000FF, bg_color=0x7000FF00)
六、更多画图示例:官方教程 t90 – t96
文档末尾提示"更多的画图示例在示例程序 t90 – t95",仓库中实际提供了 t90–t96 七个画图教程(位于 tqsdk/demo/tutorial/),覆盖了全部常见绘图形态:
| 示例 | 主题 | 关键代码位置 |
|---|---|---|
| t90.py | 在主图中画指标线 | klines["ma_MAIN"] = ma.ma(不设 board 即主图) |
| t91.py | 在附图中画指标线(循环内实时更新) | klines["ma_B2.board"] = "B2"、颜色/宽度自定义 |
| t92.py | 在主图画信号线及文字标注 | draw_line + draw_text + draw_box |
| t93.py | 在主图画线和方框(条件触发) | if high - low > 0.05: 后按 K 线 id 绘图 |
| t94.py | 在附图中画另一合约的 K 线 | 同时设置 .open/.high/.low/.close 四列与 .board |
| t95.py | 同一附图中画 K 线、线段和方框 | draw_line/draw_box 的 board="B2" 指定副图 |
| t96.py | 在附图中画 MACD 指标 | 用 K 线形态模拟 MACD 柱状图 + diff/dea 折线 |
以 t91.py 为例,它演示了两种核心技巧:
- 循环内绘图:把
MA(klines, 30)计算与附加列赋值放在while True: api.wait_update()循环内,图像即可随行情推进持续更新; - 多副图组织:
ma_B2挂在副图B2、ma_4挂在副图MA4,同一字符串即同一图板,任意字符串均可作为副图名。
while True:
ma = MA(klines, 30)
# 示例1: 在附图中画一根绿色的 ma 指标线
klines["ma_B2"] = ma.ma
klines["ma_B2.board"] = "B2"
klines["ma_B2.color"] = "green" # "green" / "#00FF00" / "rgb(0,255,0)" 均可
# 示例2: 在另一个附图画一根宽度为4的紫色指标线
klines["ma_4"] = ma.ma - 4
klines["ma_4.board"] = "MA4"
klines["ma_4.color"] = 0xFF9933CC # 或者 "#9933FF"
klines["ma_4.width"] = 4 # 宽度,默认为 1
api.wait_update()
注意:t90–t96 示例中部分启用了 web_gui=True(或 web_gui=":9878" 指定 ip 与 port),表示通过浏览器查看绘图结果,且程序用 while True 保持运行不能退出;若不使用 web_gui,则绘图结果由天勤终端或 VS Code 插件渲染。画图示例中的行情数据不具实际意义,请按自己的策略合约与周期替换。
七、VS Code 插件环境下的绘图与配套能力
若选择 VS Code 天勤插件路线(详见 doc/devtools/vscode.rst),其与 TqSdk 代码完全兼容,绘图输出会自动出现在右侧天勤面板:
- 安装与配置:在 VS Code 扩展市场搜索"天勤量化"或 "tqsdk" 安装,同时需安装 Python 插件;右键策略文件选择【设置天勤参数】,配置实盘交易账号(选填)与快期账号(必填,无账号可前往快期注册);
- 运行:右键菜单选择【在实盘中运行】或【在模拟账户中运行】,右侧面板输出策略日志与绘图;策略报单与 print 输出会自动保存到 reports 目录;
- 回测:右键提供默认【回测7天】/【回测30天】,也可在【设置天勤参数】中自定义回测区间(回测为专业版功能);
- 复盘:配置复盘日期后右键【复盘模式运行策略文件】,上方面板可暂停、加速/减速复盘;
- 打包:右键【策略程序打包成独立应用程序】可将策略打包为独立可执行程序。
需要注意:当右键菜单设置的账户信息与代码中不一致时,以右键设置的账户信息为准;停止运行/回测策略可用 Ctrl + C 或终端右上角垃圾桶按钮。
八、常见问题与注意事项
- 指标序列长度不足:
ma(series, n)在序列元素不足 n 个时返回 NaN(tqsdk/tafunc.py),因此绘图前期可能出现空值,可适当调大get_kline_serial的data_length(如 t96.py 用 200 根); - 不要动原始列:修改/重命名 K 线的
open/high/low/close等原始列会导致数据不更新,绘图只应新增附加列; - 副图命名:
.board值任意字符串,同一字符串合并到同一副图;主图缺省值为"MAIN"; - 颜色格式:字符串形式遵循 CSS 规范,整数形式为 ARGB(如
0xFF00FF00),两者可混用; - 账户与权限:绘图功能依赖 TqSdk 客户端与快期账户的正常连接;回测功能属于 TqSdk 专业版能力,需相应权限。
综上,从 tqsdk.ta.ATR 的公式级实现,到 K 线附加列 .board/.color/.width 的渲染约定,再到 draw_line/draw_text/draw_box 与 t90–t96 官方示例,TqSdk 提供了一套"计算与可视化一体"的指标绘图体系,足以支撑各类策略的实时图形化监控与信号标注需求。

