Backtests

Use o botão Test (Execução de código) no IDE do QuantCraft para abrir Run backtest. Ali você define os símbolos, os dados de preços, os dados fundamentalistas opcionais, a janela de simulação, o saldo inicial e os custos de execução e (se o seu script os usar) os parâmetros de entrada para uma execução única. O mecanismo invoca os callbacks do ciclo de vida da sua estratégia. Os resultados aparecem em Resultados dos testes; o OHLCV explica o formato das barras.

No topo do corpo da caixa, você pode usar Load ou Save para reaproveitar uma predefinição de execução (.qcs). Todo o restante é agrupado em até três abas, para que você percorra o formulário antes de iniciar o backtest.

Abas da caixa Run backtest

Relógio / símbolo principal: não há controle de símbolo principal na caixa. Com Selected symbols, o relógio de barras usa uma constante SYMBOL do seu script (se esse ticker estiver na lista carregada); caso contrário, o primeiro símbolo carregado. Com Screener, não há símbolo de relógio — o conjunto de símbolos muda ao longo da execução, então leia o histórico de cada ticker pelos próprios deslocamentos bar.close[i]. Veja Ciclo de vida da estratégia.

Temporizador / on_timer: a caixa Run backtest não define um intervalo de temporizador. O on_timer é para execuções forward / bulk / chart-forward que expõem um controle de temporizador — não para backtests do IDE.

---

Fonte de preços (feed da corretora ou B2)

Na aba Symbol & data, escolha o feed de preços:

• Feed da corretora conectada — estão disponíveis intervalos de tempo intradiários e diários (exige uma conta de corretora conectada com credenciais configuradas no aplicativo).
• QuantCraft B2 — em um plano gratuito, somente os intervalos OHLCV diário (d), semanal (w) e mensal (m) estão disponíveis; o Premium libera o intradiário e intervalos B2 estendidos. Você precisa estar conectado ao QuantCraft para que um token de sessão possa ser enviado para o OHLCV do B2 (e para os dados fundamentalistas, quando ativados).

A escolha é salva nas predefinições de execução (.qcs) como ohlcvSource ("alpaca" ou "b2").

---

Intervalo de tempo das barras e classe de ativo (somente feed da corretora)

Quando a fonte de preços é o feed da corretora conectada, você pode definir:

Quando a fonte de preços é o B2, você só escolhe o Timeframe: Daily, Weekly ou Monthly em um plano gratuito; o Premium adiciona o intradiário e intervalos B2 estendidos (veja os códigos B2 em Dados OHLCV e de barras).

---

Intervalos de tempo adicionais (opcional)

Use Additional timeframes em Symbol & data para carregar tamanhos de barra extras junto com o seu intervalo de tempo principal. No código da estratégia, leia-os com rt.get_bar(Timeframe.X, shift) — veja Dados OHLCV e de barras e Ciclo de vida da estratégia.

• Selecione em seleção múltipla qualquer intervalo extra de que a sua estratégia precise (por exemplo, diário quando a sua barra principal é de 5 minutos).
• O intervalo principal também está disponível por rt.get_bar sem precisar listá-lo em Additional timeframes.
• Retorna None se esse intervalo não tiver buffer para a execução, em uma fonte Screener ou quando os dados não estiverem disponíveis.
• Em um backtest, get_bar só vê as barras até o passo atual e sempre lê as barras do símbolo de relógio — para o histórico de outro ticker, use os deslocamentos bar.close[i] desse ticker.
• As configurações podem ser salvas nas predefinições de execução (.qcs) em secondaryTimeframes.

---

Símbolos

Fonte de símbolos

Symbol source na aba Symbol & data decide quais tickers o backtest opera:

Com Screener selecionado, você configura o próprio filtro:

Limites de um backtest guiado por screener: ele exige datas de início e fim explícitas; intervalos de tempo adicionais não são suportados; um filtro por script Python exige um Refresh interval de 7 dias ou mais; e o Debug Test não oferece suporte a uma fonte Screener (ele para com uma mensagem pedindo que você mude para Selected symbols). Com os dados fundamentalistas ativados, cada símbolo filtrado recebe os seus automaticamente. Os resultados incluem uma aba Screener Output ao lado de Logs, mostrando cada rebalanceamento como uma data recolhível com os símbolos operados naquela janela. Veja Screener para criar filtros e para os detalhes de ponto no tempo e viés de sobrevivência.

