DEVELOPER CENTER

开发者中心

接口与 API

先创建 Token，再把它传给接口。请在个人主页创建 Token，完整内容仅显示一次；遗失时直接创建新 Token，旧 Token 会立即失效。

使用 Python 客户端时，把 Token 传给 Client(token=...)。
直接发 HTTP 请求时，把 Token 放进 Authorization: Bearer <API_TOKEN> 请求头。
Token 是访问自测和提交接口的鉴权凭证，不要写入代码仓库或公开明文。
自测与正式提交都沿用同一套因子定义规则，单个自测任务最多包含 100 条公式。

Python API 因子自测

1. 安装客户端

python -m pip install factor-leaderboard-client --index-url https://quantfactorlab.com/packages/simple/

2. 初始化客户端并自测

from factor_leaderboard import Client

client = Client(
    base_url="https://quantfactorlab.com",
    token="你的 API Token",
)
results = client.self_test(
    intraday_expression="DayMean(Return)",
    interday_expression="DailyMean(Feature, 5)",
)

self_test 参数

字段	必填	说明
`formulas`	是	公式对象数组，长度 1～100。
`intraday_expression`	否	第一步每日特征表达式；纯日频可留空。
`interday_expression`	是	最终日频表达式。
`operator_source`	否	自定义 Python 算子源码字符串。
`operator_kind`	条件必填	填写自定义源码时必须指定：intraday_transform、intraday_aggregate、daily_timeseries 或 cross_section。
`from_value_test`	否	可选来源值测试任务 ID（值测试 → 正式提交转化追踪）；必须是当前账户已完成的值测试记录，详见下方「值测试 API」。

提交 API

正式提交与网页提交流程共享同一套检查与配额。

Python API 单因子提交

submission = client.submit(
    intraday_expression="DayMean(Return)",
    interday_expression="DailyMean(Feature, 5)",
)

submit 参数

字段	说明
`intraday_expression`	第一步表达式
`interday_expression`	最终日频表达式
`operator_source`	自定义源码（可选）
`operator_kind`	填写自定义源码时必填

结果查询

状态码 queued / running：计算中；completed：返回结果；failed：返回错误。

指标包括 full_market_vs_csi500 与 within_csi500。比例字段均以小数返回，例如 0.126 表示 12.6%；缺失指标返回 null。

指标	含义
`rank_ic`	两年日度 RankIC 均值。
`rank_ic_ir`	RankIC 均值与波动的比率。
`ic_positive_ratio`	RankIC 为正的有效交易日比例。
`annual_return`	多头组合相对中证500的年化超额收益。
`sharpe`	超额收益的年化 Sharpe。
`max_drawdown`	超额收益曲线最大回撤。
`long_mean_annual_return`	多头组合相对因子有效股票池等权平均收益的年化收益。
`long_mean_sharpe`	多头组合相对等权平均收益的年化 Sharpe。
`turnover`	官方口径的平均日换手率。
`valid_days`	有效 RankIC 交易日数量。
`median_stock_coverage`	每日有效股票数量的中位数。

Python API 因子值测试

不想提交公式时，可以直接把算好的日频因子值提交上来。支持两种模式：样本内（2020–2021 快速回测 + in_sample.v1 参考分，默认，只需 2 年数据）与官方完整（2020–2025H1 完整回测 + score.v5 官方评分，分数与正式榜单同口径）。方向默认自动判定（按 2020–2021 RankIC），格式自动识别。

提交因子值（文本或文件）

from factor_leaderboard import Client

client = Client(base_url="...", token="你的 API Token")

# 单因子：CSV 文本（长表 date,stock,value 或宽表 日期×股票）
result = client.value_test(
    csv_text="date,stock,value\n20200102,000001,1.1\n20200102,600000,0.9\n",
)

# 单因子：本地文件（CSV/TSV/TXT/PARQUET/PKL），官方完整模式
result = client.value_test(file_path="./factor.parquet", mode="official")

