Screener

O Screener filtra um universo de mais de 10.000 ações dos EUA por suas demonstrações financeiras e mostra as correspondências em uma tabela ordenável. Monte um filtro com linhas de filtro sem código, ou escreva um Screener Script em Python para uma lógica que as linhas de filtro não conseguem expressar. Um filtro salvo também pode escolher os símbolos de uma execução forward em massa ou de um backtest.

Os filtros usam apenas dados fundamentalistas. Não há preço ao vivo nem dados de setor, então a tabela de resultados não tem colunas Market Cap / Last / Net Change por padrão — a descrição industry da SIC faz o papel do setor. Valor de mercado, enterprise value e o preço da ação no fim do período estão disponíveis como campos do grupo Valuation, então você pode filtrar por eles ou adicioná-los como colunas; eles refletem o fim de cada período, não a cotação de hoje. Criptomoedas estão excluídas: não têm demonstrações financeiras.

Você precisa estar conectado — os dados fundamentalistas são baixados dos servidores do QuantCraft.

---

Onde fica na interface

A página tem dois cartões: Filters (com as abas No-Code e Python Script) e Results. Run fica no rodapé de filtros, ao lado de Reset filters. O chevron do cartão Filters (Collapse filters) o recolhe para dar mais espaço aos resultados.

O botão Pop out ao lado do título abre o Screener em uma janela separada, para você manter um filtro em um segundo monitor enquanto trabalha no IDE ou em um gráfico. A janela é a mesma página — as predefinições e os Screener Scripts são compartilhados com a janela principal — mas cada janela mantém seus próprios filtros e resultados, e um filtro executa em uma janela por vez. Feche-a com ← Return to main window; o aplicativo não será encerrado enquanto houver uma janela destacada aberta.

Quando o QuantCraft AI está operando uma janela do Screener, você vê "The AI is using this window" e os controles ficam bloqueados até ele terminar.

---

Baixando os dados fundamentalistas

Na primeira vez que você usa o Screener, ele baixa todo o corpus de dados fundamentalistas para a sua máquina. Enquanto esse cache não tiver dados, os cartões Filters e Results são substituídos por uma tela de espera com um botão Download Fundamentals.

O download começa quando o aplicativo abre, não quando você abre o Screener — quando você chega à página, geralmente ele já está em andamento ou concluído. Clicar em Run durante um download nunca inicia um segundo.

• A primeira execução a frio leva minutos. Todas as seguintes levam segundos.
• O banner da execução mostra a fase (connecting → universe → download → convert → screen), um contador de fragmentos como shard 14 of 32, uma contagem de analisados/total e um botão Cancel. Uma execução a quente mostra apenas a fase de filtragem.
• O banner conta o tempo decorrido para cima e não mostra ETA — uma execução cuja duração varia em minutos não pode ser prevista com honestidade. Ao terminar, você recebe um resumo como 12 matched in 3m 20s, seguido de · Fundamentals updated <time>. Se alguns símbolos não puderam ser obtidos, um link clicável N unavailable abre a lista.
• Um download interrompido é retomado na próxima execução em vez de recomeçar. Cancelar no meio do download é seguro: a parte inacabada é simplesmente obtida de novo da próxima vez.
• Um download continua mesmo se você sair da página.

Com que frequência os dados são atualizados

62 dias são cerca de um trimestre, então uma empresa só é reverificada quando o seu próximo arquivamento provavelmente já saiu.

À direita do banner você verá uma linha como 10,384 symbols cached · 250 MB com um botão Clear cache (oculto enquanto um filtro está executando, desativado enquanto a IA usa a janela). Limpar pede confirmação — Clear cache ou Keep it — porque descarta um download de vários minutos. O cache é um dado regenerável que uma desinstalação não remove, e é por isso que ele é visível e recuperável aqui.

Depois de uma atualização do aplicativo que muda o formato do cache, o próximo filtro baixa o universo inteiro de novo uma vez (isso aconteceu quando Per Share, Valuation e Scores foram adicionados).

---

Montando um filtro (No-Code)