Selected symbols

Em Symbol & data, escolha um ou mais tickers para a execução:

• Com o feed da corretora conectada, a lista vem do universo de ativos da sua corretora (ações ou cripto, conforme a Asset class). Você pode pesquisar e selecionar vários.
• Com o B2, a lista vem do mesmo catálogo dos caminhos de dados fundamentalistas no servidor.

Regras:

• É necessário pelo menos um símbolo.
• Os símbolos são normalizados para maiúsculas na execução.
• Caracteres válidos: letras, dígitos, . e - (típicos de sufixos de bolsa como BRK.B ou RHM.XETRA).

O primeiro símbolo na ordem da sua seleção é o símbolo de relógio padrão, a menos que a sua estratégia defina um SYMBOL = "..." de nível superior que corresponda a um ticker carregado. A caixa não tem um controle separado de símbolo principal.

---

Dados fundamentalistas (opcional)

Em Symbol & data, marque Uses fundamentals (select if your strategy requires fundamental data) quando a sua estratégia ler o argumento fundamentals em on_bar / on_tick (backtest), ou em on_timer em uma execução forward, ou usar lógica que considere dados fundamentalistas.

A caixa de seleção é exibida quando os recursos de dados fundamentalistas estão ativados para a sua versão, mas fica desativada (com uma dica de Premium) a menos que você tenha Premium ou o acesso a dados gratuitos esteja habilitado. Quando os dados fundamentalistas estão ativados:

• Você precisa estar conectado (o token do QuantCraft é enviado para carregar os arquivos de dados fundamentalistas do B2).
• Escolha um ou mais pacotes de dados fundamentalistas na seleção múltipla (caminhos como fundamentals/AAPL.json.gz). A caixa de diálogo mostra o caminho normalizado abaixo de cada seleção.

Importante: os símbolos OHLCV e os símbolos de dados fundamentalistas são independentes. Você pode fazer o backtest de RNMBY pelo feed da corretora enquanto carrega os dados fundamentalistas de RHM.XETRA — a interface lembra que, nesse caso, você deve passar o ticker correto para fundamentals.current(..., symbol="RHM.XETRA") (ou equivalente) no código.

Quando vários pacotes de dados fundamentalistas são selecionados, o mecanismo constrói um mapa por caminho. O pacote principal de dados fundamentalistas usado nos instantâneos alinhados às barras é, por padrão, o símbolo operado (ou o primeiro pacote em ordem alfabética); em execuções com vários símbolos e Screener, sempre passe symbol= em fundamentals.current / get_data_with_offset, já que o principal pode não ser o ticker em que você está.

---

Fatores de Fama-French (opcional)

Em Symbol & data, marque Include Fama-French factors (global) quando a sua estratégia ler retornos mensais globais de fatores por meio de fama_french.qc. Veja Fatores de Fama-French para a API completa.

Quando os fatores estão ativados:

• Você precisa do Premium (ou de acesso a dados gratuitos, quando habilitado) e deve estar conectado.
• A caixa de seleção fica marcada por padrão quando a restrição de dados permite. Desmarque para ignorar os dados de fatores naquela execução.
• Os símbolos OHLCV, os pacotes de dados fundamentalistas e os fatores de Fama-French são independentes — ative a combinação de que você precisar.
• Não há argumento de callback factors= — importe quantcraft.fama_french e leia fama_french.qc dentro dos callbacks (on_init, on_bar, on_tick, …).

---

Dados de calendário e eventos corporativos (opcional)

Em Symbol & data, Include calendar data adiciona ao seu backtest o histórico de dividendos, o histórico de desdobramentos, as datas de resultados e os arquivamentos na SEC. Ele vem ativado por padrão, e a sua escolha é lembrada para a próxima execução.

Por que isso importa

As barras de preço do backtest não são ajustadas. Sem dados de calendário, um desdobramento 4 por 1 aparece como um colapso de 75% do preço da noite para o dia, e a sua posição simulada colapsa junto. Os dividendos também nunca chegam, o que subestima discretamente o retorno total de qualquer posição mantida por muito tempo.

Subopções

Duas subopções controlam como os eventos são aplicados às posições abertas durante a simulação:

Ambas as subopções ficam ativadas por padrão quando os dados de calendário estão ativados.

