SeitenFama-French-Faktoren · 12 / 29

Fama-French-Faktoren

QuantCraft kann globale Fama-French-Faktorrenditen-Datensätze zusammen mit den OHLCV-Kursbalken während eines Backtests oder Forward-Laufs laden. Das sind monatliche Faktorrenditen (FF3 und FF5), die einmal pro Lauf abgerufen werden — nicht pro Ticker. Finanzberichte pro Ticker sind eine eigene Funktion; siehe Fundamentaldaten.

Diese Seite behandelt:

Wie sich Fama-French-Daten von Fundamentaldaten und von der Oberfläche Factor Exposure im Trade-Chart unterscheiden
Voraussetzungen und wie Sie die Funktion in den Lauf-Dialogen aktivieren
Wie Sie Faktorzeilen im Strategiecode lesen

Fama-French vs. Fundamentaldaten

	Fundamentaldaten	Fama-French-Faktoren
Daten	Dateien pro Ticker (Bilanz, Ergebnisse, …)	Ein globaler Datensatz monatlicher Faktoren
Zugriff im Algo	Callback-Argument `fundamentals` (`fundamentals.current(...)`)	Modul-Singleton `fama_french.qc`
Callback-Schlüsselwortargument	Ja — `on_bar(..., fundamentals=...)`	Nein — lesen Sie `fama_french.qc` in einem beliebigen Callback

OHLCV-Symbole, Fundamentaldaten-Pakete und Fama-French-Faktoren sind unabhängig — im Lauf-Dialog können Sie jede Kombination aktivieren.

Nicht der Tab Factor Exposure im Trade-Chart

Der Tab Fundamentals → Factor Exposure im Trade-Chart führt eine FF3/FF5-Regression clientseitig gegen das Chart-OHLC aus. Diese Oberfläche liegt außerhalb des Umfangs für Algos. Strategien erhalten nur rohe monatliche Faktorrenditen-Zeilen (ff3_monthly, ff5_monthly).

Voraussetzungen

Premium-Abonnement bei QuantCraft oder Zugang zu Gratisdaten, wenn diese Ausnahme aktiviert ist (dieselbe Bedingung wie bei Fundamentaldaten).
Angemeldet — bei aktiviertem Kontrollkästchen wird ein gültiges QuantCraft-Sitzungstoken gesendet.
Oberfläche: Include Fama-French factors (global) ist standardmäßig an, wenn die Datenfreigabe es zulässt — bei Run backtest (Symbol & data), Forward-Bulk und Chart forward test. Deaktivieren Sie es, um Faktordaten für diesen Lauf wegzulassen.

Konfigurieren Sie über Test (Code ausführen) bei Backtests oder über Algo Trading Parameters bei Chart-Forward-Läufen.

Schnellstart

Nachdem die Engine die Faktordaten geladen hat, lesen Sie den Singleton innerhalb eines Callbacks:

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))

Backtests: Verwenden Sie latest_row nicht innerhalb von Callbacks. Die Faktordaten werden einmal, Stand heute, geladen und nicht auf den simulierten Balken gefiltert. latest_row("ff3_monthly") gibt immer den neuesten Monat des gesamten Datensatzes zurück — bei einem Balken von 2015 ist das ein heutiger Monat, also Look-ahead-Bias. Wählen Sie den Monat anhand des Datums des Balkens (wie oben) oder mit qc.row("ff3_monthly", "YYYYMM"). latest_row ist in einem Forward-Lauf in Ordnung, wo „neuester“ wirklich die Gegenwart ist.

Bevorzugtes Muster: from quantcraft import fama_french, dann fama_french.qc innerhalb der Callbacks lesen (on_init, on_bar, on_tick, …). Verwenden Sie nicht from quantcraft.fama_french import qc auf Modulebene — das erfasst beim Import None, bevor die Engine die Daten lädt.

Alternativen: die Skript-Global qc_fama_french (in Ihre Algo-Stammdatei eingeschleust) oder import quantcraft.process.runtime as rt und dann rt.qc_fama_french in Callbacks — alles dasselbe Objekt, sobald es gesetzt ist; bevorzugen Sie in neuem Code fama_french.qc.

Der ältere Pfad from ide.factors_module import … löst für bestehende Strategien weiterhin auf; schreiben Sie neuen Code gegen quantcraft.fama_french. quantcraft.fama_french ist ein Modul-Alias, daher liest fama_french.qc den aktuellen Sitzungswert — siehe Modul-Handles vs. importierte Namen.

