PáginasFactores de Fama-French · 12 / 29

Factores Fama-French

QuantCraft puede cargar conjuntos de datos globales de rendimientos de factores Fama-French junto con las barras de precio OHLCV durante un backtest o una ejecución forward. Son rendimientos de factores mensuales (FF3 y FF5), obtenidos una vez por ejecución, no por ticker. Los estados financieros por ticker son una función distinta; consulta Datos fundamentales.

Esta página cubre:

En qué se diferencian los datos Fama-French de los datos fundamentales y de la interfaz Factor Exposure del gráfico Trade
Requisitos y cómo activar la función en los cuadros de ejecución
Cómo leer las filas de factores en el código de tu estrategia

Fama-French frente a datos fundamentales

	Datos fundamentales	Factores Fama-French
Datos	Archivos por ticker (balance, resultados, …)	Un conjunto global de factores mensuales
Acceso desde el algoritmo	Argumento de callback `fundamentals` (`fundamentals.current(...)`)	Singleton de módulo `fama_french.qc`
Argumento con nombre del callback	Sí — `on_bar(..., fundamentals=...)`	No — lee `fama_french.qc` dentro de cualquier callback

Los símbolos OHLCV, los paquetes de datos fundamentales y los factores Fama-French son independientes: puedes activar cualquier combinación en el cuadro de ejecución.

No es la pestaña Factor Exposure del gráfico Trade

La pestaña Fundamentals → Factor Exposure del gráfico Trade ejecuta una regresión FF3/FF5 en el cliente sobre el OHLC del gráfico. Esa interfaz está fuera del alcance de los algoritmos. Las estrategias reciben únicamente filas brutas de rendimientos de factores mensuales (ff3_monthly, ff5_monthly).

Requisitos

Suscripción Premium de QuantCraft, o acceso a datos gratuitos cuando esa excepción está activada (la misma condición que para los datos fundamentales).
Sesión iniciada: se envía un token de sesión de QuantCraft válido cuando la casilla está marcada.
Interfaz: Include Fama-French factors (global) está activada por defecto cuando la condición de datos lo permite, en Run backtest (Symbol & data), en las ejecuciones forward masivas y en Chart forward test. Desmárcala para omitir los datos de factores en esa ejecución.

Configúralo desde Test (Ejecutar código) para backtests, o desde Algo Trading Parameters en las ejecuciones forward sobre el gráfico.

Inicio rápido

Una vez que el motor ha cargado los datos de factores, lee el singleton dentro de 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: no uses latest_row dentro de los callbacks. Los datos de factores se cargan una sola vez, a fecha de hoy, y no se filtran según la barra que se está simulando. latest_row("ff3_monthly") siempre devuelve el mes más reciente de todo el conjunto de datos; en una barra de 2015 eso es un mes actual, lo que supone sesgo de anticipación. Elige el mes a partir de la fecha de la propia barra (como arriba) o con qc.row("ff3_monthly", "YYYYMM"). latest_row está bien en una ejecución forward, donde "el más reciente" es de verdad el presente.

Patrón preferido: from quantcraft import fama_french y luego lee fama_french.qc dentro de los callbacks (on_init, on_bar, on_tick, …). No uses from quantcraft.fama_french import qc a nivel superior del módulo: captura None en el momento de la importación, antes de que el motor cargue los datos.

Alternativas: la variable global de script qc_fama_french (inyectada en tu archivo raíz del algoritmo), o import quantcraft.process.runtime as rt y luego rt.qc_fama_french en los callbacks; todos son el mismo objeto cuando está definido; en código nuevo prefiere fama_french.qc.

La ruta antigua from ide.factors_module import … sigue resolviéndose para estrategias existentes; escribe el código nuevo con quantcraft.fama_french. quantcraft.fama_french es un alias de módulo, así que fama_french.qc lee el valor vivo de la sesión; consulta Manejadores de módulo frente a nombres importados.

Leer las filas de factores

Los datos mensuales viven en conjuntos indexados por cadenas YYYYMM (p. ej. "192607"), no por índices de lista.

Método	Propósito
`qc.row("ff3_monthly", "202604")`	Un mes concreto, o `None`
`qc.rows_chronological("ff5_monthly")`	Lista de la más antigua a la más reciente; cada elemento incluye `yyyymm`. Lista vacía para una clave desconocida.
`qc.latest_row("ff3_monthly")`	El mes más reciente de todo el conjunto de datos como `{ yyyymm, Mkt-RF, SMB, HML, RF, … }`, o `None`. No tiene en cuenta la barra: solo para ejecuciones forward (consulta la advertencia de arriba).
`qc.dataset(key)`	Dict bruto del conjunto para esa clave (`columns`, `rows`, …), o `None` cuando falta la clave
`qc.raw` / `qc.datasets` / `qc.updated_at`	Carga completa, `raw["datasets"]` y la hora de actualización UTC analizada (o `None`)

Superficie de importación completa (quantcraft.fama_french): QcFamaFrench(token, *, base_url=None) — se construye y obtiene los datos de inmediato (normalmente nunca lo construyes; lo hace la ejecución); load_qc_fama_french_from_config(cfg); y los asistentes simples factor_rows_chronological(dataset) / latest_factor_row(dataset), que funcionan con un dict de conjunto bruto.

Ids de conjuntos de datos:

Clave	Contenido
`ff3_monthly`	Rendimientos mensuales de 3 factores de Fama-French
`ff5_monthly`	Rendimientos mensuales de 5 factores de Fama-French

Claves FF3 típicas: Mkt-RF, SMB, HML, RF. FF5 añade RMW, CMA. Los valores son cadenas decimales (porcentaje ÷ 100): usa float(...) para operar.

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

Activarlo en el IDE

Run backtest

En Test → Run backtest → Symbol & data, marca Include Fama-French factors (global) (activada por defecto cuando la condición de datos lo permite). Requiere haber iniciado sesión. El motor carga los datos antes de que se ejecute tu on_init().

No hay argumento de callback factors= en on_tick / on_bar. Importa quantcraft.fama_french y usa fama_french.qc.

Chart forward test

En Trade → Algo Trading Parameters, usa la misma casilla Include Fama-French factors (global) (activada por defecto para Premium).

Forward masivo / QuantCloud

En el cuadro New Run de forward masivo (AutoTrading o QuantCloud), usa Include Fama-French factors (global) en la pestaña Schedule & data (activada por defecto). Consulta QuantCloud y Preajustes de ejecución (.qcs).

Preajustes de ejecución (.qcs)

Los ajustes de ejecución guardados pueden incluir:

{ "includeFactors": true }

Cargar un preajuste con includeFactors: true requiere Premium; el nivel gratuito borra el indicador al cargar. Consulta Preajustes de ejecución (.qcs).

Errores comunes

rows[0] / rows[-1] — no válido. dataset["rows"] es un dict indexado por "YYYYMM", no una lista. Usa row o rows_chronological (o latest_row en ejecuciones forward).
from quantcraft.fama_french import qc al principio del archivo — captura None antes de que el motor cargue los datos.
Esperar un callback factors= — usa fama_french.qc dentro de on_init / on_bar / on_tick en su lugar.
latest_row en un backtest — devuelve el mes más reciente de hoy en cada barra histórica (anticipación). Selecciona el mes a partir de la fecha de la barra.

Comportamiento ante fallos

Si la casilla está marcada pero la obtención falla, la ejecución continúa, imprime un mensaje — factors load failed: … (backtest / Debug Test), forward factors load failed: … o bulk factors load failed: … — y deja fama_french.qc = None. Revisa el Panel de salida. Protege siempre el acceso antes de usarlo.

Temas relacionados

Ciclo de vida de la estrategia: orden de los callbacks; variable global del runtime qc_fama_french
Datos fundamentales: estados financieros por ticker (función distinta)
Datos OHLCV y de barras: barras de precio; los rendimientos de factores son globales, no están en bar
Backtests: opciones del cuadro Run backtest
Referencia: rutas de importación e índice de temas

7 min de lecturaSugerir una edición ↗