TDX 数据接口与策略评价工具文档

1. 概述

本项目提供了基于通达信（TDX）数据的Python接口封装和策略评价工具，主要包含三个模块：

1. tqcenter.py - TDX数据接口核心封装
2. tdxvbt.py - 基于VectorBT的策略评价工具
3. test.py - 使用示例和功能测试

2. 文件说明

2.1 tqcenter.py - TDX数据接口

这是核心的数据访问模块，封装了通达信DLL的调用接口，提供股票数据获取、财务数据、板块数据等功能。

2.1.1 主要功能

• K线数据获取（支持多种周期）
• 财务数据获取（支持多张报表）
• 板块数据获取
• 权息数据获取
• 数据订阅（回调机制）
• 交易下单接口
• 合约详细信息获取

2.1.2 初始化与连接管理

class tdxdata:
    @classmethod
    def initialize(cls, path: str)
    """初始化TDX数据连接"""
    
    @classmethod
    def close(cls)
    """关闭TDX数据连接"""

参数：

• path: 连接路径，通常使用__file__传递当前文件路径

示例：

tdxdata.initialize(__file__)
# ... 使用数据接口
tdxdata.close()

2.1.3 数据获取函数

get_market_data - 获取K线数据

@classmethod
def get_market_data(cls,
                   field_list: List[str] = [],
                   stock_list: List[str] = [],
                   period: str = '',
                   start_time: str = '',
                   end_time: str = '',
                   count: int = -1,
                   dividend_type: Optional[str] = None,
                   fill_data: bool = True) -> Dict

功能： 获取股票K线数据（支持日线、分钟线、tick数据）

参数说明：

• field_list: 字段列表，如['Open', 'High', 'Low', 'Close', 'Volume']，空列表返回所有字段
• stock_list: 股票代码列表，如['600519.SH', '000001.SZ']
• period: 数据周期，支持：'1d'（日线）、'1m'、'5m'、'15m'、'30m'、'60m'、'1w'、'tick'等
• start_time: 开始时间，格式'YYYYMMDD'或'YYYYMMDDHHMMSS'
• end_time: 结束时间，格式同上
• count: 数据条数，当count>0时，从结束时间向前取count条
• dividend_type: 复权类型，'none'（不复权）、'front'（前复权）、'back'（后复权）
• fill_data: 是否填充缺失数据

返回值： 字典格式，键为字段名，值为pd.DataFrame（列名为股票代码，索引为时间）

示例：

# 获取贵州茅台日线数据
data = tdxdata.get_market_data(
    field_list=['Open', 'High', 'Low', 'Close', 'Volume'],
    stock_list=['600519.SH'],
    start_time='20240101',
    end_time='20241231',
    period='1d',
    dividend_type='front',
    fill_data=True
)
print(data['Close'])  # 获取收盘价数据

get_financial_data - 获取财务数据

@classmethod
def get_financial_data(cls,
                      stock_list: List[str] = [],
                      table_list: List[str] = [],
                      start_time: str = '',
                      end_time: str = '',
                      report_type: str = 'report_time') -> Dict

功能： 获取股票财务数据

参数说明：

• stock_list: 股票代码列表
• table_list: 财务报表类型列表，如['Balance', 'Income', 'CashFlow']，'ALL'获取所有报表
• start_time: 开始时间
• end_time: 结束时间
• report_type: 报告类型，'report_time'（报告期）或'announce_time'（公告时间）

返回值： 字典格式，键为股票代码，值为嵌套字典（键为报表类型，值为pd.DataFrame）

示例：

# 获取贵州茅台资本结构数据
fd = tdxdata.get_financial_data(
    stock_list=['600519.SH'],
    table_list=['Capital'],
    start_time='20240101',
    end_time=''
)
print(fd['600519.SH']['Capital'])

get_divid_factors - 获取权息数据

@classmethod
def get_divid_factors(cls,
                     stock_code: str,
                     start_time: str,
                     end_time: str) -> pd.DataFrame

功能： 获取股票的除权除息数据

参数说明：

• stock_code: 股票代码
• start_time: 开始时间
• end_time: 结束时间

返回值： pd.DataFrame，包含以下列：

• Date: 除权除息日
• Type: 类型
• Bonus: 每10股分红
• AllotPrice: 配股价
• ShareBonus: 每10股送股
• Allotment: 每10股配股