Faktorzeilen lesen

Monatsdaten liegen in Datensätzen, die über YYYYMM-Strings (z. B. "192607") indiziert sind, nicht über Listenindizes.

Methode	Zweck
`qc.row("ff3_monthly", "202604")`	Ein bestimmter Monat oder `None`
`qc.rows_chronological("ff5_monthly")`	Liste, ältester zuerst; jedes Element enthält `yyyymm`. Leere Liste bei unbekanntem Schlüssel.
`qc.latest_row("ff3_monthly")`	Der jüngste Monat im gesamten Datensatz als `{ yyyymm, Mkt-RF, SMB, HML, RF, … }` oder `None`. Nicht balkenbewusst — nur für Forward-Läufe (siehe Warnung oben).
`qc.dataset(key)`	Roh-Dict des Datensatzes für diesen Schlüssel (`columns`, `rows`, …) oder `None`, wenn der Schlüssel fehlt
`qc.raw` / `qc.datasets` / `qc.updated_at`	Vollständige Nutzlast, `raw["datasets"]` und die geparste UTC-Aktualisierungszeit (oder `None`)

Vollständige Import-Oberfläche (quantcraft.fama_french): QcFamaFrench(token, *, base_url=None) — baut sich auf und ruft sofort ab (Sie konstruieren es normalerweise nie; der Lauf tut das); load_qc_fama_french_from_config(cfg); und die einfachen Hilfsfunktionen factor_rows_chronological(dataset) / latest_factor_row(dataset), die auf einem rohen Datensatz-Dict arbeiten.

Datensatz-IDs:

Schlüssel	Inhalt
`ff3_monthly`	Fama-French-Monatsrenditen mit 3 Faktoren
`ff5_monthly`	Fama-French-Monatsrenditen mit 5 Faktoren

Typische FF3-Schlüssel: Mkt-RF, SMB, HML, RF. FF5 ergänzt RMW, CMA. Werte sind Dezimal-Strings (Prozent ÷ 100) — verwenden Sie float(...) für Arithmetik.

# 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"]

In der IDE aktivieren

Run backtest

Aktivieren Sie unter Test → Run backtest → Symbol & data die Option Include Fama-French factors (global) (standardmäßig an, wenn die Datenfreigabe es zulässt). Erfordert Anmeldung. Die Engine lädt die Daten, bevor Ihr on_init() läuft.

Es gibt kein Callback-Argument factors= bei on_tick / on_bar. Importieren Sie quantcraft.fama_french und nutzen Sie fama_french.qc.

Chart forward test

Nutzen Sie unter Trade → Algo Trading Parameters dasselbe Kontrollkästchen Include Fama-French factors (global) (bei Premium standardmäßig an).

Forward-Bulk / QuantCloud

Nutzen Sie im Dialog New Run für Forward-Bulk (AutoTrading oder QuantCloud) die Option Include Fama-French factors (global) im Tab Schedule & data (standardmäßig an). Siehe QuantCloud und Ausführungsvorlagen (.qcs).

Ausführungsvorlagen (.qcs)

Gespeicherte Lauf-Einstellungen können Folgendes enthalten:

{ "includeFactors": true }

Das Laden einer Vorlage mit includeFactors: true erfordert Premium; die kostenlose Stufe löscht das Flag beim Laden. Siehe Ausführungsvorlagen (.qcs).

Häufige Fehler

rows[0] / rows[-1] — ungültig. dataset["rows"] ist ein Dict, indiziert über "YYYYMM", keine Liste. Verwenden Sie row oder rows_chronological (oder latest_row in Forward-Läufen).
from quantcraft.fama_french import qc am Dateianfang — erfasst None, bevor die Engine die Daten lädt.
Ein Callback factors= erwarten — nutzen Sie stattdessen fama_french.qc innerhalb von on_init / on_bar / on_tick.
latest_row in einem Backtest — liefert bei jedem historischen Balken den heute neuesten Monat (Look-ahead). Wählen Sie den Monat anhand des Balkendatums.

Verhalten bei Fehlern

Ist das Kontrollkästchen an, der Abruf schlägt aber fehl, läuft der Lauf weiter, gibt eine Meldung aus — factors load failed: … (Backtest / Debug Test), forward factors load failed: … oder bulk factors load failed: … — und lässt fama_french.qc = None. Prüfen Sie den Ausgabebereich. Sichern Sie den Zugriff vor der Nutzung immer ab.