b3stats

B3 Stats — Sistema de Análise Estatística do Mercado Brasileiro

📊 Visão Geral

Dashboard interativo para análise de retornos históricos de ativos e índices da B3.
Lê automaticamente a planilha Excel, processa os dados e exibe estatísticas completas.

Ativos incluídos: IBOV, SMLL, ICON, IEEX, IFNC, IMAT, IMOB, MLCX, INDX, CCMFUT, BGIFUT, VALE3, PETR4, ITUB4
Cobertura: 1994–2026 | Total de registros: 3.413 observações mensais

---

🗂️ Estrutura do Projeto

mercado-stats/
├── b3stats.html              ← DASHBOARD STANDALONE (abre direto no navegador)
├── dados.json                ← Dados processados (gerado automaticamente)
├── dados_embed.json          ← Dados compactos (embutidos no HTML)
│
├── backend/
│   ├── main.py               ← API REST (FastAPI)
│   └── requirements.txt      ← Dependências Python
│
└── frontend/
    ├── index.html            ← Frontend SPA
    └── src/
        └── app.js            ← Lógica do frontend (com API)

---

🚀 Opção 1 — Modo Standalone (mais simples, sem servidor)

Abra diretamente no navegador:

# macOS
open b3stats.html

# Linux
xdg-open b3stats.html

# Windows
start b3stats.html

✅ Funciona offline. Todos os 3.413 registros estão embutidos no HTML.
Não precisa de Python, Node, servidor ou internet.

---

🖥️ Opção 2 — Modo com Backend (API REST + Frontend)

Pré-requisitos

• Python 3.11+
• pip

1. Instalar dependências

cd backend
pip install -r requirements.txt

2. Iniciar o servidor

# A partir da pasta raiz do projeto
uvicorn backend.main:app --reload --port 8000

O servidor estará disponível em: http://localhost:8000

Documentação interativa da API: http://localhost:8000/docs

3. Abrir o frontend

# Em outro terminal, sirva o frontend
cd frontend
python3 -m http.server 3000

Abra http://localhost:3000 no navegador.

---

📡 Endpoints da API

Método	Endpoint	Descrição
GET	/ativos	Lista todos os ativos disponíveis
GET	/dados?ativo=IBOV&mes=1	Série histórica filtrada
GET	/estatisticas?ativo=IBOV&mes=1	Estatísticas completas
GET	/heatmap?ativo=IBOV	Matriz ano × mês para heatmap
GET	/ranking?ativo=IBOV	Ranking dos meses por retorno médio
GET	/comparacao?ativos=IBOV,SMLL&mes=1	Comparação entre ativos

Parâmetros opcionais (GET /dados e /estatisticas)

Parâmetro	Tipo	Descrição
mes	int (1–12)	Filtrar por mês específico
ano_inicio	int	Ano inicial do período
ano_fim	int	Ano final do período
apenas_positivos	bool	Somente retornos > 0
apenas_negativos	bool	Somente retornos < 0
acima_da_media	bool	Somente retornos acima da média
abaixo_da_media	bool	Somente retornos abaixo da média

Exemplos de uso

# IBOV em Janeiro — todos os anos
curl "http://localhost:8000/estatisticas?ativo=IBOV&mes=1"

# PETR4 em Outubro 2010–2024, apenas meses positivos
curl "http://localhost:8000/dados?ativo=PETR4&mes=10&ano_inicio=2010&ano_fim=2024&apenas_positivos=true"

# Heatmap completo do IBOV
curl "http://localhost:8000/heatmap?ativo=IBOV"

# Ranking de meses do VALE3
curl "http://localhost:8000/ranking?ativo=VALE3"

# Comparação IBOV vs SMLL vs MLCX em Dezembro
curl "http://localhost:8000/comparacao?ativos=IBOV,SMLL,MLCX&mes=12"

---

📈 Funcionalidades

Estatísticas calculadas

• Média de retorno
• Mediana
• Desvio padrão
• Taxa de acerto (% de meses positivos)
• Maior alta e maior queda históricas
• Médias separadas para meses positivos/negativos
• Quartis (Q1, Q3) e IQR

Visualizações

• Histograma de distribuição dos retornos
• Série histórica (barras coloridas por sinal)
• Média por mês (barras comparativas)
• Heatmap interativo (ano × mês, escala de cor por intensidade)
• Ranking de meses com barra de performance
• Comparação multi-ativo com gráfico de linhas sobrepostas

Filtros disponíveis

• Seleção de ativo
• Seleção de mês (1–12 ou todos)
• Intervalo de anos (De/Até)
• Apenas positivos / negativos
• Acima / abaixo da média

---

🔧 Atualizar com nova planilha

Para incorporar uma nova versão da planilha Excel:

python3 << 'EOF'
import pandas as pd
import json

SHEETS = ['IBOV','SMLL','ICON','IEEX','IFNC','IMAT','IMOB','MLCX','INDX','CCMFUT','BGIFUT','VALE3','PETR4','ITUB4']
xl = pd.ExcelFile('sua_planilha.xlsx')

records = []
for sheet in SHEETS:
    if sheet not in xl.sheet_names:
        continue
    df = xl.parse(sheet, header=None)
    for _, row in df.iterrows():
        try:
            ano = int(float(str(row[0]).replace('.0','')))
        except:
            continue
        if not 1990 <= ano <= 2030:
            continue
        for m in range(1, 13):
            val = row[m] if m < len(row) else None
            if pd.notna(val) and isinstance(val, (int, float)):
                records.append([sheet, ano, m, round(float(val), 6)])

with open('dados_embed.json', 'w') as f:
    json.dump(records, f, separators=(',',':'))
print(f"✅ {len(records)} registros exportados")
EOF

Depois regenere o b3stats.html substituindo o conteúdo da variável RAW pelo novo JSON.

---

🛠️ Tecnologias

Camada	Tecnologia
Dados	Pandas, openpyxl
Backend	Python 3.11, FastAPI, Uvicorn
Frontend	HTML5, CSS3, JavaScript ES2022
Gráficos	Chart.js 4.4
Fontes	Google Fonts (Syne, DM Mono, Inter)
Banco	Dados em memória (DataFrame Pandas / JSON embutido)

---

📝 Notas técnicas

• Cache em memória: todos os dados são carregados na inicialização; sem I/O por requisição
• Dados embutidos: o modo standalone usa const RAW = [...] com 3.413 arrays no JS
• Processamento: cálculos estatísticos feitos em Python (backend) ou JS puro (standalone)
• CORS: habilitado para desenvolvimento local (allow_origins=["*"])
• Sem dependências de banco: SQLite/PostgreSQL opcionais; padrão é em memória

---

📄 Licença

Uso interno. Dados históricos da B3.