PagesFacteurs de Fama-French · 12 / 29

Facteurs Fama-French

QuantCraft peut charger des jeux de données globaux de rendements de facteurs Fama-French en plus des barres de prix OHLCV pendant un backtest ou une exécution forward. Ce sont des rendements de facteurs mensuels (FF3 et FF5), récupérés une seule fois par exécution — pas par ticker. Les états financiers par ticker sont une fonctionnalité distincte ; voir Données fondamentales.

Cette page couvre :

En quoi les données Fama-French diffèrent des données fondamentales et de l'interface Factor Exposure du graphique Trade
Les prérequis et comment activer la fonctionnalité dans les fenêtres d'exécution
Comment lire les lignes de facteurs dans le code de votre stratégie

Fama-French et données fondamentales

	Données fondamentales	Facteurs Fama-French
Données	Fichiers par ticker (bilan, résultats, …)	Un jeu de facteurs mensuels global unique
Accès depuis l'algo	Argument de callback `fundamentals` (`fundamentals.current(...)`)	Singleton de module `fama_french.qc`
Argument nommé de callback	Oui — `on_bar(..., fundamentals=...)`	Non — lisez `fama_french.qc` dans n'importe quel callback

Les symboles OHLCV, les lots de données fondamentales et les facteurs Fama-French sont indépendants — vous pouvez activer n'importe quelle combinaison dans la fenêtre d'exécution.

Pas l'onglet Factor Exposure du graphique Trade

L'onglet Fundamentals → Factor Exposure du graphique Trade exécute une régression FF3/FF5 côté client sur l'OHLC du graphique. Cette interface est hors du périmètre des algos. Les stratégies reçoivent uniquement des lignes brutes de rendements de facteurs mensuels (ff3_monthly, ff5_monthly).

Prérequis

Un abonnement Premium QuantCraft, ou l'accès aux données gratuites lorsque cette dérogation est activée (même condition que pour les données fondamentales).
Être connecté — un jeton de session QuantCraft valide est envoyé lorsque la case est cochée.
Interface : Include Fama-French factors (global) est activé par défaut lorsque la condition d'accès aux données le permet — dans Run backtest (Symbol & data), les exécutions forward en masse et le Chart forward test. Décochez pour omettre les données de facteurs pour cette exécution.

Configurez depuis Test (Exécution du code) pour les backtests, ou depuis Algo Trading Parameters pour les exécutions forward sur graphique.

Démarrage rapide

Une fois que le moteur a chargé les données de facteurs, lisez le singleton dans un callback :

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 : n'utilisez pas latest_row dans les callbacks. Les données de facteurs sont chargées une seule fois, à la date du jour, et ne sont pas filtrées selon la barre simulée. latest_row("ff3_monthly") renvoie toujours le mois le plus récent de tout le jeu de données — sur une barre de 2015, c'est un mois actuel, ce qui constitue un biais d'anticipation. Choisissez le mois à partir de la date de la barre (comme ci-dessus) ou avec qc.row("ff3_monthly", "YYYYMM"). latest_row convient dans une exécution forward, où « le plus récent » correspond réellement au présent.

Schéma recommandé : from quantcraft import fama_french, puis lisez fama_french.qc dans les callbacks (on_init, on_bar, on_tick, …). N'utilisez pas from quantcraft.fama_french import qc au niveau supérieur du module — cela capture None à l'import, avant que le moteur ne charge les données.

Alternatives : la variable globale de script qc_fama_french (injectée dans votre fichier d'algo racine), ou import quantcraft.process.runtime as rt puis rt.qc_fama_french dans les callbacks — c'est le même objet une fois défini ; préférez fama_french.qc dans le nouveau code.

L'ancien chemin from ide.factors_module import … fonctionne toujours pour les stratégies existantes ; écrivez le nouveau code avec quantcraft.fama_french. quantcraft.fama_french est un alias de module, donc fama_french.qc lit la valeur courante de la session — voir Poignées de module et noms importés.

Lire les lignes de facteurs

Les données mensuelles se trouvent dans des jeux indexés par des chaînes YYYYMM (p. ex. "192607"), et non par des indices de liste.

Méthode	Rôle
`qc.row("ff3_monthly", "202604")`	Un mois précis, ou `None`
`qc.rows_chronological("ff5_monthly")`	Liste du plus ancien au plus récent ; chaque élément inclut `yyyymm`. Liste vide pour une clé inconnue.
`qc.latest_row("ff3_monthly")`	Le mois le plus récent de tout le jeu de données sous la forme `{ yyyymm, Mkt-RF, SMB, HML, RF, … }`, ou `None`. Ne tient pas compte de la barre — exécutions forward uniquement (voir l'avertissement ci-dessus).
`qc.dataset(key)`	Dict brut du jeu pour cette clé (`columns`, `rows`, …), ou `None` lorsque la clé est absente
`qc.raw` / `qc.datasets` / `qc.updated_at`	Charge utile complète, `raw["datasets"]`, et l'heure de mise à jour UTC analysée (ou `None`)

Surface d'import complète (quantcraft.fama_french) : QcFamaFrench(token, *, base_url=None) — construit et récupère immédiatement (vous ne le construisez normalement jamais ; l'exécution s'en charge) ; load_qc_fama_french_from_config(cfg) ; et les assistants simples factor_rows_chronological(dataset) / latest_factor_row(dataset), qui fonctionnent sur un dict de jeu brut.

Identifiants de jeux de données :

Clé	Contenu
`ff3_monthly`	Rendements mensuels à 3 facteurs de Fama-French
`ff5_monthly`	Rendements mensuels à 5 facteurs de Fama-French

Clés FF3 typiques : Mkt-RF, SMB, HML, RF. FF5 ajoute RMW, CMA. Les valeurs sont des chaînes décimales (pourcentage ÷ 100) — utilisez float(...) pour les calculs.

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

Activation dans l'IDE

Run backtest

Dans Test → Run backtest → Symbol & data, cochez Include Fama-French factors (global) (activé par défaut lorsque la condition d'accès aux données le permet). Nécessite d'être connecté. Le moteur charge les données avant l'exécution de votre on_init().

Il n'y a aucun argument de callback factors= sur on_tick / on_bar. Importez quantcraft.fama_french et utilisez fama_french.qc.

Chart forward test

Dans Trade → Algo Trading Parameters, utilisez la même case Include Fama-French factors (global) (activée par défaut pour Premium).

Forward en masse / QuantCloud

Dans la fenêtre New Run du forward en masse (AutoTrading ou QuantCloud), utilisez Include Fama-French factors (global) dans l'onglet Schedule & data (activé par défaut). Voir QuantCloud et Préréglages d'exécution (.qcs).

Préréglages d'exécution (.qcs)

Les réglages d'exécution enregistrés peuvent inclure :

{ "includeFactors": true }

Charger un préréglage avec includeFactors: true exige Premium ; le niveau gratuit efface l'indicateur au chargement. Voir Préréglages d'exécution (.qcs).

Erreurs courantes

rows[0] / rows[-1] — invalide. dataset["rows"] est un dict indexé par "YYYYMM", pas une liste. Utilisez row ou rows_chronological (ou latest_row dans les exécutions forward).
from quantcraft.fama_french import qc en haut du fichier — capture None avant que le moteur ne charge les données.
S'attendre à un callback factors= — utilisez plutôt fama_french.qc dans on_init / on_bar / on_tick.
latest_row dans un backtest — renvoie le mois le plus récent d'aujourd'hui à chaque barre historique (anticipation). Sélectionnez le mois d'après la date de la barre.

Comportement en cas d'échec

Si la case est cochée mais que la récupération échoue, l'exécution continue, affiche un message — factors load failed: … (backtest / Debug Test), forward factors load failed: … ou bulk factors load failed: … — et laisse fama_french.qc = None. Consultez le Panneau de sortie. Protégez toujours l'accès avant utilisation.

Sujets connexes

Cycle de vie de la stratégie — ordre des callbacks ; variable globale du runtime qc_fama_french
Données fondamentales — états financiers par ticker (fonctionnalité distincte)
Données OHLCV et de barres — barres de prix ; les rendements de facteurs sont globaux, pas sur bar
Backtests — options de la fenêtre Run backtest
Référence — chemins d'import et index des sujets

7 min de lectureSuggérer une modification ↗