行情与数据

本页定义 MarketData 的输入、时点和验证规则。分红送转见权益模型,沪深预设见市场支持矩阵。

接入数据

分钟入口为 MarketData.from_minutes:日期日历仍只含交易日,行提供带 +08:00 的 timestamp 及 phase,frequency 为 1min/5min。每个日期/证券必须覆盖完整时段网格,详见分钟数据与时间契约。以下日线契约适用于 from_records/from_csv。

MarketData.from_records(rows, calendar=..., instruments=..., rules=..., source=..., actions=..., adjustments=...) 接受字典行;MarketData.from_csv(path, ...) 接受相同字段的 UTF-8 CSV(允许 BOM)。构造后数据不可修改,行自动按交易日和声明的证券顺序排列。交易日、证券、规则和来源由数据提供层组织一次,策略只接收验证后的对象,不重复填写规则。

完整人工数据示例见 market_data.py。沪深股票与 ETF 可通过 china_rules 使用历史预设;自定义规则通过 RuleBook 声明有效期、来源和版本。

价格和状态

每个交易日、每个证券恰有一行,字段全部必需:

字段

契约

session, symbol

严格的日期和证券标识;不从文件名或列位置猜测

status

trading、suspended、unlisted、delisted,未知值报错

open, high, low, close

人民币元、原始未复权 OHLC;交易及停牌日必须明确提供估值,不隐式前填

volume

股/份,非负整数;停牌、上市前及退市后为零

upper_limit, lower_limit

当日真实价格边界,两个值一起提供;确认无限制时两个字段均为空,不能缺列

上市前和退市后必须有显式行,价格及边界为空;它们在 prices("close") 等只读矩阵中返回 NaN。证券不能从已上市回到未上市,也不能在退市后重新交易。交易日历必须非空、严格递增,缺行、重复行、日历外数据和未知证券全部报错。使用独立交易所日历,缺失的整日行情也会在构造时被发现。

报价内部按万分之一元精确存储,随后按当期最小价位检查。不支持的精度和非有限数值直接报错,不自动四舍五入行情。指标层获得元为单位的浮点数组;此数组不会被用于反向修正账本。复权研究价单独定义时点和用途,不作为记账价格输入。

按决策时点复权的研究视图

data.prices("close") 默认仍是整个输入的原始价矩阵;传 as_of="2025-01-06" 只返回截至该输入交易日的行。data.prices("close", adjustment="asof", as_of=...) 要求显式时点;策略可直接使用 ctx.history(symbol, adjustment="asof", bars=20),其时点固定为当前回调收盘,无须手工传日期。OHLC 四个字段遵循同一规则,输出为只读浮点副本。

数据准备时通过 adjustments 提供 PriceAdjustment(action_id=..., factor=..., known_on=..., source=...):

  • action_id 必须对应输入中的公司行动,除权日和证券沿用该事件;不能重复或引用未知事件。

  • factor 是单次事件把除权日前价格换算到事件后价格口径的乘法系数,非供应商截至今天的累计复权因子。它必须正且有限,当前数值范围为 1e-100 至 1e100。

  • known_on 为该因子可被研究者获知的日期,不早于事件公告。只有除权日已到、因子也已知时才能用于该历史视图。未来事件即便提前公告也不会提前调整。

  • 视图每跨过一次事件,就把该事件之前的行乘相应因子;事件日及之后不乘这个因子。多个日期事件按顺序组合,不跨事件的短窗口无须因子。请求的证券不会被其他证券缺失因子阻断。

  • 已跨过事件而当时没有可用因子时明确失败,不退回原始价,不偷用后来补齐的值。复权计算出现数值溢出或下溢也明确失败。数据准备时提供完整事件表及对应因子。

普通现金分红/送转的理论参考比例可由 ((前收盘价-每股参考现金额)/(1+参考送转比例))/前收盘价 得到。但参考现金额不一定等于账户应得现金,例如差异化分派中不参与分配的回购股份会改变摊薄口径,因此引擎不从账户 cash_per_share 自动猜复权因子。参考深交所公式说明与差异化分派公告示例。事件因子由提供层根据适用规则、行情或有来源的供应商数据准备,并记录口径;不同供应商的舍入与累计方式可能不同。

复权视图用于计算连续价格指标;账户继续按原始价估值,并分别处理分红、税款和送转。示例 historical_rules.py 将人工原始收盘价 [18.5, 18.5, 10] 换算为除权日视图 [10, 10, 10],并独立保持原始成交和税务结果。

历史规则

Instrument 明确 symbol 和 stock/etf 分类。证券代码是标识,引擎不根据前缀推断市场制度。RuleBook 包含有起止日期(两端含)、来源与版本的 RulePeriod,禁止区间重叠,活动行情对应的日期必须存在规则。

TradingRule 表达价位、买卖最小量和增量、单笔数量上限、交易日交收延迟、是否允许零股清仓,以及卖出印花税率与双向过户费率。比例使用小数(例如 0.0005),最多六位小数。佣金、滑点和成交策略属于执行配置,不混入历史市场事实。买入数量满足最小量后按增量增加,交收延迟按后续交易日计数。规则可附 instrument_kind 约束,防止股票与 ETF 规则误用;自定义中性规则可留空。

规则按证券和有效日期查询,过期或缺失规则会明确报错。china_rules 核验范围为 2015-09-09 至 2026-10-12(科创板从 2019-07-22 起),普通股票与支持的 ETF 分类见市场规则。按证券/profile 和日期覆盖后,每段保留基础来源与覆盖摘要;规则包版本、分类与覆盖声明也进入数据指纹。不推断每日特殊状态或价格边界。

公司行动

CorporateAction 保留唯一事件标识、证券、公告/登记/除权日期和来源。cash_per_share 按每股税前金额填写并附 pay_date;bonus_per_share 按每股增加数量填写,附 share_credit_date 和 share_listing_date,分别表示入账和上市可卖。现金及送转应税金额支持六位小数;股票送转必须显式提供 taxable_bonus_amount_per_share,免税转增填零,不从送转比例猜税基。

distribution 至少包含现金或送转;登记必须早于除权,到账和上市不得早于除权,股份入账不能晚于上市。样本范围内的登记、除权、股份入账和上市日必须在输入日历中;现金到账落在非输入交易日时,在之后首个输入交易日开盘处理。允许样本结束后的到账/上市日期,结果保留未到账权益或未解锁股份。

配股、合并、退市作为其他显式事件保留,不暗中转换成分红。未支持行动影响持仓、登记权益、未到账权益或活动委托时明确失败。完全未持有且无相关权益、委托的证券发生该事件,不自动使整个组合失败。

同一证券同一除权日目前只接受一个综合公司行动。现金和送转应放在同一个分配事件中;不能用不同事件 ID 重复表示同一权益,也不猜测多个事件之间的股份计算基数。数据准备层须合并可确定的同日分派事实,不能合并的复合行动不在当前执行支持范围内。此限制避免持续目标在同日被重复复合调整。

输入指纹

fingerprint 覆盖交易日、证券顺序、原始行情、状态/价格边界、历史规则、公司行动、研究复权因子及其可知日期和来源。等价的 CSV 行顺序与规则输入顺序得到相同标识;声明的证券顺序则保留,因为后续共同现金的订单处理需要确定顺序。可以用它检查两次运行是否使用相同输入。

字段转换和输入检查可参考数据到报告。历史 ETF 的账户与成交核对资料见案例记录。