示例：

divid_factors = tdxdata.get_divid_factors(
    stock_code='600519.SH',
    start_time='20200101',
    end_time='20241231'
)
print(divid_factors)

get_sector_list - 获取板块列表

@classmethod
def get_sector_list(cls) -> List

功能： 获取所有板块列表

返回值： 板块名称列表

示例：

block_list = tdxdata.get_sector_list()
print(f"板块数量: {len(block_list)}")
print(block_list[:10])  # 打印前10个板块

get_stock_list_in_sector - 获取板块成分股

@classmethod
def get_stock_list_in_sector(cls, block_code: str) -> List

功能： 获取指定板块的成分股列表

参数说明：

• block_code: 板块名称

返回值： 股票代码列表

示例：

# 获取"钛金属"板块成分股
titanium_stocks = tdxdata.get_stock_list_in_sector('钛金属')
print(f"钛金属板块成分股数量: {len(titanium_stocks)}")
print(titanium_stocks[:10])

2.1.4 其他重要函数

subscribe_quote - 订阅行情数据回调

@classmethod
def subscribe_quote(cls,
                   stock_code: str,
                   period: str = '1d',
                   start_time: str = '',
                   end_time: str = '',
                   count: int = 0,
                   dividend_type: Optional[str] = None,
                   callback = None)

功能： 订阅单只股票的行情数据回调

参数说明：

• stock_code: 股票代码
• period: 数据周期
• start_time: 开始时间
• end_time: 结束时间
• count: 数据条数
• dividend_type: 复权类型
• callback: 回调函数，接收数据字符串

返回值： 订阅标识符

示例：

def my_callback(data_str):
    print(f"收到数据: {data_str}")
    # 解析JSON数据
    data = json.loads(data_str)
    print(f"股票: {data['Code']}, 时间: {data['Date']}")

# 订阅数据
ptr = tdxdata.subscribe_quote(
    stock_code='600519.SH',
    period='1d',
    start_time='20240101',
    end_time='20241231',
    callback=my_callback
)

order_stock - 股票下单

@classmethod
def order_stock(cls,
               account: str,
               stock_code: str,
               order_type: int,
               order_volume: int,
               price_type: int,
               price: float,
               strategy_name: str,
               order_remark: str = '') -> Dict

功能： 股票交易下单

参数说明：

• account: 账户号
• stock_code: 股票代码
• order_type: 委托类型（1-买入，2-卖出等）
• order_volume: 委托数量
• price_type: 价格类型
• price: 委托价格
• strategy_name: 策略名称
• order_remark: 委托备注

返回值： 下单结果字典

示例：

result = tdxdata.order_stock(
    account='123456',
    stock_code='600519.SH',
    order_type=1,  # 买入
    order_volume=100,
    price_type=1,  # 限价
    price=1800.0,
    strategy_name='MyStrategy',
    order_remark='测试订单'
)
print(f"下单结果: {result}")

send_result - 发送结果到主程序

@classmethod
def send_result(cls, result_str: str) -> Dict

功能： 发送自定义结果到主程序

参数说明：

• result_str: 结果字符串，支持多种格式：
  • "XG,股票代码|筛选条件" - 选股结果
  • "MSG,消息内容" - 文本消息
  • "FILE,文件名,文件内容" - 文件内容

返回值： 发送结果字典

示例：

# 发送选股结果
result = tdxdata.send_result("XG,1#600001|0#000010|1#600011|0#000020")

# 发送文本消息
tdxdata.send_result("MSG,策略执行完成，共选出5只股票")

# 发送文件内容
tdxdata.send_result("FILE,Report.txt,回测报告内容...")

2.2 tdxvbt.py - 策略评价工具

基于VectorBT的策略评价类，支持内部获取基准数据并进行全面评价。

2.2.1 evaluation类

class evaluation:
    def __init__(self,
                 vbt_portfolio: vbt.Portfolio,
                 benchmark_code: str,
                 start_time: str,
                 end_time: str,
                 annualization_factor_full: int = 252,
                 period: str = '1d')

功能： 策略评价类构造函数

参数说明：

• vbt_portfolio: VectorBT生成的Portfolio对象
• benchmark_code: 基准代码，如'000300.SH'
• start_time: 回测开始时间，格式'YYYY-MM-DD'
• end_time: 回测结束时间，格式'YYYY-MM-DD'
• annualization_factor_full: 年化因子，默认252（交易日）
• period: 数据周期，默认'1d'