Cada linha de filtro é lida da esquerda para a direita: Period → Field → Filter type → entrada(s) de valor. Use + para adicionar uma linha e − para remover. O botão + pergunta se a nova linha é de Fundamentals ou de Industry.

As linhas se combinam com AND — um símbolo precisa satisfazer todas as linhas ativadas. (Uma predefinição criada pela IA ou importada de um arquivo pode usar OR — "Any filter can match"; Load Preset mostra qual.)

A linha inicial padrão (Quarterly / Total Revenue / % Change / 1 period back / min 0%) é válida como está, então Run funciona de imediato. Antes de uma execução começar, cada linha ativada é validada; se alguma estiver incompleta, você recebe um aviso e um erro na própria linha, e a execução não começa — uma varredura de vários minutos não deve começar com uma consulta inutilizável.

Um exemplo prático: Quarterly / Total Revenue / % Change / periods back 3 / min 1 / max 3 encontra empresas cuja receita cresceu entre 1% e 3% nos últimos três trimestres.

Tipos de filtro

Todo filtro lê o valor mais recente, a menos que se diga o contrário.

Os dois filtros de ranking são decididos sobre toda a população, não símbolo a símbolo, então são resolvidos depois que todos os símbolos foram analisados. Um símbolo sem valor no campo ranqueado nunca pode ganhar um.

O maior periods back que você pode usar é 40.

Escolhendo um campo

O seletor de campos tem busca e agrupa os campos nesta ordem:

Ratios → Valuation → Scores → Per Share → Income Statement → Balance Sheet → Cash Flow → Financials Extended → Earnings History

Os índices vêm primeiro porque são os mais relevantes para um screener e já estão normalizados por unidade. As entradas de valor seguem a unidade do campo — $, %, dias, ações, valores por ação, contagens ou um número simples, conforme o caso. Veja a Referência de campos de dados fundamentalistas para saber o que cada grupo contém.

• Todos os grupos suportam trimestral e anual, exceto Earnings History, que é somente trimestral, e os campos CAGR (revenueCagr3y, revenueCagr5y, …), que são somente anuais e somem do seletor trimestral. Mudar o período limpa o campo se ele não existir para o novo período.
• "Periods back" conta linhas dentro do período escolhido. Trimestral + 3 significa três trimestres; anual + 3 significa três exercícios. Não há mistura dos dois.
• Os múltiplos de Valuation são dos últimos doze meses mesmo em uma linha trimestral.
• Os campos de Financials Extended variam por símbolo. Eles só aparecem no seletor depois que o cache de dados fundamentalistas foi baixado e são marcados como "varies by symbol". Um filtro sobre um campo que uma empresa não reporta simplesmente reprova aquela empresa — combine com Has a value quando isso importar.
• Fins de período com data futura são ignorados, então "último" nunca é um período que ainda não aconteceu.
• Não filtráveis: Company Info, Earnings Trend, Earnings Annual, TTM, a avaliação mais recente (a partir de hoje), a procedência das métricas, os componentes dos scores de Piotroski / Beneish e chaves de texto ou sim/não como priceBasis ou approximate. Elas ou não têm um período de relatório para comparar, ou não são números.

Campos aposentados. Oito campos antigos de Financials Extended foram retirados porque agora existem versões melhores: ebitda, ebitdaMargin, enterpriseValue, priceToEarnings, priceToBook, priceToSales, evToEbitda, evToRevenue. Um filtro salvo que usava algum deles perde essa linha (ou coluna) ao ser carregado — reconstrua-o a partir do grupo Valuation, que calcula esses valores com base nos últimos doze meses, então os valores diferem dos antigos. (ratios.debtToEquity foi simplesmente renomeado para ratios.debtToEquityRatio e continua carregando.)

Linhas de Industry

Uma linha Industry substitui os controles de campo/tipo/valor por uma seleção múltipla de indústrias; um símbolo passa se a sua indústria for uma das escolhidas. Pelo menos uma indústria deve ser selecionada. A lista é montada a partir dos dados que você realmente baixou.

---

Modo Python Script

Escolha Python Script quando uma pilha de comparações ligadas por AND não for suficiente — aritmética com vários campos, lógica condicional ou o seu próprio score de ranking.

