ページファマ・フレンチ・ファクター · 12 / 29

Fama-French ファクター

QuantCraft は、バックテストまたはフォワード実行中に、OHLCV の価格バーと並べて、グローバルな Fama-French ファクターリターンのデータセットを読み込めます。これらは月次のファクターリターン（FF3 と FF5）で、ティッカーごとではなく実行ごとに 1 回取得されます。ティッカーごとの財務諸表は別の機能です。ファンダメンタルデータを参照してください。

このページで扱う内容：

Fama-French データが、ファンダメンタルデータや Trade チャートの Factor Exposure UI とどう違うか
要件と、実行ダイアログでこの機能を有効にする方法
ストラテジーコードでファクター行を読み取る方法

Fama-French とファンダメンタルデータ

	ファンダメンタルデータ	Fama-French ファクター
データ	ティッカーごとのファイル（貸借対照表、決算など）	1 つのグローバルな月次ファクターデータセット
アルゴからのアクセス	コールバック引数 `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 回帰をクライアント側で実行します。その UI はアルゴの対象外です。ストラテジーが受け取るのは、月次ファクターリターンの生の行（ff3_monthly、ff5_monthly）のみです。

要件

Premium の QuantCraft サブスクリプション、またはその例外が有効な場合は無料データアクセス（ファンダメンタルデータと同じゲート）。
サインイン済み — チェックボックスが有効なとき、有効な QuantCraft セッショントークンが送信されます。
UI：データゲートが許可する場合、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 を使わないでください。ファクターデータは今日時点で一度だけ読み込まれ、シミュレート中のバーに合わせて絞り込まれません。latest_row("ff3_monthly") は常にデータセット全体で最新の月を返すため、2015 年のバーでは現在の月になり、先読みバイアスとなります。（上記のように）バー自身の日付から月を選ぶか、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")`	特定の 1 か月。なければ `None`
`qc.rows_chronological("ff5_monthly")`	古い順のリスト。各項目に `yyyymm` を含む。未知のキーの場合は空リスト。
`qc.latest_row("ff3_monthly")`	データセット全体で最新の月を `{ yyyymm, Mkt-RF, SMB, HML, RF, … }` として返す。なければ `None`。バーを考慮しません — フォワード実行専用です（上記の警告を参照）。
`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 3 ファクターの月次リターン
`ff5_monthly`	Fama-French 5 ファクターの月次リターン

典型的な 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 — すべての過去のバーで、今日時点の最新の月を返します（先読み）。バーの日付から月を選んでください。

失敗時の動作

チェックボックスがオンなのに取得に失敗した場合、実行は継続し、factors load failed: …（バックテスト / Debug Test）、forward factors load failed: …、bulk factors load failed: … のいずれかのメッセージを出力して、fama_french.qc = None のままにします。出力パネルを確認してください。使用前には必ずガードしてください。