初始化过程：

1. 内部调用tdxdata.get_market_data获取基准数据
2. 提取策略净值数据
3. 对齐策略与基准的时间轴
4. 计算各类评价指标

2.2.2 主要方法

show_metrics - 显示评价指标

def show_metrics(self) -> None

功能： 在控制台显示所有评价指标

示例输出：

================================================================================
策略评价报告（基准：000300.SH）
================================================================================
基准代码              : 000300.SH
回测时间范围          : 2024-01-01 ~ 2024-12-31
实际交易日数          : 245
年化因子              : 1.03
策略总收益率（%）      : 15.23
基准总收益率（%）      : 8.45
策略年化收益率（%）    : 15.67
基准年化收益率（%）    : 8.72
年化超额收益率（%）    : 6.95
策略年化波动率（%）    : 18.34
基准年化波动率（%）    : 15.67
超额收益年化波动率（%） : 8.23
Alpha（年化，%）      : 5.23
Beta                 : 0.85
信息比率（IR）        : 0.84
策略最大回撤（%）      : -12.34
基准最大回撤（%）      : -15.67
相对最大回撤（%）      : -5.23
超额收益胜率（%）      : 55.67
================================================================================

plot_equity_curve - 绘制净值曲线

def plot_equity_curve(self, figsize: tuple = (12, 6)) -> None

功能： 绘制策略与基准的净值对比图

参数说明：

• figsize: 图形尺寸，默认(12, 6)

plot_excess_returns - 绘制超额收益

def plot_excess_returns(self, figsize: tuple = (12, 4)) -> None

功能： 绘制超额收益时序图和累计超额收益图

get_metrics_df - 获取指标DataFrame

def get_metrics_df(self) -> pd.DataFrame

功能： 以DataFrame形式返回所有评价指标

返回值： pd.DataFrame，索引为指标名称，列为指标值

2.2.3 使用示例

import vectorbt as vbt
import pandas as pd
from tdxvbt import evaluation

# 1. 使用VectorBT创建策略组合（示例）
price_data = vbt.YFData.download('AAPL', start='2024-01-01', end='2024-12-31').get('Close')
fast_ma = vbt.MA.run(price_data, 20)
slow_ma = vbt.MA.run(price_data, 50)
entries = fast_ma.ma_crossed_above(slow_ma)
exits = fast_ma.ma_crossed_below(slow_ma)

portfolio = vbt.Portfolio.from_signals(
    price_data, 
    entries, 
    exits,
    init_cash=100000,
    fees=0.001
)

# 2. 创建评价对象
eval_obj = evaluation(
    vbt_portfolio=portfolio,
    benchmark_code='000300.SH',  # 沪深300作为基准
    start_time='2024-01-01',
    end_time='2024-12-31',
    annualization_factor_full=252,
    period='1d'
)

# 3. 显示评价结果
eval_obj.show_metrics()
eval_obj.plot_equity_curve()
eval_obj.plot_excess_returns()

# 4. 获取指标DataFrame
metrics_df = eval_obj.get_metrics_df()
print(metrics_df)

2.3 test.py - 功能测试示例

该文件展示了各个功能模块的使用方法，包括：

1. 数据获取示例 - K线数据、财务数据、板块数据
2. 数据订阅示例 - 回调函数的使用
3. 权息数据获取 - 除权除息数据
4. 结果发送示例 - 发送选股结果、消息、文件

2.3.1 运行环境要求

pip install numpy pandas tqdm matplotlib vectorbt scikit-learn

2.3.2 主要功能演示

基础数据获取

# 初始化连接
tdxdata.initialize(__file__)

# 获取K线数据（已注释，可按需启用）
# df = tdxdata.get_market_data(
#     field_list=['Close', 'Volume'],
#     stock_list=['600519.SH'],
#     start_time='20240101',
#     end_time='20241231',
#     period='1d',
#     dividend_type='front'
# )

# 获取财务数据
fd = tdxdata.get_financial_data(
    stock_list=['600519.SH'],
    table_list=['Capital'],
    start_time='20240101',
    end_time=''
)
print(fd)

# 获取板块成分股
block_stocks = tdxdata.get_stock_list_in_sector('钛金属')
print(block_stocks)

数据订阅（回调模式）

