Dados eleitorais com o electionsBR

8 anos de pacote e uma atualização

R
Eleições
TSE
Author

Fernando Meireles

Published

December 16, 2024



Depois de um relativamente longo período sem atualizações, acabamos, Denisson e eu, de lançar a versão 0.5.0 do electionsBR, nosso pacote em R criado para facilitar o acesso estruturado a dados eleitorais brasileiros. Muitas coisas mudaram nele com essa atualização – mas, talvez a mais importante, é que ela marca 8 anos de existência do pacote, período no qual ele foi baixado mais de 45 mil vezes.

A seguir, um resumo do que mudou de lá para cá.

A razão do pacote

O electionsBR tem um único objetivo: facilitar o acesso a dados eleitorais do Tribunal Superior Eleitoral (TSE).

Quando Denisson e eu o criamos, em novembro de 2016, o TSE disponibilizava informações de resultados eleitorais, candidaturas registradas, coligações, entre outros, de forma fragmentada em arquivos cujas formatações não raro geravam problemas de importação.

O electionsBR foi a nossa tentativa de solucionar o problema. Com ele, criamos uma interface amigável, via R, que permitia a qualquer pessoa obter, em segundos, dados de uma eleição inteira de forma estruturada, contornando problemas de importação. Mesmo para quem não usa R, basta digitar duas linhas de código para ter os dados desejados em uma planilha ou arquivo para leitura no SPSS ou Stata.

Nos últimos anos, nosso trabalho de manutenção do pacote, no entanto, diminuiu. O TSE passou a disponibilizar os dados de forma mais amigável, em arquivos CSV com cabeçalhos, além de ter criado uma excelente página de Dados Abertos.

Paralelamente, a louvável iniciativa do Cepesp Data, da FGV, passou não apenas a oferecer os mesmos dados em uma interface versátil como, também, a consolidá-los e a enriquecê-los com outras informações. A plataforma dispensa a consulta aos dados do próprio TSE em vários casos.

A atualização

Se há alternativas, por que atualizar o electionsBR? Simples: ele ainda é útil para muitas pessoas – principalmente para nós mesmos.

Indo além, integramos também a API do Cepesp Data ao pacote, o que desbloqueia a possibilidade de obter dados consolidados e enriquecidos de outra fonte. Com essa atualização, portanto, o electionsBR vira uma interface unificada para obtenção de dados eleitorais brasileiros diretamente do R.

Outra novidade, disponível desde a última atualização, é simplificação de código: com apenas duas funções é possível acessar qualquer dado eleitoral. A divisão funciona por fonte dos dados: elections_tse() para dados do TSE e elections_cepesp() para dados do Cepesp Data.

Duas principais funções do novo electionsBR
Função Argumentos principais Descrição
elections_tse() year, type Dados diretamente do TSE
elections_cepesp() year, type, position Dados da API do Cepesp Data

Usando o electionsBR

O pacote está disponível no CRAN e pode ser instalado e carregado com as seguintes linhas:

install.packages("electionsBR")
library(electionsBR)

Com isso feito, é possível usar uma das duas principais funções para, por exemplo, obter informações das candidaturas registradas para concorrer na eleição de 2018:

cands <- elections_tse(year = 2018, type = "candidate")

Para baixar os resultados eleitorais na mesma eleição agregados por município e por zona eleitoral (nível de agregação padrão do TSE), basta modificar o argumento type:

votos <- elections_tse(year = 2018, type = "vote_mun_zone")

E para baixar dados do Cepesp Data? Basicamente a mesma coisa:

cands_cepesp <- elections_cepesp(year = 2018, type = "candidate", position = "President")

A diferença aqui é que, além de indicar o tipo de informação desejada, é preciso informar o cargo em disputa. A tabela a seguir mostra os tipos de dados disponíveis para cada fonte e, para o caso do Cepesp Data, os cargos disponíveis:

Tipo (type) Dados
candidate Candidaturas
vote_mun_zone Votos
details_mun_zone Apuração eleitoral
legends Partidos
party_mun_zone Votos por partido
personal_finances Declarações de bens pessoais dos candidatos
seats Número de vagas em disputa
vote_section Votos por seção eleitoral
voter_profile_by_section Perfil do eleitorado por seção
voter_profile Perfil do eleitorado
social_media Links das redes sociais dos candidatos
Tipo (type) Posição (position) Dados
candidate President, Governor, Senator, Federal Deputy, State Deputy, District Deputy, Mayor, Councillor Candidaturas
vote President, Governor, Senator, Federal Deputy, State Deputy, District Deputy, Mayor, Councillor Votos

Um exemplo: mapas

Passadas as eleições, mapas eleitorais pipocam em todo lugar. Graças a um excelente pacote chamado geobr, é extremamente simples criar esse tipo de visualização.1 Um exemplo: qual foi o percentual de vereadores e vereadoras eleitos pelo Partido dos Trabalhadores (PT) em cada município brasileiro no pleito de 2024?

O TSE disponibiliza uma tabela com várias informações sobre candidaturas, incluindo seus resultados na totalização dos votos (i.e., se foram ou não eleitos e eleitas). Com o electionsBR, basta usar elections_tse() com type = "candidate" para obter esses dados:

# Carrega pacotes
if (!require(pacman)) install.packages("pacman")
pacman::p_load("electionsBR", "tidyverse", "geobr")

# Baixa os dados
eleitos <- elections_tse(year = 2024, type = "candidate")

As variáveis que nos interessam são essas:

eleitos %>%
    select(NM_UE, SG_UE, SG_PARTIDO, DS_CARGO, DS_SIT_TOT_TURNO)
