Vibe-Trading 数据技能实战：Tushare `suspend_d` 每日停复牌信息接口解析与量化应用

Vibe-Trading 数据技能实战：Tusharesuspend_d每日停复牌信息接口解析与量化应用

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading

导读

本指南围绕 Vibe-Trading 仓库内 tushare 数据技能中的suspend_d（每日停复牌信息）接口文档，系统讲解该接口的输入输出参数、调用方式、返回数据结构，并结合仓库内的事件驱动技能（corporate-events）说明停复牌数据在 A 股量化研究中的典型应用场景。读者将掌握通过ts.pro_api()提取全市场停复牌列表、按股票代码与日期区间回溯停牌历史、以及将停复牌信号接入组合构建与风险控制流程的具体方法。

一、接口概览：suspend_d能提供什么

suspend_d是 tushare 提供的"按日期方式获取股票每日停复牌信息"的 Pro 接口，在仓库中登记于 tushare 技能接口列表，归属于"股票数据 / 行情数据"分类。其核心能力是回答三个问题：

1. 某一天有哪些股票停牌（suspend_type='S'）；
2. 某一天有哪些股票复牌（suspend_type='R'）；
3. 某只股票在一段时间内的停复牌事件历史（按ts_code+ 起止日期查询）。

该接口按"交易日 + 事件类型"组织数据，适合做截面（cross-section）扫描和事件时间线（event timeline）回溯，而非像daily（历史日线）那样提供连续的价格序列。

接口基础属性：

二、输入参数详解

suspend_d的全部入参均为可选参数（必选列均为 N），这意味你可以只传其中一个维度（如只传trade_date）来扫描全市场，也可以组合多个维度进行精确过滤。

参数使用要点：

• 日期格式统一为YYYYMMDD：这与 tushare 技能文档约定的全局参数规范一致（SKILL.md 中明确"日期：YYYYMMDD，如 20241231"）。传入2020-03-12或20200312之外的带分隔符格式不会被识别。
• ts_code支持多值：可一次传入多只股票代码，格式如000001.SZ,600000.SH，便于批量跟踪持仓停复牌状态。
• trade_date与start_date/end_date是两种查询口径：前者查询"指定某一天"的停复牌事件，后者查询"某时间段内"发生的全部事件。若同时给定，以区间查询为主、单日过滤为辅，实际使用中建议按需选择其一，避免参数冲突。
• suspend_type用于区分事件方向：S表示当天进入停牌状态，R表示当天恢复交易。忽略该参数时返回停复牌两类事件的混合结果。

三、输出参数与数据结构

每次调用返回一个 pandasDataFrame，共 4 个字段：

其中suspend_timing是全日停牌与日内临时停牌的关键区分字段：当日 26 只停牌股票中，300819.SZ、300821.SZ两条记录带有09:30-10:00的时间段，说明它们是日内临时停牌（如盘中重大事项、股价异动核查），其余记录该字段为None（空值），表示从开盘起全天停牌。解析该字段时要注意None的判空处理，不能直接当作字符串。

四、接口用法与实战代码

4.1 基础调用

文档给出的最小可用示例如下：

import tushare as ts pro = ts.pro_api() # 提取2020-03-12的停牌股票 df = pro.suspend_d(suspend_type='S', trade_date='20200312')

4.2 初始化与 Token 管理（仓库标准姿势）

直接调用ts.pro_api()依赖本地已保存的 token。在 Vibe-Trading 仓库中，更推荐的做法是从环境配置中读取 token，参见 stock_data_example.py 的初始化方式：

import os import tushare as ts from src.config.accessor import get_env_config # 优先读取仓库环境配置中的 tushare_token，兜底使用本地记录的 token token = get_env_config().data.tushare_token or ts.get_token() pro = ts.pro_api(token)

离线环境下的环境变量配置方式（SKILL.md）：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple export TUSHARE_TOKEN=your_token

4.3 按场景扩展调用

在基础示例之上，可以按以下维度扩展查询能力：

# 场景一：查询某一天全部复牌股票 df_resume = pro.suspend_d(suspend_type='R', trade_date='20200313') # 场景二：查询单只股票在时间区间内的停复牌历史 df_stock = pro.suspend_d( ts_code='300104.SZ', start_date='20200101', end_date='20201231' ) # 场景三：查询区间内全部停牌事件（不带类型过滤，返回 S/R 混合） df_range = pro.suspend_d(start_date='20200310', end_date='20200314') # 场景四：指定返回字段，减少带宽与内存开销 df_cols = pro.suspend_d( trade_date='20200312', suspend_type='S', fields='ts_code,suspend_timing' )

4.4 返回数据样例解读

以suspend_type='S', trade_date='20200312'的调用为例，返回DataFrame前若干行为：

