TqSdk 技术指标绘图实战:ATR 计算、副图配置与天勤终端/VS Code 插件可视化

原创2026-10-12 13:44:521,926 阅读
文章标签:金融科技数据分析

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)。

绘图能力贯穿两条使用路径:

  1. 天勤终端:TqSdk 客户端程序运行后,把绘图数据推送给天勤终端(快期),由终端渲染 K 线与指标图形;
  2. 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 两个副图,效果如下:

TqSdk ATR 指标副图绘制效果

TqSdk ATR 指标副图自定义颜色与宽度后的效果

五、进阶绘图: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 为例,它演示了两种核心技巧:

  1. 循环内绘图:把 MA(klines, 30) 计算与附加列赋值放在 while True: api.wait_update() 循环内,图像即可随行情推进持续更新;
  2. 多副图组织: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 或终端右上角垃圾桶按钮。

八、常见问题与注意事项

  1. 指标序列长度不足:ma(series, n) 在序列元素不足 n 个时返回 NaN(tqsdk/tafunc.py),因此绘图前期可能出现空值,可适当调大 get_kline_serial 的 data_length(如 t96.py 用 200 根);
  2. 不要动原始列:修改/重命名 K 线的 open/high/low/close 等原始列会导致数据不更新,绘图只应新增附加列;
  3. 副图命名:.board 值任意字符串,同一字符串合并到同一副图;主图缺省值为 "MAIN";
  4. 颜色格式:字符串形式遵循 CSS 规范,整数形式为 ARGB(如 0xFF00FF00),两者可混用;
  5. 账户与权限:绘图功能依赖 TqSdk 客户端与快期账户的正常连接;回测功能属于 TqSdk 专业版能力,需相应权限。

综上,从 tqsdk.ta.ATR 的公式级实现,到 K 线附加列 .board/.color/.width 的渲染约定,再到 draw_line/draw_text/draw_box 与 t90–t96 官方示例,TqSdk 提供了一套"计算与可视化一体"的指标绘图体系,足以支撑各类策略的实时图形化监控与信号标注需求。

登录后查看全文
tqsdk-python