Vesper Election Intel

Pipeline de geointeligência eleitoral para eleições municipais brasileiras. Alvo: Maricá / RJ (TSE code 58530) | Fonte: basedosdados via Google BigQuery

Pipeline

 BigQuery (TSE)
      │
      ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  EXTRACTION │────▶│   CLEANING  │────▶│   PIVOTING  │
│  extractor  │     │  processor  │     │  processor  │
│             │     │             │     │             │
│ basedosdados│     │ dtype opt.  │     │ seções ×    │
│ 2x LEFT JOIN│     │ feat. eng.  │     │ candidatos  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                         ┌─────────────────────▼──────┐
                         │        CLUSTERING          │
                         │        clustering          │
                         │                            │
                         │  StandardScaler → K-Means  │
                         │  Silhouette Score          │
                         └─────────────┬──────────────┘
                                       │
                         ┌─────────────▼──────────────┐
                         │         GEOCODING          │
                         │         geocoder           │
                         │                            │
                         │  Nominatim + disk cache    │
                         │  endereço → lat/lon        │
                         └─────────────┬──────────────┘
                                       │
                         ┌─────────────▼──────────────┐
                         │       VISUALIZATION        │
                         │        visualizer          │
                         │                            │
                         │  Folium + Leaflet.heat     │
                         │  Intel Report HTML         │
                         └────────────────────────────┘
                                       │
                              orquestrado por
                           pipeline.py (Typer CLI)

Estrutura do Projeto

vesper_election_intel/
├── vesper_intel/
│   ├── __init__.py
│   ├── config.py        ← constantes, BigQueryConfig, SQL template
│   ├── extractor.py     ← extração via basedosdados / BigQuery
│   ├── processor.py     ← limpeza Pandas, engenharia de features, pivot
│   ├── clustering.py    ← pipeline scikit-learn K-Means
│   ├── geocoder.py      ← geocodificação Nominatim com cache em disco
│   ├── visualizer.py    ← Folium Intel Report unificado
│   └── pipeline.py      ← orquestrador CLI (Typer)
├── outputs/             ← HTML gerados pelo pipeline
├── requirements.txt
├── .env
└── README.md

Setup

# 1. Instale as dependências
pip install -r requirements.txt

# 2. Autentique com o GCP
gcloud auth application-default login

# 3. Configure o ambiente
echo "GCP_PROJECT_ID=seu-projeto" > .env

# 4. Execute o pipeline
python -m vesper_intel.pipeline \
    --project seu-projeto-gcp \
    --candidate "NOME DO CANDIDATO" \
    --ano 2022 \
    --turno 1 \
    --k 5

CLI Options

Flag	Descrição	Padrão
--project / -p	GCP billing project ID	$GCP_PROJECT_ID
--candidate / -c	Nome do candidato para o heatmap	obrigatório
--ano / -a	Ano da eleição (2022 ou 2024)	2024
--turno / -t	Turno (1 ou 2)	1
--k	Número de clusters K-Means	5
--sweep-k	Executa sweep de silhouette para encontrar k ideal	False
--max-geocode	Limita geocodificação a N endereços (dev/teste)	None

Output

O pipeline salva em outputs/:

intel_report_marica_<ANO>_T<TURNO>.html

Arquivo HTML autocontido (CSS, JS e dados embutidos). Abra direto no navegador.

Componentes do Intel Report

• Sidebar — KPIs: total de votos, dominância percentual média, seções vencidas
• Heatmap — intensidade de votos do candidato no espaço urbano (Leaflet.heat)
• Marcadores — seções coloridas por cluster K-Means; popup com votos por candidato
• Controle de camadas — alterna entre Heatmap e Marcadores

BigQuery Tables

Tabela	Finalidade
basedosdados.br_tse_eleicoes.resultados_candidato_secao	Votos por seção e candidato
basedosdados.br_tse_eleicoes.perfil_eleitorado_local_votacao	Nome e endereço do local de votação
basedosdados.br_tse_eleicoes.candidatos	Número e nome oficial dos candidatos

Chave de JOIN: ano + turno + sigla_uf + id_municipio_tse + numero_zona + numero_secao

GitHub Pages (deploy do relatório)

git checkout --orphan gh-pages
cp outputs/intel_report_marica_2022_T1.html index.html
git add index.html
git commit -m "deploy: intel report 2022 T1"
git push origin gh-pages

Notes

• Queries BigQuery são cobradas ao seu projeto GCP. Para um município único, o custo típico é inferior a $0,01.
• Geocodificação usa OSM Nominatim (sem API key) com rate limit de 1 req/s e cache local em outputs/.geocode_cache.json.
• Anos suportados: 2022 e 2024 (configurado em config.py → TargetConfig.anos_eleicao).