PáginasFatores de Fama-French · 12 / 29

Fatores Fama-French

O QuantCraft pode carregar conjuntos de dados globais de retornos de fatores Fama-French junto com as barras de preço OHLCV durante um backtest ou uma execução forward. São retornos de fatores mensais (FF3 e FF5), buscados uma vez por execução — não por ticker. As demonstrações financeiras por ticker são um recurso separado; veja Dados fundamentalistas.

Esta página cobre:

Como os dados Fama-French diferem dos dados fundamentalistas e da interface Factor Exposure do gráfico Trade
Requisitos e como ativar o recurso nas caixas de execução
Como ler as linhas de fatores no código da sua estratégia

Fama-French vs dados fundamentalistas

	Dados fundamentalistas	Fatores Fama-French
Dados	Arquivos por ticker (balanço, resultados, …)	Um conjunto global de fatores mensais
Acesso pelo algoritmo	Argumento de callback `fundamentals` (`fundamentals.current(...)`)	Singleton de módulo `fama_french.qc`
Argumento nomeado do callback	Sim — `on_bar(..., fundamentals=...)`	Não — leia `fama_french.qc` dentro de qualquer callback

Os símbolos OHLCV, os pacotes de dados fundamentalistas e os fatores Fama-French são independentes — você pode ativar qualquer combinação na caixa de execução.

Não é a aba Factor Exposure do gráfico Trade

A aba Fundamentals → Factor Exposure do gráfico Trade executa uma regressão FF3/FF5 no cliente sobre o OHLC do gráfico. Essa interface está fora do escopo dos algoritmos. As estratégias recebem somente linhas brutas de retornos de fatores mensais (ff3_monthly, ff5_monthly).

Requisitos

Assinatura Premium do QuantCraft, ou acesso a dados gratuitos quando essa exceção está ativada (a mesma condição dos dados fundamentalistas).
Estar conectado — um token de sessão válido do QuantCraft é enviado quando a caixa está marcada.
Interface: Include Fama-French factors (global) vem ativada por padrão quando a condição de dados permite — em Run backtest (Symbol & data), nas execuções forward em massa e no Chart forward test. Desmarque para omitir os dados de fatores naquela execução.

Configure pelo Test (Executando código) nos backtests, ou por Algo Trading Parameters nas execuções forward no gráfico.

Início rápido

Depois que o mecanismo carregar os dados de fatores, leia o singleton dentro de um 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ão use latest_row dentro dos callbacks. Os dados de fatores são carregados uma única vez, na data de hoje, e não são filtrados pela barra que está sendo simulada. latest_row("ff3_monthly") sempre retorna o mês mais recente de todo o conjunto de dados — em uma barra de 2015 isso é um mês atual, o que é viés de antecipação. Escolha o mês a partir da data da própria barra (como acima) ou com qc.row("ff3_monthly", "YYYYMM"). latest_row serve em uma execução forward, onde "o mais recente" é de fato o presente.

Padrão preferido: from quantcraft import fama_french e depois leia fama_french.qc dentro dos callbacks (on_init, on_bar, on_tick, …). Não use from quantcraft.fama_french import qc no nível superior do módulo — isso captura None na importação, antes de o mecanismo carregar os dados.

Alternativas: a global de script qc_fama_french (injetada no seu arquivo raiz do algoritmo), ou import quantcraft.process.runtime as rt e depois rt.qc_fama_french nos callbacks — todos são o mesmo objeto quando definido; prefira fama_french.qc em código novo.

O caminho antigo from ide.factors_module import … ainda funciona para estratégias existentes; escreva o código novo com quantcraft.fama_french. quantcraft.fama_french é um alias de módulo, então fama_french.qc lê o valor vivo da sessão — veja Identificadores de módulo vs nomes importados.

Lendo as linhas de fatores

Os dados mensais ficam em conjuntos indexados por strings YYYYMM (por exemplo "192607"), não por índices de lista.

Método	Finalidade
`qc.row("ff3_monthly", "202604")`	Um mês específico, ou `None`
`qc.rows_chronological("ff5_monthly")`	Lista da mais antiga para a mais nova; cada item inclui `yyyymm`. Lista vazia para uma chave desconhecida.
`qc.latest_row("ff3_monthly")`	O mês mais recente de todo o conjunto de dados como `{ yyyymm, Mkt-RF, SMB, HML, RF, … }`, ou `None`. Não considera a barra — somente execuções forward (veja o aviso acima).
`qc.dataset(key)`	Dict bruto do conjunto para aquela chave (`columns`, `rows`, …), ou `None` quando a chave não existe
`qc.raw` / `qc.datasets` / `qc.updated_at`	Carga completa, `raw["datasets"]` e o horário de atualização UTC analisado (ou `None`)

Superfície de importação completa (quantcraft.fama_french): QcFamaFrench(token, *, base_url=None) — constrói e busca imediatamente (normalmente você nunca o constrói; a execução faz isso); load_qc_fama_french_from_config(cfg); e os auxiliares simples factor_rows_chronological(dataset) / latest_factor_row(dataset), que funcionam sobre um dict de conjunto bruto.

Ids dos conjuntos de dados:

Chave	Conteúdo
`ff3_monthly`	Retornos mensais de 3 fatores de Fama-French
`ff5_monthly`	Retornos mensais de 5 fatores de Fama-French

Chaves FF3 típicas: Mkt-RF, SMB, HML, RF. O FF5 acrescenta RMW, CMA. Os valores são strings decimais (porcentagem ÷ 100) — use float(...) para a aritmética.

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

Ativando no IDE

Run backtest

Em Test → Run backtest → Symbol & data, marque Include Fama-French factors (global) (ativada por padrão quando a condição de dados permite). Exige login. O mecanismo carrega os dados antes de o seu on_init() rodar.

Não há argumento de callback factors= em on_tick / on_bar. Importe quantcraft.fama_french e use fama_french.qc.

Chart forward test

Em Trade → Algo Trading Parameters, use a mesma caixa Include Fama-French factors (global) (ativada por padrão no Premium).

Forward em massa / QuantCloud

Na caixa New Run do forward em massa (AutoTrading ou QuantCloud), use Include Fama-French factors (global) na aba Schedule & data (ativada por padrão). Veja QuantCloud e Predefinições de execução (.qcs).

Predefinições de execução (.qcs)

As configurações de execução salvas podem incluir:

{ "includeFactors": true }

Carregar uma predefinição com includeFactors: true exige Premium; o nível gratuito limpa o indicador ao carregar. Veja Predefinições de execução (.qcs).

Erros comuns

rows[0] / rows[-1] — inválido. dataset["rows"] é um dict indexado por "YYYYMM", não uma lista. Use row ou rows_chronological (ou latest_row em execuções forward).
from quantcraft.fama_french import qc no topo do arquivo — captura None antes de o mecanismo carregar os dados.
Esperar um callback factors= — use fama_french.qc dentro de on_init / on_bar / on_tick.
latest_row em um backtest — retorna o mês mais recente de hoje em toda barra histórica (antecipação). Selecione o mês a partir da data da barra.

Comportamento em caso de falha

Se a caixa estiver marcada mas a busca falhar, a execução continua, imprime uma mensagem — factors load failed: … (backtest / Debug Test), forward factors load failed: … ou bulk factors load failed: … — e deixa fama_french.qc = None. Confira o Painel de saída. Sempre proteja o acesso antes de usar.

Tópicos relacionados

Ciclo de vida da estratégia — ordem dos callbacks; global do runtime qc_fama_french
Dados fundamentalistas — demonstrações financeiras por ticker (recurso separado)
Dados OHLCV e de barras — barras de preço; os retornos de fatores são globais, não estão em bar
Backtests — opções da caixa Run backtest
Referência — caminhos de importação e índice de tópicos

7 min de leituraSugerir uma edição ↗