# A tibble: 463,598 × 5
  NM_UE                SG_UE SG_PARTIDO DS_CARGO DS_SIT_TOT_TURNO
  <chr>                <chr> <chr>      <chr>    <chr>           
1 MARECHAL THAUMATURGO 01040 PV         VEREADOR SUPLENTE        
2 RODRIGUES ALVES      01082 PC do B    VEREADOR NÃO ELEITO      
3 XAPURI               01490 PT         VEREADOR #NULO#          
4 SENA MADUREIRA       01457 PP         VEREADOR SUPLENTE        
5 PORTO ACRE           01023 PSDB       VEREADOR NÃO ELEITO      
# ℹ 463,593 more rows

Com elas, conseguimos saber, para cada município, o percentual de vereadores e vereadoras eleitos e eleitas pelo PT (claro, usando algumas funções antes):

eleitos_pt <- eleitos %>%
    filter(NR_TURNO == 1) %>%
    filter(DS_CARGO == "VEREADOR") %>%
    filter(DS_SIT_TOT_TURNO %in% c("ELEITO POR QP", "ELEITO POR MÉDIA")) %>%
    mutate(SG_UE = as.numeric(SG_UE)) %>%
    group_by(NM_UE, SG_UE) %>%
    summarise(pct_vereadores_pt = sum(SG_PARTIDO == "PT") / n()) %>%
    arrange(desc(pct_vereadores_pt))

eleitos_pt
# A tibble: 5,537 × 3
# Groups:   NM_UE [5,266]
  NM_UE           SG_UE pct_vereadores_pt
  <chr>           <dbl>             <dbl>
1 ANÍSIO DE ABREU 10138             1    
2 BREJO DO PIAUÍ  10642             1    
3 IPAPORANGA      13340             1    
4 URUOCA          15792             0.889
5 COCAL DOS ALVES 12696             0.778
# ℹ 5,532 more rows

O geobr tem uma função read_municipality() que retorna um sf com os municípios brasileiros.2 O que é isso? Basicamente, um data.frame com as informações geográficas necessárias para desenharmos polígonos em R, isto é, um mapa.

municipios <- geobr::read_municipality(showProgress = FALSE)

Um problema: o código utilizado para identificar cada município nas bases do TSE é diferente do código utilizado pelo geobr, que adota os identificadores do IBGE. Se tivermos um arquivo de correspondência entre os dois códigos, podemos fazer a junção dos dados. Aqui:

codigos <- read_csv("https://github.com/betafcc/Municipios-Brasileiros-TSE/raw/refs/heads/master/municipios_brasileiros_tse.csv") %>%
  select(SG_UE = codigo_tse, code_muni = codigo_ibge)

df <- municipios %>%
  left_join(codigos, by = "code_muni") %>%
  left_join(eleitos_pt, by = "SG_UE")

Finalmente, o mapa:

df %>%
  ggplot(aes(fill = pct_vereadores_pt)) +
  geom_sf(color = "white", linewidth = 0.05) +
  scale_fill_gradientn(colors = c("#eae2b7", "#e09f3e", "#9e2a2b", "#540b0e"), 
                       na.value = "#faf0ca", guide = guide_colorsteps(barheight = 0.3),
                       label = scales::percent) +
  theme_void() +
  theme(legend.position = "bottom",
        legend.key.width = unit(12, "mm")) +
  labs(fill = NULL)

Percentual de vereadores e vereadoras eleitos pelo PT em 2024

Há nitidamente um vazio em boa parte do território, o que pode ser lido como a extensão territorial sem representates do PT. A exceção é parte do Nordeste, área de sertão, onde o partido tem maior presença e também boa votação em eleições presidenciais. O contraste com a bancada de vereadores e vereadoras eleitos pelo PL, do ex-Presidente Jair Bolsonaro, é grande (mas vale o alerta de que território não vota):

Percentual de vereadores e vereadoras eleitos pelo PL em 2024

Compatibilidade

Na versão atual do electionsBR, todas as funções terminadas com o sufixo _fed ou _local (e.g., vote_mun_zone_local) foram substituídas por elections_tse(). Vale dizer, elas ainda estão disponíveis no pacote, mas serão removidas em futuras atualizações (ao usá-las, você deverá receber um aviso de que a função está deprecated). Com o passar do tempo, nossa ideia é simplificar ao máximo a interface do pacote, o que também nos ajudará a fazer manutenção do código.

Citação

Pretende usar o pacote em uma pesquisa ou artigo acadêmico? Se o electionsBR foi útil para você, para nós seria ótimo vê-lo citado no seu trabalho – é a nossa forma de ter esse projeto paralelo reconhecido e valorizado. As referências bibliográficas do pacote são encontradas assim, no próprio R:

citation("electionsBR")
Para citar o pacote 'electionsBR' em publicações use:

  Meireles, Fernando; Silva, Denisson; Costa, Beatriz. (2016).
  electionsBR: R functions to download and clean Brazilian electoral
  data. URL: http://electionsbr.com/novo/

Uma entrada BibTeX para usuários(as) de LaTeX é

  @Manual{,
    title = {{electionsBR}: {R} Functions to Download and Clean {B}razilian Electoral Data},
    author = {Fernando Meireles and Denisson Silva and Beatriz Costa},
    year = {2016},
    url = {http://electionsbr.com/novo/},
    encoding = {UTF-8},
  }

Footnotes

  1. Há outro pacote que facilita a criação de mapas em R, o simplefeaturesbr. Vale conferir.↩︎

  2. Para uma introdução detalhada ao pacote, que obviamente passa longe daqui, ver este link.↩︎