Crie o arquivo no IDE do QuantCraft por New File → Screener Script; ele vem com um modelo funcional. Qualquer arquivo .py do seu espaço de trabalho que defina um filter() de nível superior também se qualifica. A aba Python Script do Screener os lista (rotulados pelo caminho da pasta, para que arquivos de pastas diferentes continuem distinguíveis) e mostra uma prévia do selecionado. Seus outros arquivos do espaço de trabalho são enviados junto com a execução, então o seu script pode importar seus próprios módulos auxiliares.

filter(fundamentals, symbol) é chamada uma vez por ticker e deve retornar um dict com um "result" booleano. "value" é opcional e é o que você quiser levar para o ranking. Um script que lança exceção, retorna um simples True ou retorna um dict sem "result" booleano conta como sem correspondência apenas para aquele ticker — um ticker ruim nunca aborta a execução.

rank(value, symbol) é opcional e só executa para os tickers que corresponderam. Retorne um número real — qualquer escala serve (0-1, 1-10, 0-100), e maior sempre significa melhor. Ela preenche a coluna ordenável Rank, que aparece somente no modo Python Script. Um rank() que falha não desfaz a correspondência da linha; a linha mantém sua correspondência e seu rank aparece como —, ordenado por último.

O argumento symbol é opcional nas duas funções — as versões antigas de um único argumento filter(fundamentals) e rank(value) ainda funcionam.

O argumento fundamentals

Nada "na data do upload" chega a um script: ttm, valuation.latest, metricsInputs e metricsHealth não têm período, e um filtro compara períodos entre símbolos. Os múltiplos de valuation são dos últimos doze meses mesmo em uma linha trimestral, e um múltiplo None ao lado de um rendimento com sinal significa um denominador não positivo, não um dado ausente.

• Os valores são números ou None — nunca strings como "1234.00". As chaves que não são números ficam de fora por completo: beforeAfterMarket, reportDate e currency em earnings.history, os detalhamentos piotroskiComponents / beneishComponents em scores, e sinalizadores de texto como priceBasis / approximate em valuation.
• As linhas vão da mais antiga para a mais recente, então rows[-1] é o último período. Cada linha traz uma date (o fim do seu período).
• Você recebe no máximo os 12 trimestres mais recentes e os 6 anos mais recentes, o que limita até onde um script pode olhar para trás.

Tudo que o seu script imprimir com print() é capturado e exibido pelo botão Output logs ao lado de Run — também em execuções com falha, para você ver o que foi impresso logo antes de uma queda. O buffer comporta 200.000 caracteres e descarta a saída mais antiga além disso. Uma execução no-code não limpa os logs da última execução de script.

Run é bloqueado com um aviso se nenhum script estiver selecionado ou se o arquivo selecionado não tiver filter().

---

Resultados

Cada linha mostra uma estrela e um botão de gráfico, Rank (somente no modo Python Script), Symbol, Company, Industry e As of, além de uma coluna por linha de filtro com o valor que correspondeu (modo No-Code) e quaisquer campos extras que você adicionar.

"As of" é o fim de período mais recente usado para aquele símbolo — o período fiscal com o qual os seus filtros foram de fato avaliados. Nunca é um período futuro.

As correspondências aparecem todas de uma vez quando a execução termina, então a tabela fica vazia enquanto um filtro está em andamento — acompanhe o progresso no banner.

Os resultados não são salvos. Recarregar o aplicativo limpa a tabela de propósito, já que um resultado desatualizado é pior que nenhum. Seus filtros, colunas, símbolos marcados, aba ativa e script selecionado são lembrados.

---

Predefinições

Uma predefinição é um instantâneo nomeado das suas linhas de filtro, da junção entre elas e das suas colunas de resultados.

Dentro de Load Preset você também pode:

• Delete preset — remove-a após uma confirmação.
• Export preset — salva-a como um arquivo JSON que você pode compartilhar ou usar como backup.
• Import preset — carrega uma predefinição de um arquivo JSON assim.

---

Usando um filtro para escolher símbolos

