Time Series Cross-Correlation

Projeto para o desenvolvimento de um algoritmo de análise de séries temporais por meio de correlação cruzada (cross-correlation), com o objetivo de subsidiar a discussão de resultados no Trabalho de Conclusão de Curso (TCC).

Objetivo

Investigar e implementar técnicas de correlação cruzada aplicadas a séries temporais, permitindo identificar relações de dependência, defasagens (lags) e padrões de similaridade entre diferentes sinais/séries ao longo do tempo. Os resultados obtidos servirão como base experimental para a análise e discussão apresentadas no TCC.

Status

🚧 Release 6 em desenvolvimento — correlação das tendências (média móvel e STL) dos 10 pregões na janela 10:00–17:00 com Informação Mútua, ρDCCA e MF-DCCA (ver docs/ARCHITECTURE.pt-BR.md §9 e ADR 0008). A Release 5 (Informação Mútua, ρDCCA e MF-DCCA — ADR 0007), a Release 4 (decomposição de tendência por média móvel e STL — ADR 0006), a Release 3 (CCF com varredura de lags — ADR 0005), a Release 2 (correlação cruzada par a par com Pearson/Spearman, matriz $\mathbf{V}$, p-valor, estabilidade entre sub-janelas e mapa de calor — ADR 0004) e a Release 1 (Captura → Pré-processamento → Armazenamento) já estão em main. Integração com o dashboard fica para releases seguintes.

Requisitos

• Python 3.14.7
• pip install -r requirements.txt (dev: requirements-dev.txt)

Arquitetura e contratos

• docs/ARCHITECTURE.pt-BR.md — pipeline em camadas
• docs/CONTRACTS.pt-BR.md — contrato OHLC (servidor qData_service x cliente)
• docs/adr/ — decisões arquiteturais

Como executar

Configuração versionada em config/pipeline.yaml; segredos em .env (ver .env.example).

# 1x: gera o fixture sintético offline em data/raw/ (semente fixa)
python scripts/gen_fixture.py

# pipeline completo offline (captura → ... → análise)
python main.py --offline

# só recalcular a correlação sobre os candles já armazenados
python main.py --analysis-only

# execução contra o qData_service (requer credenciais em .env)
python main.py

Saídas: data/interim/current_day.parquet (dia corrente, mutável), data/processed/candles/date=.../ (dias fechados, imutáveis), data/processed/pairs/d_i=.../ (estrutura de defasagens), data/processed/correlations/method=<m>/{pairs,matrix}.parquet + heatmap_<m>.png, e data/processed/manifest.yaml.

Uma amostragem executada de exemplo (com heatmap e REPORT.md) fica em samples/ — corrida contra o qData_service via config/sample.yaml (python scripts/make_sample.py, requer credenciais em .env). A decomposição de um pregão (bruto × tendência/sazonal/resíduo) é plotada sobre os candles da amostragem com python scripts/plot_decomposition.py. A amostragem das tendências usa outra configuração e destino: python scripts/make_sample.py --config config/sample-trend.yaml --dest samples/win-10d-trend.

Testes

pytest

Licença

Este projeto é de caráter acadêmico, desenvolvido no contexto de um Trabalho de Conclusão de Curso (TCC).