Observação sobre a estimativa da data ex: o EDGAR não publica as datas ex-dividendo. A menos que houvesse dados da bolsa, a data ex é estimada a partir da data de declaração (com precisão de cerca de ±7 dias) e é marcada com est. em Resultados dos testes. Os dividendos estimados são creditados por padrão; para ignorá-los, defina dividendDatePolicy como exact_only (ou off) em uma predefinição .qcs — a caixa não tem controle para isso. Filtre por d.estimated no código se a sua estratégia for sensível à data exata.

Universos de screener

Os dados de calendário funcionam com uma fonte de símbolos Screener. Os calendários são carregados depois que o filtro resolve a lista completa de tickers; símbolos correspondentes, mas sem barras de preço, não geram nenhuma requisição de calendário. Um filtro amplo pode incluir símbolos sem calendário no servidor — o log da execução informa a contagem em vez de falhar.

Onde você vê isso

• Painel de saída — uma linha [calendar] por evento corporativo aplicado durante a execução, mais uma linha de resumo no final.
• Test Results — as linhas Split e Dividend aparecem intercaladas na tabela de operações encerradas (que então se chama Closed trades & events), mostrando a razão ou o valor por ação e o impacto em dinheiro.

Veja Dados de calendário para a API completa de BacktestCalendar e o argumento de callback calendar.

---

Simulação — datas, saldo e custos de execução

Tudo o que segue fica na aba Simulation:

A caixa Run backtest não configura um intervalo de temporizador. O on_timer só está disponível em execuções forward (chart forward test, bulk forward / QuantCloud) quando timerIntervalMs está definido. Veja Ciclo de vida da estratégia.

Stop-loss / take-profit / dimensionamento de risco padrão opcionais ainda podem aparecer em predefinições .qcs quando presentes, mas a caixa Run backtest não expõe atualmente entradas de SL/TP / risco. Configure-os no código ou por predefinições, se os seus auxiliares os suportarem — veja Modelo de conta e Predefinições de execução (.qcs).

Comissão e slippage

As configurações de simulação podem ser salvas nas predefinições de execução (.qcs).

---

Parâmetros do script (execução única)

Se a sua estratégia importa from quantcraft.inputs import params (os caminhos mais antigos quantcraft.inputs_module / ide.inputs_module ainda são reconhecidos em scripts existentes) e referencia params.NAME, a caixa de diálogo mostra uma aba Script com uma linha por nome descoberto: Parameter, Type (int / float / str / bool) e Value.

Preencha todas as linhas antes de começar — é necessário um valor para cada parâmetro declarado. Eles são enviados como strings e convertidos pelo mecanismo antes de o seu arquivo ser carregado, então params.PERIOD (por exemplo) já tem o tipo Python correto quando o seu módulo é executado.

Na mesma aba, você pode ativar Optimize para busca em grade ou genética — veja Otimização. Deixe o Optimize desmarcado para um backtest único normal.

---

O que acontece ao iniciar a execução

O aplicativo valida o formulário (datas, símbolos, saldo, dados fundamentalistas, se ativados, e tipos dos parâmetros do script). Se tudo estiver certo, ele inicia um backtest com a configuração montada; o progresso e os logs aparecem no painel Output, e os resultados estruturados abrem em Test Results.

---

Referência rápida

---

Dicas

• Se os símbolos do feed da corretora nunca carregarem, abra o Trade uma vez ou confirme a conexão com a sua corretora; no B2, confirme que você está conectado e que o catálogo de símbolos foi carregado.
• O aquecimento só estende o histórico carregado — ele não adiciona dias de negociação fora do seu intervalo de datas.
• Não espere on_timer no backtest do IDE — não há controle de temporizador nessa caixa. Use on_bar / on_tick no lugar. Os temporizadores se aplicam às execuções forward quando timerIntervalMs está configurado.
• O on_tick no backtest usa OHLC sintético de cada barra (quatro chamadas por barra) — não dados reais de ticks. Teste a lógica de ticks ao vivo em execuções forward (Ciclo de vida da estratégia).
• Faça os pacotes de dados fundamentalistas corresponderem aos tickers que você realmente lê no código quando os tickers de OHLCV e de dados fundamentalistas diferirem.
• Use Min bars com moderação — é fácil encurtar uma execução mais do que você pretendia.