Execuções forward em massa

Na aba Targets da caixa New Run, escolha o escopo Screener. A execução negocia o que uma predefinição salva ou um Screener Script selecionar, refiltrando a cada Refresh interval (days) enquanto estiver ativa. Include tickers with open positions mantém uma posição na rotação depois que ela deixa de corresponder. Os alvos Screener são apenas de ações. Com Use fundamentals ativado, todo símbolo do filtro atual recebe automaticamente os seus dados fundamentalistas, e o conjunto acompanha cada nova filtragem.

No QuantCloud o executor mantém sua própria cópia dos dados fundamentalistas de que o filtro precisa. A primeira execução do screener em um executor novo baixa tudo, o que leva um tempo; depois disso ele só atualiza uma vez por dia. O executor usa o seu login para baixar e não consegue renová-lo sozinho, então em uma execução de muitos dias, as novas filtragens continuam usando os dados que ele já tem depois que o login expira.

Por que 16:30 ET é o padrão. Assumir um novo universo reinicia a execução, então uma nova filtragem às 11:00 interromperia a negociação ao vivo. Ancorá-la a um horário depois do fechamento faz a atualização acontecer enquanto nada está sendo negociado e a nova lista de símbolos fica pronta antes de a próxima sessão abrir.

• O horário é sempre o do mercado (ET), qualquer que seja o seu fuso. O texto de ajuda sob o campo mostra o seu equivalente local, então 16:30 ET · 21:30 your time é o mesmo instante, não duas configurações.
• Alterá-lo é permitido a qualquer momento. Se você escolher um horário dentro da sessão 09:30–16:00 ET, aparece um aviso sob o campo explicando que a reinicialização interromperá a negociação, mas a execução ainda começa — a escolha é sua.
• O intervalo e o horário funcionam juntos. 1 dia às 16:30 refiltra todo dia depois do fechamento; 3 dias às 16:30 refiltra depois do fechamento a cada três dias.
• Deixar o campo vazio ou digitar algo que não seja HH:MM bloqueia a execução com um erro na linha.

Veja AutoTrading e QuantCloud para a caixa New Run completa.

Backtests

Na aba Symbol & data da caixa Run backtest, defina Symbol source como Screener. Em vez de negociar uma lista fixa, o backtest reexecuta o seu filtro ao longo do caminho e negocia o que correspondia naquele ponto da simulação.

Os dados fundamentalistas acompanham o filtro. Com Uses fundamentals ativado, todo símbolo filtrado recebe automaticamente os seus dados fundamentalistas em on_bar / on_tick — não é preciso escolhê-los. Eles são lidos do cache do Screener, então um símbolo que o Screener já baixou não custa nenhum download extra. Sempre passe symbol=symbol ao lê-los — veja Dados fundamentalistas.

"Keep tickers with an open position" afeta a negociação, não a avaliação. Ativado, um símbolo que você ainda mantém continua recebendo barras depois de sair do filtro, para que a sua estratégia possa sair dele. Desativado, o símbolo para de receber callbacks e a posição simplesmente permanece aberta até o fim do backtest. De qualquer forma a posição é sempre marcada ao preço real do símbolo, então a sua curva de patrimônio e as métricas ficam corretas.

on_init é disparada de novo a cada rebalanceamento. Quando uma fonte de símbolos de screener está ativa, o mecanismo chama on_init(symbols=<ticker list>) novamente cada vez que o filtro reexecuta. Isso permite que a sua estratégia responda a um novo universo sem reiniciar a simulação. Pontos principais:

• No início da execução, on_init dispara duas vezes seguidas — a chamada de configuração padrão (com symbols=None) seguida imediatamente do resultado inicial do filtro.
• Cada novo disparo enxerga o estado de nível de módulo deixado pela chamada anterior. O estado não é redefinido entre rebalanceamentos.
• Estratégias que declaram def on_init(): (sem parâmetro) não são afetadas — argumentos opcionais são casados por nome, então o symbols ausente é simplesmente ignorado.

Dados de calendário para um universo filtrado