# 批量：一次多个文件，每个文件一个因子，结果按传入顺序返回
results = client.value_test_batch(file_paths=["./f1.csv", "./f2.parquet"])

print(results[0]["scenarios"]["full_market_vs_csi500"]["display_total_score"])

value_test 参数

字段	必填	说明
`csv_text` / `file_path`	二选一	因子值文本，或本地 CSV/TSV/TXT/PARQUET/PKL 文件，单文件 ≤32MB。parquet/pkl 需为 pandas DataFrame（宽表 index 为日期，或长表 date,stock,value）；PKL 请使用可信来源文件。
`mode`	否	in_sample（默认，2020–2021 快速回测 + 参考分）或 official（2020–2025H1 + score.v5）。
`factor_name`	否	留空自动生成随机因子名（与自测/正式提交一致）。
`direction`	否	默认自动判定（按 2020–2021 RankIC）；如需强制方向可传 1（值越大越看多）或 -1（仅官方模式生效）。
`source_format`	否	默认 auto 自动识别；可强制 long（date,stock,value）或 wide（日期×股票）。

HTTP 接口：POST /api/value-test（JSON csv 字段，或 multipart panel_file 文件字段）；状态查询 GET /api/value-test/<task_id>。结果包含 full_market_vs_csi500 与 within_csi500 两榜分数：official 模式为 display_total_score（score.v5），in_sample 模式为 in_sample_score（参考分，不与榜单直接比较）。

批量提交：multipart 每批最多携带 10 个 panel_file（每个文件一个因子），整批合计不超过 128MB；响应返回 {"task_ids": [...], "status": "queued", "count": N}。Python 客户端可直接用 Client.value_test_batch(file_paths=[...]) 提交并等待全部完成。每个账户同时排队不超过 10 个任务（批量按新增数量计入）。

下载原始因子值面板：服务端默认在评估完成后删除上传的因子值（临时存储）；若部署时设置 VALUE_TEST_KEEP_PANELS=1，面板（parquet）会保留，可通过 GET /api/value-test/<task_id>/panel 下载，客户端使用 Client.download_value_test_panel(task_id) 返回字节。未启用保留时该接口返回 404。结果页在保留时会显示「下载 parquet」按钮。

如何写自定义算子

在“提交因子”页面展开“自定义 Python 算子”，粘贴源码并选择对应的算子类别。不匹配会在检查阶段直接失败。

1. 按类别选择

日内变换：输入 (date, minute, stock)，输出同形状；只能读取当前和过去分钟。
日内聚合：输入 (date, minute, stock)，输出 (date, stock)；收盘后形成，可使用当日分钟数据。
日间时序：输入 (date, stock)，输出同形状；只能读取当日和过去交易日。
截面：输入 (date, minute, stock) 或 (date, stock)，输出同形状；仅沿股票轴计算。

2. 命名和参数

Python 入口函数必须是下划线命名，例如：def _moment4(x):。
同一次提交只允许定义一个自定义算子。
只允许位置参数，不允许默认参数、关键字参数、*args、**kwargs。

3. 返回与类型

输出必须是数值数组，推荐最后显式转换为 np.float32。
若是日内聚合，建议用 axis=1 或 np.nanmean/np.nansum 降掉 minute 轴。

示例：四类算子

日内变换

输入和输出都是 (date, minute, stock)。例：分钟级滞后 1 个时间点。

def _lag1(x):
    out = np.full_like(x, np.nan)
    out[:, 1:, :] = x[:, :-1, :]
    return out.astype(np.float32)

第一栏：Lag1(Return)

日内聚合

输入 (date, minute, stock)，输出 (date, stock)。例：分钟收益的四阶中心矩。

def _moment4(x):
    mean = np.nanmean(x, axis=1, keepdims=True)
    centered = x - mean
    return np.nanmean(centered ** 4, axis=1).astype(np.float32)

第一栏：Moment4(Return)；第二栏：Feature

日间时序

