Dados fundamentalistas

Trabalho em andamento: os dados fundamentalistas ainda não são totalmente funcionais. Usar este recurso no IDE ou em backtests pode retornar dados fundamentalistas inconsistentes (campos ausentes, datas de relatório divergentes ou snapshots alinhados às barras instáveis). Trate os resultados como experimentais até que uma versão futura marque os dados fundamentalistas como estáveis.

As estratégias do QuantCraft podem usar dados financeiros de empresas junto com as barras de preço OHLCV: balanços, demonstrações de fluxo de caixa, demonstrações de resultados e histórico / estimativas de resultados. Os dados são carregados uma vez por símbolo a partir do serviço de dados fundamentalistas do QuantCraft, organizados como tabelas indexadas por data e disponibilizados à sua estratégia como snapshots alinhados às barras durante um backtest. O momento dos callbacks segue o Ciclo de vida da estratégia; configure símbolos e datas no Test (Executando código).

Além das três demonstrações, você recebe índices (91 deles), valores por ação, múltiplos e rendimentos de valuation e scores de qualidade (Piotroski F, Altman Z-prime, Beneish M) — todos point-in-time, todos opcionais. Eles são liberados símbolo a símbolo, então proteja cada acesso: raw["metricsInputs"] is None significa que um pacote é anterior a eles.

Esta página cobre:

• Quais dados de demonstrações financeiras estão disponíveis
• Como as tabelas indexadas por data são organizadas
• Como as cargas alinhadas às barras chegam aos seus callbacks durante um backtest

Relacionado: os conjuntos de dados globais de retornos de fatores Fama-French (não por ticker) são um recurso separado — veja Fatores Fama-French (fama_french.qc, sem argumento de callback). As rows dos fatores são indexadas por strings YYYYMM, não por índices de lista.

---

O que você recebe

Cada pacote de dados fundamentalistas é um único objeto JSON de um ticker, contendo:

• Balanço — relatórios quarterly e yearly.
• Fluxo de caixa — relatórios quarterly e yearly.
• Demonstração de resultados — relatórios quarterly e yearly.
• Resultados (earnings):
  • History — LPA divulgado vs. estimativas e surpresas por data de relatório.
  • Trend — estimativas futuras, tendência do LPA e revisões de analistas.
  • Annual — epsActual por exercício fiscal.
• Índices (Ratios) — índices financeiros quarterly e yearly (margens, retornos, liquidez, alavancagem).
• Financials extended — métricas estendidas quarterly e yearly que não estão nas demonstrações básicas de resultados, balanço ou fluxo de caixa.
• Por ação — valores por ação quarterly e yearly como arquivados (quantidade de ações na base de desdobramento daquele período).
• Valuation — valor de mercado, enterprise value, múltiplos e rendimentos quarterly e yearly, mais um objeto latest sem data.
• Scores — Piotroski F, Altman Z-prime e Beneish M quarterly e yearly, mais notApplicableReason.
• TTM — um único objeto dos últimos doze meses (não agrupado por período).
• Procedência das métricas — objetos planos metricsInputs / metricsHealth. metricsInputs é None em um pacote anterior à expansão das métricas.
• Histórico de arquivamentos — metadados de arquivamento quarterly e yearly (tipo de formulário, data de arquivamento, indexados pelo fim do período). Também incluído nos snapshots alinhados às barras current(...) quando presente no pacote; as tabelas brutas continuam disponíveis por f.tables["filingHistory.quarterly"].
• Informações da empresa — metadados planos da entidade (nome, CIK, SIC, endereço, bolsas, tickers). Não indexados por data e fora dos snapshots alinhados às barras; acesse por f.raw["companyInfo"].

Cada relatório é uma linha de métricas em camelCase — por exemplo totalAssets, cash, freeCashFlow, totalRevenue, netIncome, epsActual, epsEstimate, surprisePercent. Os valores numéricos podem chegar como strings no JSON subjacente, e qualquer campo ausente volta como None.

Um determinado ticker pode não expor todas as seções. Veja o Explorador de cobertura de dados fundamentalistas para conferir quais campos estão disponíveis para um ticker.

---

Tabelas indexadas por data

Para cada seção acima, os dados fundamentalistas são organizados como uma tabela indexada por data: as linhas são indexadas pela data do relatório (YYYY-MM-DD), e as métricas são expostas como listas paralelas que você pode indexar como um histórico de preços.

Os caminhos de tabela padrão são:

Não são tabelas. valuation.latest, scores.notApplicableReason, ttm, metricsInputs, metricsHealth e companyInfo não são indexados por data, então não aparecem em tables, lists nem em nenhum snapshot no horário de uma barra — isso é intencional:

Todos são da data do upload e não por período, então mantê-los fora de tables também os mantém fora de todo snapshot no horário de uma barra — um backtest não pode ler por acidente o preço de hoje em uma barra de 2019. Acesse-os por f.raw. Um bloco vazio ({"quarterly": {}, "yearly": {}}, que é a aparência dos scores de um declarante do setor financeiro) não registra tabela alguma.

Convenção de índices: do mais novo para o mais antigo

Dentro de qualquer uma dessas tabelas, o índice 0 é o período elegível mais recente, o índice 1 é o anterior, e assim por diante. Isso é igual ao funcionamento das séries de preços no resto do QuantCraft.

Se você quiser carregar um pacote diretamente (por exemplo, fora de um backtest), o formato básico é:

O que você pode ler de um pacote carregado:

Uma DateKeyedTable expõe periods (as chaves YYYY-MM-DD, do mais novo ao mais antigo), columns (campo → valores) e suporta a indexação table["fieldName"].

Descobrir campos em tempo de execução é fácil: sorted(f.lists.keys()) mostra cada série plana, e sorted(t.columns.keys()) mostra as colunas de uma tabela — útil quando um servidor adiciona ou remove campos.

---

Cargas alinhadas às barras em backtests

Em um backtest, você não lê os dados fundamentalistas como tabelas brutas — o mecanismo seleciona o relatório certo para a barra atual e o entrega aos seus callbacks como um snapshot. Isso é chamado de carga alinhada às barras.

Configurando os dados fundamentalistas para um backtest

Na aba Symbol & data do Run backtest:

1. Marque Uses fundamentals (select if your strategy requires fundamental data) (exige login — o QuantCraft envia o seu token de sessão para carregar os arquivos de dados fundamentalistas do B2). As execuções forward em massa e no gráfico o chamam de Use fundamentals (optional). A caixa aparece quando os recursos de dados fundamentalistas estão disponíveis na 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.
2. Escolha um ou mais pacotes de dados fundamentalistas na seleção múltipla (caminhos como fundamentals/AAPL.json.gz).

Com uma fonte de símbolos Screener (backtest) ou um alvo Screener (execuções em massa do AutoTrading / QuantCloud) você não precisa escolher nada: ative os dados fundamentalistas e todo símbolo que o filtro selecionar recebe o seu próprio pacote, de modo que fundamentals.current(bar["t"], symbol=symbol) funciona para cada um. Os pacotes vêm do próprio download do Screener (nada é buscado duas vezes), e um símbolo que o Screener ainda não baixou é buscado uma vez e guardado. Em uma execução ao vivo, os pacotes acompanham cada nova filtragem. Escolhas manuais continuam sendo aceitas como extras (por exemplo, um ticker de referência). Um símbolo cujos dados não podem ser carregados retorna None em vez de falhar a execução — o painel Output informa quantos foram carregados.

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 — passe o ticker correto a fundamentals.current(..., symbol="RHM.XETRA") (ou equivalente) no código.

Quando vários pacotes estão selecionados, use symbol= explícito em fundamentals.current / get_data_with_offset quando precisar de um pacote específico. O pacote principal usado nos snapshots alinhados às barras é, por padrão, o primeiro símbolo OHLCV da sua lista de símbolos, a menos que o mecanismo aplique outra regra.

Para acesso de baixo nível às tabelas fora dos callbacks, use qc_fundamentals de quantcraft.process.runtime quando não for None (por exemplo qc_fundamentals.raw["companyInfo"]). Ele guarda apenas o pacote principal; use o identificador fundamentals do callback com symbol= para qualquer outro ticker.

Se os dados fundamentalistas não estiverem configurados, o mecanismo simplesmente passa fundamentals=None aos seus callbacks, e você o protege com uma verificação.

Point-in-time (backtest): tanto o mecanismo de backtest quanto o Debug Test constroem BacktestFundamentals(..., backtest_mode=True), então current / get_data_with_offset usam filtragem por data de arquivamento (use_filing_date=True) — um período é excluído se o seu filing_date for posterior ao horário da barra. Quando um período não tem um filing_date utilizável, usa-se um prazo de arquivamento presumido — 45 dias após o fim do período nas tabelas trimestrais, 90 dias nas anuais (default_filing_lag_days) — em vez de tornar o relatório visível no dia em que o período fecha. As execuções forward usam elegibilidade pelo fim do período (backtest_mode=False). Prefira o identificador fundamentals do callback nos backtests do IDE; chamar qc_fundamentals.get_data_with_offset(...) diretamente sem use_filing_date=True pode antecipar em relação às datas de arquivamento.

Execuções forward: uma execução ao vivo recarrega seus dados fundamentalistas cerca de a cada hora, e em cerca de 5 minutos depois que os dados do Screener são atualizados. Uma recarga com falha mantém os dados anteriores. Como o "agora" de uma execução forward é de fato hoje, os blocos da data do upload (raw["ttm"], raw["valuation"]["latest"], …) são dados atuais ali, não antecipação.

Callbacks legados: estratégias mais antigas podem usar um argumento qc_fundamentals separado ou um dict bruto em vez de BacktestFundamentals. A assinatura moderna passa fundamentals como terceiro argumento de on_bar / on_tick. O alias de nível de módulo fundamentals_as_of_bar corresponde ao mesmo formato de carga alinhada às barras.

O parâmetro de callback fundamentals

Quando os dados fundamentalistas são carregados, o mecanismo passa um identificador BacktestFundamentals como argumento fundamentals a on_bar, on_tick e (quando usado nas execuções forward) on_timer:

Como é o snapshot

Um snapshot alinhado à barra é um dict aninhado com apenas os períodos válidos no horário dessa barra (com filtragem por data de arquivamento nos backtests do IDE). Cada seção não nula inclui um periodEnd mais as métricas do relatório:

Trend pode ser null quando nenhum período se qualifica no horário da barra ou antes. O priceToEarningsRatio: null ao lado de earningsYield: -5.0 acima é uma empresa com prejuízo, não dado ausente — veja Valuation.

Nunca no snapshot: ttm, valuation.latest, scores.notApplicableReason, metricsInputs, metricsHealth, companyInfo. Eles são da data do upload e não por período; anexá-los a uma barra vazaria informação futura para um backtest. Leia-os de qc_fundamentals.raw[...].

O mesmo dict por barra aparece no campo fundamentals de cada linha do resultado do backtest estruturado, então o que você vê na estratégia corresponde ao que aparece nos dados do resultado.

Consultando períodos mais antigos (get_data_with_offset)

Às vezes você quer não o último relatório no horário de uma barra, mas um anterior — o trimestre anterior, o exercício anterior, a linha de resultados anterior:

Comportamento:

• Cada subtabela é indexada de forma independente. Com offset=1, a seção balanceSheet.quarterly recua um trimestre, enquanto balanceSheet.yearly recua um exercício, e assim por diante.
• Se uma subtabela não tem histórico suficiente antes da barra atual, a sua seção é null no dict retornado (e uma nota de uma linha pode ser impressa).
• O formato é o mesmo de current(...), mais um "offset": <int> de nível superior.
• Na API bruta QcFundamentals, a assinatura preferida é f.get_data_with_offset(bar_time, offset, *, print_on_shortfall=True, use_filing_date=False). A função de nível de módulo get_data_with_offset(qc, bar_time, offset, *, print_on_shortfall=True) não tem o parâmetro use_filing_date — ela sempre usa elegibilidade pelo fim do período, então chame o método com use_filing_date=True (ou use o identificador do callback) para dados point-in-time. O padrão use_filing_date=False significa apenas elegibilidade pelo fim do período (pode antecipar em relação às datas de arquivamento). Com use_filing_date=True, um período cujo filing_date está ausente recorre a um prazo presumido de 45 dias (trimestral) / 90 dias (anual) após o fim do período. Prefira o identificador fundamentals do callback nos backtests do IDE, que usa a filtragem por data de arquivamento automaticamente.

Dados fundamentalistas com vários símbolos

Quando você carrega vários pacotes (para estratégias transversais ou de comparação), pode escolher de qual ler com symbol="TICKER":

• Omitir symbol usa o pacote principal: o único carregado; senão fundamentals.primary se definido, senão o símbolo negociado, senão o ticker carregado primeiro em ordem alfabética. Em uma execução com vários símbolos ou Screener, esse recurso pode silenciosamente apontar a empresa errada — sempre passe symbol=symbol ali.
• fundamentals.symbols lista cada chave de ticker em maiúsculas atualmente carregada.
• fundamentals.primary_symbol() retorna a chave principal.
• O símbolo que você negocia no backtest pode ser diferente do(s) símbolo(s) de dados fundamentalistas que você carrega — por exemplo, negociar SPY enquanto lê os dados fundamentalistas de AAPL e MSFT.

Horários de barra aceitos

Tanto current(...) quanto get_data_with_offset(...) aceitam vários formatos de horário, para que você possa passar bar["t"], bar.t[0] ou um valor próprio:

• datetime (o ingênuo é tratado como UTC),
• date,
• string ISO (incluindo um Z final),
• segundos epoch UNIX (int / float).

---

Padrões práticos

Alguns formatos comuns:

---

Referência de campos de dados fundamentalistas

A disponibilidade dos campos depende do símbolo — nem todo emissor reporta cada linha. Use sorted(f.lists.keys()) ou sorted(t.columns.keys()) em tempo de execução para ver o que um pacote específico realmente expõe. Os valores numéricos podem chegar como strings; converta com float(...) para fazer contas.

Balanço

Tabelas: balanceSheet.quarterly, balanceSheet.yearly

Fluxo de caixa

Tabelas: cashFlow.quarterly, cashFlow.yearly

Demonstração de resultados

Tabelas: incomeStatement.quarterly, incomeStatement.yearly

Resultados — History

Tabela: earnings.History (LPA divulgado vs. estimativas por data de relatório)

Resultados — Trend

Tabela: earnings.Trend (estimativas futuras e revisões)

Resultados — Annual

Tabela: earnings.Annual (LPA anual divulgado)

Índices (Ratios)

Tabelas: ratios.quarterly, ratios.yearly

91 métricas desde a expansão das métricas (94 chaves contando date, currency_symbol e filing_date). O conjunto original vem listado primeiro; tudo a partir de Capital de giro é novo. Um símbolo no meio da liberação pode trazer só o conjunto original, então descubra a lista real com sorted(f.table("ratios.quarterly").columns.keys()).

Conjunto original

Os campos de margem e retorno deste grupo (grossMargin, operatingMargin etc.) são frações decimais — multiplique por 100 para obter porcentagem. debtToEquity foi renomeado para debtToEquityRatio.

Capital de giro

Alavancagem e cobertura

Todos são decimais simples (4 dec.).

Retornos

Margens e intensidade de capital

Distribuição

Todos são porcentagens (2 dec.): dividendPayoutRatio, freeCashFlowPayoutRatio, shareholderPayoutToFreeCashFlow, retentionRatio, sustainableGrowthRate.

Crescimento, ano contra ano

Todos são porcentagens (2 dec.). O crescimento de receita / lucro líquido / LPA não é duplicado aqui — está em earnings.Trend.

CAGRs — somente yearly

Todos são porcentagens (2 dec.) e null em todo período quarterly — um filtro ou regra que peça um deles em um período trimestral reprova todos os símbolos.

revenueCagr3y / revenueCagr5y, netIncomeCagr3y / netIncomeCagr5y, epsCagr3y / epsCagr5y, freeCashFlowCagr3y / freeCashFlowCagr5y, dividendCagr3y / dividendCagr5y.

Financials extended

Tabelas: financialsExtended.quarterly, financialsExtended.yearly

Os campos variam por símbolo e não são enumerados aqui. Descubra o que um pacote carregado expõe em tempo de execução:

Os campos comuns incluem métricas de EBITDA estendidas, componentes do capital de giro e dados por ação que não estão na demonstração de resultados básica.

Campos aposentados: ebitda, ebitdaMargin, enterpriseValue, priceToEarnings, priceToBook, priceToSales, evToEbitda e evToRevenue estão sendo retirados de Financials extended em favor das versões de Valuation e de Índices (Ratios), calculadas sobre os últimos doze meses (portanto os valores diferem).

Por ação

Tabelas: perShare.quarterly, perShare.yearly

Um registro como arquivado: sharesOutstanding está na base de desdobramento reportada para aquele período, então não é comparável entre os dois lados de um desdobramento. Use Valuation para qualquer comparação. Os valores são strings de 4 casas decimais, salvo indicação em contrário.

Valuation

Tabelas: valuation.quarterly, valuation.yearly (mais o valuation.latest, que não é tabela)

Três regras:

1. Os múltiplos são marketCap / agregado, não price / perShare. Não os recalcule a partir de perShare — comparativos reapresentados fazem os dois divergirem nos períodos mais antigos.
2. Um múltiplo None ao lado de um rendimento com sinal está correto, não é bug. Os múltiplos marcados como null com denominador não positivo abaixo viram None quando o denominador não é positivo, enquanto os rendimentos e o bookToMarketRatio mantêm o sinal. Uma empresa com prejuízo mostra priceToEarningsRatio: None e earningsYield: -5.0.
3. Os múltiplos são dos últimos doze meses, mesmo em períodos trimestrais — um P/L trimestral é um verdadeiro P/L dos últimos doze meses, não um trimestre anualizado.

Metadados

Tamanho: marketCap, enterpriseValue — strings monetárias de 2 casas.

Múltiplos (números de 4 casas)

Rendimentos — porcentagens de 2 casas, com sinal: earningsYield, ebitToEnterpriseValueYield, freeCashFlowYield, operatingCashFlowYield, dividendYield, buybackYield, shareholderYield.

valuation.latest — não é um período. Um único objeto que carrega todos os campos acima mais priceAsOf, priceAgeDays, priceSource, fundamentalsAsOf e ttmBasis. Fica ao lado das chaves de data, então não é uma entrada de tabela e nunca aparece em um snapshot no horário de uma barra — lê-lo em um backtest seria antecipação. Acesse-o por qc_fundamentals.raw["valuation"]["latest"]; é None quando não há preço disponível.

Scores

Tabelas: scores.quarterly, scores.yearly

Duas ausências esperadas, nenhuma delas é um erro:

• O primeiro período de um declarante não traz scores — eles precisam de um ano anterior para comparar.
• Para os SIC 6000–6799 (bancos, corretoras, seguradoras, REITs) ambos os grupos ficam vazios e scores.notApplicableReason é "financial-sector-sic". Trate isso como "não aplicável", não como "sem dados". Leia-o de qc_fundamentals.raw["scores"]["notApplicableReason"].

TTM

ttm é um único objeto, não uma tabela — agregados dos últimos doze meses na data do upload, não na data de qualquer barra. Ele nunca aparece em um snapshot; acesse-o por qc_fundamentals.raw["ttm"] (seguro nas execuções forward, antecipação em um backtest).

• Metadados: basis ("quarterly" / "annual"), asOf, periodsUsed (list[str]), complete (bool), synthetic (bool — o 4T fiscal foi reconstruído; normal, geralmente true), coverageDays (cerca de 365).
• Fluxos — somados em 4 trimestres, strings de 2 casas exceto epsBasic / epsDiluted (4 dec.): totalRevenue, grossProfit, operatingIncome, ebit, ebitda, netIncome, epsBasic, epsDiluted, depreciationAndAmortization, interestExpense, incomeBeforeTax, incomeTaxExpense, costOfRevenue, sellingGeneralAdministrative, researchDevelopment, taxProvision, totalCashFromOperatingActivities, totalCashflowsFromInvestingActivities, capitalExpenditures, freeCashFlow, dividendsPaid, stockBasedCompensation, paymentsForRepurchaseOfCommonStock, proceedsFromIssuanceOfCommonStock, repaymentsOfLongTermDebt.
• Saldos pontuais — último período, nunca somados, strings de 2 casas: totalAssets, totalLiab, totalStockholderEquity, totalCurrentAssets, totalCurrentLiabilities, totalDebt, netDebt, cashAndShortTermInvestments, goodWill, intangibleAssets, netWorkingCapital, retainedEarnings, netReceivables, inventory, accountsPayable, propertyPlantAndEquipmentNet, preferredStockTotalEquity, commonStockSharesOutstanding, minorityInterest.

Procedência das métricas (metricsInputs / metricsHealth)

Objetos planos que descrevem de onde vieram as métricas:

Confira metricsHealth["prices"] != "absent" antes de depender de campos baseados em preço; "stale" ainda é utilizável — compare com priceAsOf. metricsInputs is None significa um pacote anterior à expansão das métricas. Os campos aparecem símbolo a símbolo conforme ele é reenviado, então a cobertura é irregular por um tempo: trate cada bloco acima como opcional.

Convenções de tipo para os blocos de métricas

Cada métrica pode ser nula de forma independente. Um objeto de período é omitido por completo quando todas as suas chaves que não são metadados são nulas. Um bloco é {"quarterly": {}, "yearly": {}} quando vazio — nunca null, nunca omitido. NaN / Infinity nunca aparecem.

Informações da empresa

companyInfo é um objeto plano — não é indexado por data e não aparece nos snapshots current(...) / get_data_with_offset(...). Acesse-o diretamente:

---

Observações e armadilhas

• Sempre proteja contra None. Se os dados fundamentalistas não estiverem configurados, fundamentals é None. Dentro de um snapshot, seções individuais (por exemplo earnings.Trend, scores) também podem ser null em algumas barras, e os blocos da expansão das métricas podem faltar por completo em pacotes mais antigos.
• Sempre passe symbol= em execuções com vários símbolos e Screener — o recurso do pacote principal pode não ser o ticker em que você está.
• Números podem ser strings. O JSON subjacente costuma enviar as métricas numéricas como strings; converta com float(...) ao fazer contas.
• A indexação do mais novo para o mais antigo vale para as tabelas indexadas por data e para as consultas por deslocamento — o índice 0 é o período elegível mais recente no horário da barra, 1 é o anterior, etc.
• O carimbo de tempo da barra é a fonte da verdade para saber qual relatório é o "atual" — passe bar["t"] (ou bar.t[0]) diretamente; você não precisa analisá-lo você mesmo.