Include calendar data funciona com uma fonte de símbolos de screener. Os calendários são carregados depois que o filtro resolve a lista completa de tickers de um rebalanceamento — não há atraso de consulta por tick. Pontos a saber:

• Símbolos que o filtro encontrou mas sem barras de preço (fora do intervalo de datas ou retirados de negociação antes de a execução começar) não custam nenhuma requisição de calendário.
• Um filtro amplo frequentemente encontra símbolos sem calendário no servidor — em geral tickers menores ou com menos cobertura. O log da execução informa a contagem em vez de falhar a execução.
• Os calendários são atualizados a cada rebalanceamento para cobrir tickers recém-adicionados.

Os resultados aparecem em uma aba Screener Output ao lado de Logs, mostrando cada rebalanceamento como uma data recolhível. Clique em + para expandir uma data e ver os símbolos negociados naquela janela, ou use Expand all. Como o filtro é resolvido antes da primeira barra, o cronograma inteiro está disponível desde o início.

Requisitos a conhecer: um backtest guiado por screener precisa de datas de início e fim explícitas; intervalos de tempo adicionais não são suportados (então get_bar retorna None — use os deslocamentos bar.close[i] de cada ticker para o histórico); e o Debug Test não pode usar uma fonte de símbolos de screener — mude para Selected symbols para depurar. Veja Backtests.

Point-in-time e viés de sobrevivência

Cada rebalanceamento só enxerga os relatórios que já haviam sido arquivados naquela data. Um filtro em 5 de maio de 2021 não verá um trimestre que terminou em abril mas só foi publicado em junho. A exceção é um período sem data de arquivamento registrada, que é admitido a partir do fim do período — raro, mas significa que uma pequena quantidade de antecipação é possível ali. É isso que torna o resultado honesto, e também é por isso que as escolhas de um backtest não coincidem com o que você obtém filtrando a mesma data com os dados de hoje.

Duas coisas ainda refletem hoje, não a data simulada:

• Em um feed de corretora conectada, as correspondências são filtradas para símbolos negociáveis na sua corretora agora, então uma empresa retirada de negociação desde então é descartada até de um rebalanceamento em que era perfeitamente negociável. Um feed do QuantCraft (B2) pula essa verificação.
• O universo em cache só contém as empresas que o corpus de dados fundamentalistas ainda mantém, então uma empresa retirada de negociação há muito tempo não aparecerá.

A precisão point-in-time se aplica aos valores que um filtro lê, não a quais empresas existem nele. Tenha isso em mente ao analisar resultados de longo horizonte.

---

Interpretando os resultados

Não ter histórico suficiente reprova um símbolo — ele nunca passa em silêncio. Pedir "Grew 8 in a row" para uma empresa com cinco trimestres de dados a exclui. Excluir em vez de aprovar garante que um conjunto de resultados nunca superestime.

Outros casos em que um símbolo é excluído em vez de correspondido:

• % Change não pode ser calculado a partir de um valor inicial zero.
• CAGR % precisa que ambas as pontas sejam positivas.
• Average over N falha se algum valor da janela estiver ausente — nulos não são ignorados.
• Um campo que a empresa não reporta reprova essa empresa, o que importa mais em Financials Extended.
• Os filtros de ranking rejeitam símbolos sem valor para o campo ranqueado.

Uma peculiaridade do ranking: valores empatados não compartilham um rank percentil, então dois valores idênticos podem cair em lados opostos de um corte Percentile rank ≥.

Se o servidor não puder ser alcançado, você recebe um erro claro em vez de um fallback lento e silencioso, e uma execução que fica quieta por 90 segundos é reportada como erro em vez de travar.

---

Veja também

• AutoTrading — execuções forward em massa, incluindo o escopo de alvo Screener
• QuantCloud — executores na nuvem com tarefas em massa guiadas pelo Screener
• Backtests — usando um filtro como fonte de símbolos do backtest
• Dados fundamentalistas — lendo dados fundamentalistas nos callbacks de estratégia, e a referência de campos
• QuantCraft AI — deixando a IA montar e executar filtros para você
• Fatores Fama-French — os dados de fatores por trás da aba Factor Exposure da caixa de detalhes