对该样例的实用解读：

• 当日全市场 26 只股票处于停牌状态，其中24 只为全天停牌（suspend_timing=None），2 只为日内临时停牌（300819.SZ、300821.SZ，时间段09:30-10:00）；
• 覆盖沪深两市多个板块（000/002/300开头为深市，600/601/603开头为沪市），可用于观察当日停牌面的行业与板块分布；
• ts_code中的后缀.SZ/.SH分别对应深交所与上交所，字段格式与 tushare 全局 TS 代码规范一致。

五、停复牌数据在量化流程中的应用

5.1 数据正确性治理：剔除停牌日

停牌期间股票没有连续成交，其价格序列存在缺口，直接进入因子计算或回测会产生虚假信号。从源码结构看，仓库的量价因子基座已针对"停牌 bar"做了专门处理（见 agent/src/factors/base.py 中关于 suspended bars 的处理逻辑）。实践中可以用suspend_d生成的停牌日历，对日线数据做如下对齐：

import pandas as pd # 拉取某区间停牌事件，构造 (ts_code, trade_date) 停牌掩码 sus = pro.suspend_d(start_date='20200101', end_date='20201231') sus_mask = set(zip(sus['ts_code'], sus['trade_date'])) # 过滤掉因子/收益序列中的停牌日 clean = df_daily[ ~df_daily.apply( lambda r: (r['ts_code'], r['trade_date']) in sus_mask, axis=1 ) ]

5.2 事件驱动研究：停复牌节奏信号

仓库的 corporate-events 技能 明确指出 A 股并购重组研究需"关注'筹划重大资产重组'公告 → 停牌 → 复牌的节奏"，并提示"停牌制度改革后，复牌首日涨跌幅受限（创业板/科创板 20%）"。suspend_d为这一事件链提供了机械化的事件时间戳：

# 提取某标的全年停复牌时间线 df_ev = pro.suspend_d(ts_code='600074.SH', start_date='20200101', end_date='20201231') # 按 trade_date 排序后即可还原: 停牌日(S) -> 复牌日(R) 的交替节奏 timeline = df_ev.sort_values('trade_date')

结合R类事件可构建"复牌首日涨跌幅受限"策略的观察样本，为事件窗口收益统计（如公告后 3 日、20 日窗口）提供事件日期来源。

5.3 组合风控：持仓停牌监控

对实盘组合而言，持仓股票突然停牌会带来流动性风险与估值不确定性问题。可按日扫描持仓代码的停牌状态：

holdings = ['000029.SZ', '300104.SZ', '600074.SH'] df_hold = pro.suspend_d(ts_code=','.join(holdings), trade_date=today_str) suspended_now = set(df_hold[df_hold['suspend_type'] == 'S']['ts_code']) print(f"今日停牌持仓: {suspended_now}")

该结果可作为交易执行前的拦截信号：对停牌中的标的跳过撮合、暂停目标权重调整，避免产生"挂单永不成交"的无效订单。

六、使用注意事项与限制

1. 更新不定期：suspend_d的更新频率为"不定期"，与daily（每日收盘后）、stk_limit（每日涨跌停价格，每个交易日 8:40 左右更新）等固定节奏接口不同。用于盘前风控时，应以当日实际返回结果为准，不能假设盘前必有当日数据。
2. 接口权限：tushare Pro 接口普遍与用户积分挂钩（如stk_limit需 2000 积分且有分钟级流控），suspend_d同样需要账户具备相应访问等级，具体以 tushare 官方积分规则为准。
3. suspend_timing空值语义：None表示全天停牌而非数据缺失，解析时需区分"无该字段信息"与"全日停牌"两种含义。
4. 事件类型区分：S（停牌）与R（复牌）是两条独立记录，统计"停牌次数"时应先按suspend_type分组，避免把复牌事件误计入停牌计数。
5. 历史覆盖：与 tushare 其他行情接口一样，数据回溯能力受账户权限与积分档位影响，大区间历史回溯建议按start_date/end_date分片循环拉取，控制单次请求数据量。

七、小结

suspend_d是 A 股停复牌事件研究的基础数据源：输入侧通过trade_date/start_date/end_date控制时间维度、ts_code控制标的维度、suspend_type控制事件方向；输出侧用suspend_timing区分全天停牌与日内临时停牌。在 Vibe-Trading 仓库中，它既服务于因子层的数据清洗（剔除停牌 bar），也与 corporate-events 的事件驱动研究形成配套——从"停牌日历"到"重组节奏事件链"再到"持仓风控拦截"，覆盖了从数据治理到策略构建的完整链路。建议读者在 tushare 技能目录 基础上，结合 股票数据获取示例脚本 快速上手，并优先用fields参数精简返回列，降低调用开销。

【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading