页面Fama-French 因子 · 12 / 29

Fama-French 因子

QuantCraft 可以在回测或前向运行期间，在 OHLCV 价格 K 线之外加载全球的 Fama-French 因子收益数据集。它们是月度因子收益（FF3 和 FF5），每次运行只获取一次——不是按代码获取。按代码的财务报表是另一项功能；参见基本面数据。

本页涵盖：

Fama-French 数据与基本面数据、以及与 Trade 图表 Factor Exposure 界面的区别
要求，以及如何在运行对话框中启用该功能
如何在策略代码中读取因子行

Fama-French 与基本面数据

	基本面数据	Fama-French 因子
数据	按代码的文件（资产负债表、财报等）	一个全球月度因子数据集
算法访问方式	`fundamentals` 回调参数（`fundamentals.current(...)`）	`fama_french.qc` 模块单例
回调关键字参数	有——`on_bar(..., fundamentals=...)`	没有——在任何回调中读取 `fama_french.qc`

OHLCV 标的、基本面数据包和 Fama-French 因子是相互独立的——你可以在运行对话框中启用任意组合。

不是 Trade 图表的 Factor Exposure 标签页

Trade 图表的 Fundamentals → Factor Exposure 标签页会针对图表 OHLC 在客户端运行 FF3/FF5 回归。该界面不在算法的范围内。策略只会收到原始的月度因子收益行（ff3_monthly、ff5_monthly）。

要求

Premium QuantCraft 订阅，或在启用该例外时使用免费数据访问（与基本面数据相同的门槛）。
已登录——启用复选框时会发送有效的 QuantCraft 会话令牌。
**界面：**当数据门槛允许时，Include Fama-French factors (global) 默认开启——在 Run backtest（Symbol & data）、批量前向和 Chart forward test 中。取消勾选可在该次运行中省略因子数据。

回测请在 Test（运行代码）中配置，图表前向运行则在 Algo Trading Parameters 中配置。

快速开始

引擎加载因子数据之后，在回调内部读取单例：

from quantcraft import fama_french

_ff3 = None  # oldest-first rows, built once

def factor_row_before(bar_t):
    """Latest FF3 month that ended before this bar's month (no look-ahead)."""
    global _ff3
    if _ff3 is None:
        _ff3 = fama_french.qc.rows_chronological("ff3_monthly")
    t = str(bar_t)
    bar_yyyymm = t[:4] + t[5:7]          # works for "2024-01-02" and ISO timestamps
    rows = [r for r in _ff3 if r["yyyymm"] < bar_yyyymm]
    return rows[-1] if rows else None

def on_bar(bar_index, bar, fundamentals=None, symbol=None):
    if fama_french.qc is None:
        return  # checkbox off or load failed
    row = factor_row_before(bar["t"])
    if row:
        mkt_rf = float(row.get("Mkt-RF", 0))
        smb = float(row.get("SMB", 0))
        hml = float(row.get("HML", 0))

回测：不要在回调中使用 latest_row。因子数据是截至今天一次性加载的，不会按正在模拟的 K 线进行过滤。latest_row("ff3_monthly") 始终返回整个数据集中最新的月份——在 2015 年的 K 线上，那是当前的月份，属于前视偏差。请根据 K 线自身的日期选择月份（如上所示），或使用 qc.row("ff3_monthly", "YYYYMM")。latest_row 在前向运行中没有问题，因为那里的“最新”确实就是当下。

推荐模式：from quantcraft import fama_french，然后在回调内部（on_init、on_bar、on_tick 等）读取 fama_french.qc。不要在模块顶层使用 from quantcraft.fama_french import qc——那样会在引擎加载数据之前、导入时就捕获到 None。

**替代方式：**脚本全局变量 qc_fama_french（注入到你的根算法文件中），或 import quantcraft.process.runtime as rt 然后在回调中使用 rt.qc_fama_french——设置之后它们都是同一个对象；新代码请优先使用 fama_french.qc。

较旧的 from ide.factors_module import … 路径对现有策略仍然可用；编写新代码时请使用 quantcraft.fama_french。quantcraft.fama_french 是一个模块别名，因此 fama_french.qc 读取的是实时的会话值——参见模块句柄与导入名称。

读取因子行

月度数据保存在以 YYYYMM 字符串（例如 "192607"）为键的数据集中，而不是列表索引。

方法	用途
`qc.row("ff3_monthly", "202604")`	某个特定月份，或 `None`
`qc.rows_chronological("ff5_monthly")`	从旧到新的列表；每一项包含 `yyyymm`。未知的键返回空列表。
`qc.latest_row("ff3_monthly")`	整个数据集中最近的月份，形式为 `{ yyyymm, Mkt-RF, SMB, HML, RF, … }`，或 `None`。不感知 K 线——仅用于前向运行（参见上面的警告）。
`qc.dataset(key)`	该键的原始数据集 dict（`columns`、`rows` 等），键不存在时为 `None`
`qc.raw` / `qc.datasets` / `qc.updated_at`	完整载荷、`raw["datasets"]`，以及解析后的 UTC 更新时间（或 `None`）

完整的导入接口（quantcraft.fama_french）：QcFamaFrench(token, *, base_url=None)——构造后立即获取（你通常不需要自己构造；运行会这样做）；load_qc_fama_french_from_config(cfg)；以及作用于原始数据集 dict 的简单辅助函数 factor_rows_chronological(dataset) / latest_factor_row(dataset)。

数据集 id：

键	内容
`ff3_monthly`	Fama-French 三因子月度收益
`ff5_monthly`	Fama-French 五因子月度收益

典型的 FF3 键：Mkt-RF、SMB、HML、RF。FF5 另外增加 RMW、CMA。值是十进制字符串（百分比 ÷ 100）——运算时请使用 float(...)。

# Helpers (recommended)
history = fama_french.qc.rows_chronological("ff5_monthly")   # oldest-first
jan_2024 = fama_french.qc.row("ff5_monthly", "202401")

# Raw dict access (keys are YYYYMM strings — not rows[0] / rows[-1])
ff3_rows = fama_french.qc.datasets["ff3_monthly"]["rows"]
july_1926 = ff3_rows["192607"]

在 IDE 中启用

Run backtest

在 Test → Run backtest → Symbol & data 中，勾选 Include Fama-French factors (global)（数据门槛允许时默认开启）。需要登录。引擎会在你的 on_init() 运行之前加载数据。

on_tick / on_bar 没有 factors= 回调参数。请导入 quantcraft.fama_french 并使用 fama_french.qc。

Chart forward test

在 Trade → Algo Trading Parameters 中，使用相同的 Include Fama-French factors (global) 复选框（Premium 默认开启）。

批量前向 / QuantCloud

在批量前向的 New Run 对话框（AutoTrading 或 QuantCloud）中，使用 Schedule & data 标签页上的 Include Fama-French factors (global)（默认开启）。参见 QuantCloud 和运行预设（.qcs）。

运行预设（.qcs）

保存的运行设置可以包含：

{ "includeFactors": true }

加载带有 includeFactors: true 的预设需要 Premium；免费版会在加载时清除该标志。参见运行预设（.qcs）。

常见错误

rows[0] / rows[-1]——无效。dataset["rows"] 是以 "YYYYMM" 为键的 dict，不是列表。请使用 row 或 rows_chronological（前向运行中也可用 latest_row）。
文件顶部的 from quantcraft.fama_french import qc——会在引擎加载数据之前捕获到 None。
期待 factors= 回调——请改为在 on_init / on_bar / on_tick 内使用 fama_french.qc。
回测中的 latest_row——在每一根历史 K 线上都返回今天最新的月份（前视）。请根据 K 线的日期选择月份。

失败时的行为

如果复选框已开启但获取失败，运行会继续，并打印一条消息——factors load failed: …（回测 / Debug Test）、forward factors load failed: … 或 bulk factors load failed: …——同时让 fama_french.qc = None。请查看输出面板。使用前务必先做判空保护。