聚宽因子分析 API（Factor 与 calc_factors）

一句话

自定义因子 = 继承 Factor 的类：声明 name（唯一）、max_window（日级数据窗口）、dependencies（依赖的基础因子），实现 calc(self, data) 返回因子值。calc_factors(股票列表, [因子对象…], start_data, end_data) 返回 {因子name: DataFrame}。这是从「策略内手算指标」走向「可研究的因子库」的接口。

当前理解

• 因子类的三件套（见一句话）；data 在 calc 里是 dict：key = dependencies 里的因子名，value = pandas.DataFrame。
• 可依赖的基础因子族（dependencies 合法输入）：
  • 价量：open/close/high/low/volume/money。
  • 单季财务：fundamentals 全部指标（当日能看到的最新报告期）。
  • 前 N 季度财务：字段名加 _1…_7 后缀；如 operating_revenue_1 = 上一报告期；N 最大 7。
  • 行业因子（证监会 / 聚宽一二级 / 申万一二三级）、概念因子、指数因子：bool（属于=1，否则=0）。
  • 资金流因子：get_money_flow 可取的数据。
• TTM 构造：dependencies 列 operating_revenue 与 _1/_2/_3，calc 里四期相加 → 滚动四季营收，平滑单季波动（示例 OR_TT）。
• 示例因子值公式：
  • MA5 = 最近 5 日收盘均值。
  • ALPHA013 = (√(high×low) − vwap) 的均值，其中 vwap = money/volume（量价类）。
  • GROSSPROFITABILITY = (营业总收入 − 营业总成本)/总资产 的均值（毛利资产比）。
• 批量计算：calc_factors(securities, factors, start_data, end_data)——securities 股票列表、factors 因子对象列表、起止日期；返回 dict，key = 因子 name，value = DataFrame；factors['因子name'].head() 预览。
• 和策略的关系：策略在 handle_data 里手算指标后下单；因子 API 把指标对象化，为「按因子排序选股」（承接市值轮动「排序取前 N」）和后续「因子有效性研究」供数据。

来源

• 因子分析 — 全部内容
• raw 路径：原始出处（已归档）
• 关联：聚宽行情与财务数据获取 API（价量/财务字段）、简单市值轮动策略（排序取前 N 的选股模式）

常见混淆

• name vs 类名：结果 dict 的 key 用 name（如 'alpha013_name'），不是类名 ALPHA013；实例化用 ALPHA013()。
• max_window vs dependencies：max_window 决定喂多长的价格历史（MA5 要 5）；财务 _N 后缀决定取几个报告期，两者不是一回事（TTM 因子 max_window=1 但依赖 4 个财务字段）。
• 因子 ≠ 交易信号：因子只是数值；要不要买、怎么买是策略层的事。
• 财务因子的口径风险：依赖的利润表/资产负债表字段（营业总收入、总资产等）是财报口径的数字——权责发生制下「单季 vs TTM」「可持续 vs 一次性」等质量问题的分析见 利润表（读懂一段时间赚了多少钱）。
• 单季 vs TTM：直接依赖 operating_revenue 是单季口径，容易受季节波动干扰；加 _1/_2/_3 求和才是 TTM。

开放问题

• [需要验证] calc_factors 官方参数名（raw 写作 start_data/end_data，官方可能为 start_date/end_date）与返回值结构。
• [需要验证] 财务指标字段全集与报告期对齐规则（季报延迟披露时「当日能看到」的口径）。
• 因子有效性检验方法（IC、分层回测等）不在本页，见量化课堂「因子研究」系列。