Correlacionar séries
bcb_correlacaoCalcula a correlação estatística entre 2 a 5 séries temporais do BCB no MESMO período (dataInicial e dataFinal obrigatórias), par a par. Quando usar: para medir se dois indicadores se movem juntos (ex.: dólar e Selic, IPCA e IGP-M). Quando NÃO usar: para comparar a variação de cada série lado a lado use bcb_comparar; para uma série só use bcb_variacao. Métodos: pearson (padrão) mede relação LINEAR entre os valores; spearman mede relação MONÓTONA entre os postos e é o adequado quando a relação não é reta ou quando uma série fica parada em platôs (taxa de juros entre reuniões do Copom). Base: nivel (padrão) correlaciona os valores; variacao correlaciona a mudança percentual de um ponto para o outro — prefira variacao quando as duas séries têm tendência (preço, índice, estoque), porque o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo. Retorna: periodo, metodo, base, series, alinhamento (datas cruzadas, completas e parciais), pares (cada um com codigoA/codigoB, coeficiente entre -1 e 1, n, descartados e interpretacao em prosa), erros e derivacao. Coeficiente que não pode ser calculado vem null com motivo — nunca 0, que significaria ausência medida de relação. Periodicidades diferentes são RECUSADAS, não avisadas: cruzar uma série diária com uma mensal por data casa só as datas coincidentes (cerca de 7 por ano) e produziria um coeficiente sobre esse punhado; informe frequencia para harmonizar todas na mesma grade antes de correlacionar. Correlação não estabelece causalidade. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna isError: true com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em structuredContent (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | `nivel` correlaciona os valores; `variacao` correlaciona a mudança percentual de um ponto para o seguinte. Prefira `variacao` quando as duas séries têm tendência: o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo. | nivel |
| metodo | No | `pearson` mede relação linear entre os valores; `spearman` mede relação monótona entre os postos (com posto médio nos empates) e é o adequado quando a relação não é reta ou quando uma das séries fica parada em platôs, como a Selic entre reuniões do Copom. | pearson |
| codigos | Yes | Array com 2 a 5 códigos de séries para correlacionar par a par | |
| agregacao | No | Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano. | ultimo |
| dataFinal | Yes | Data final (yyyy-MM-dd ou dd/MM/yyyy) | |
| frequencia | No | Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes. | |
| dataInicial | Yes | Data inicial (yyyy-MM-dd ou dd/MM/yyyy) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | Se o cálculo usou os valores ou as variações | |
| erros | Yes | Séries que não retornaram dados, com o motivo | |
| pares | Yes | Um item por par de séries | |
| metodo | Yes | Método aplicado | |
| series | Yes | Séries que entraram no cálculo | |
| periodo | Yes | Janela temporal correlacionada | |
| derivacao | Yes | Origem dos números calculados: o que é derivado, por qual motor e com quais convenções | |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença | |
| alinhamento | Yes | Como as grades foram cruzadas. `completas` é o que efetivamente entra num coeficiente: datas em que TODAS as séries publicam. A distância entre `datas` e `completas` é a medida de quanto as séries não se sobrepõem. | |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) | |
| harmonizacao | No | Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central. |