输入和输出都是 (date, stock)。例：每只股票沿日期计算 3 日均值，不跨股票、不看未来。

def _delay1(x):
    out = np.full_like(x, np.nan)
    out[1:, :] = x[:-1, :]
    return out.astype(np.float32)

第二栏：Delay1(Feature)

截面

输入和输出都是 (date, stock)。例：每日对股票做截面去均值，可跨股票但不跨日期。

def _demean(x):
    mean = np.nanmean(x, axis=-1, keepdims=True)
    return (x - mean).astype(np.float32)

第二栏：Demean(Feature)

4. 常见报错先查清单

维度不对：输出 shape 和所选类别不一致。
参数个数不对：表达式和函数参数顺序不一致。
未来数据：窗口引用了未来时刻。

错误码索引与修复路径

先看清楚报错码，再按顺序改代码。大部分失败都在 preflight 阶段拦截，不会真正进入评估。

一、形状相关

INVALID_OUTPUT_SHAPE：函数返回 shape 与算子类型不匹配。
修复：按算子类型回归“输入 / 输出形状契约”重写（见下文）并确保用 np.ndarray.astype(np.float32)。
INVALID_OUTPUT_DTYPE：输出不是数值矩阵（如返回 Python list / 标量 / 字符串）。
修复：统一返回 np.ndarray，避免字符串拼接或 Python 标量。

二、函数清单与参数

MISSING_OPERATOR_KIND（等同 INVALID_MANIFEST）：自定义源码已填但没选算子类别。
修复：在提交流程里必须选择 intraday_transform / intraday_aggregate / daily_timeseries / cross_section。
INVALID_MANIFEST：算子声明不完整（函数名/参数名/类别缺失）。
修复：确保源码里有一个下划线开头函数（例如 _moment4），参数只用位置参数。
INVALID_EXPRESSION：表达式里算子名/参数不合法。
修复：检查函数名大小写与表达式参数顺序，确认公式里使用了你在源码里定义的名字。
INVALID_OUTPUT_VALUES：算子写回了原始输入数组，或输出包含 inf/NaN。
修复：返回新数组（如 out = np.full_like(...)）并最终对输出做 astype(np.float32)。

三、时序与因果性

REJECTED_FUTURE_LEAKAGE：使用未来分钟/未来交易日。
修复：日内只能用当前及过去分钟，日间只能用当前与过去日期；任何依赖未来索引（如 [i+1:]）都先移除。
INVALID_CAUSALITY：跨股票读取、跨日期读取规则冲突。
修复：按算子类型选定维度进行计算，不要在日间时序中做 axis=-1 聚合。
FAILED_SYNTAX：公式语法不支持当前算子模式。
修复：先确认你是否使用了受控表达式集合（比如 BinOp 可能不被允许）。
PREFLIGHT_FAILED：预检异常（常见于后端执行异常）。
修复：联系管理员并提交报错日志，通常前 1 行会给出最直接原因。
BATCH_FACTOR_CORRELATION_OVER_LIMIT：同批多因子相关性过高。
修复：重写函数降低相关性，或在同一批次减少相似因子。

四、形状契约（强制检查）

算子类型	期望输入	期望输出	典型写法
`intraday_transform`	`(date, minute, stock)`	`(date, minute, stock)`	逐分钟返回完整张量
`intraday_aggregate`	`(date, minute, stock)`	`(date, stock)`	`axis=1` 聚合分钟轴
`daily_timeseries`	`(date, stock)`	`(date, stock)`	沿日期滚动/滞后，不可跨 stock 维
`cross_section`	`(date, minute, stock)` 或 `(date, stock)`	`同输入`	只沿 `stock` 轴聚合或变换

五、快速排查步骤

对照算子类型核对 shape。
先把代码简化成最小版（如 nanmean）确认能过，再逐步加逻辑。
确认参数数量与表达式一致。
确认无未来索引：把所有 i+1 / shift(-1) / 类似引用暂时移除。