def my_callback_func(data_str):
    print(f"回调收到数据: {data_str}")
    return None

# 注册数据回调
ptr = tdxdata.subscribe_quote(
    stock_code='600519.SH',
    period='1d',
    start_time='20240101',
    end_time='20241231',
    count=10,
    dividend_type='none',
    callback=my_callback_func
)
print(f"订阅标识: {ptr}")

权息数据获取

# 获取权息数据
divid_factors = tdxdata.get_divid_factors(
    stock_code='600519.SH',
    start_time='19000508',
    end_time='20250925'
)
print(divid_factors)

3. 注意事项

3.1 数据格式说明

1. 股票代码格式：支持多种格式

   • 简单格式：'600519'
   • 带市场后缀：'600519.SH'、'000001.SZ'、'300001.BJ'
   • 系统会自动进行格式转换

2. 时间格式：

   • 短格式：'YYYYMMDD'（如'20240101'）
   • 长格式：'YYYYMMDDHHMMSS'（如'20240101100000'）
   • 函数内部会自动转换

3. 返回值格式：

   • K线数据：字典，键为字段名，值为DataFrame
   • 财务数据：嵌套字典，第一层为股票代码，第二层为报表类型
   • 板块数据：列表格式

3.2 错误处理

1. 连接错误：确保TDX客户端正常运行
2. 数据错误：检查股票代码和时间范围的有效性
3. 内存管理：及时关闭连接，释放资源

3.3 性能建议

1. 批量获取：尽量减少单次请求的股票数量
2. 数据缓存：重复使用的数据建议本地缓存
3. 异步处理：大数据量时考虑异步请求

4. 高级用法

4.1 自定义数据转换

tdxdata模块提供了price_df辅助函数，用于从返回的字典中提取价格数据：

# 获取数据
data_dict = tdxdata.get_market_data(
    field_list=['Close', 'Volume'],
    stock_list=['600519.SH', '000001.SZ'],
    period='1d',
    start_time='20240101',
    end_time='20241231'
)

# 提取收盘价DataFrame
close_df = tdxdata.price_df(data_dict, 'Close', column_names=['茅台', '平安'])
print(close_df.head())

4.2 策略回测集成

结合VectorBT进行策略回测和评价：

import vectorbt as vbt
from tqcenter import tdxdata
from tdxvbt import evaluation

# 1. 获取数据
data = tdxdata.get_market_data(
    field_list=['Close'],
    stock_list=['600519.SH'],
    start_time='20230101',
    end_time='20231231',
    period='1d',
    dividend_type='front'
)

# 2. 提取价格序列
price_series = tdxdata.price_df(data, 'Close').iloc[:, 0]

# 3. 创建简单策略（双均线）
fast_ma = vbt.MA.run(price_series, 20)
slow_ma = vbt.MA.run(price_series, 50)
entries = fast_ma.ma_crossed_above(slow_ma)
exits = fast_ma.ma_crossed_below(slow_ma)

# 4. 运行回测
portfolio = vbt.Portfolio.from_signals(
    price_series,
    entries,
    exits,
    init_cash=100000,
    fees=0.001
)

# 5. 策略评价
eval_obj = evaluation(
    vbt_portfolio=portfolio,
    benchmark_code='000300.SH',
    start_time='2023-01-01',
    end_time='2023-12-31'
)

eval_obj.show_metrics()
eval_obj.plot_equity_curve()

5. 常见问题

Q1: 如何解决中文乱码问题？

A: 在代码开头添加：

import matplotlib.pyplot as plt
plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS']
plt.rcParams['axes.unicode_minus'] = False

Q2: 数据获取失败怎么办？

A: 检查以下事项：

1. TDX客户端是否正常运行
2. 网络连接是否正常
3. 股票代码格式是否正确
4. 时间范围是否有效

Q3: 如何获取更多字段？

A: 查看get_market_data函数的实现，或尝试不指定field_list参数获取所有可用字段。

Q4: 财务数据包含哪些报表？

A: 常见报表包括：

• Balance - 资产负债表
• Income - 利润表
• CashFlow - 现金流量表
• Capital - 资本结构表
• 使用'ALL'获取所有报表

6. 版本更新

v1.0.0 (2024-12-12)

• 初始版本发布
• 支持K线数据获取
• 支持财务数据获取
• 支持板块数据获取
• 支持策略评价工具