electionsBR: versão 0.3.0

Ainda mais rápido, com mais opções para customizar resultados e novas funções

08 Jun 2017 por Fernando Meireles


O pacote do R para baixar e limpar dados eleitorais do TSE criado pelo Denisson Silva, Beatriz Costa e eu, o electionsBR, acaba de ganhar uma grande atualização, já disponível no CRAN: para a versão 0.3.0[1]. Para quem não o conhece, basicamente ele automatiza o trabalho de baixar, deszipar, tratar e limpar dados eleitorais brasileiros diretamente do Repositório de Dados Eleitorais do TSE – tudo acompanhado de extensa documentação baseada em informações oficiais. Em outras palavras, com ele é possível extrair quase todos os dados públicos de resultados eleitorais, apuração, partidos, coligações, candidaturas, de perfil dos eleitores, entre outros, diretamente pelo R, e isto em pouquíssimo tempo.

Nesta nova versão, estendemos as funcionalidades do pacote em vários pontos, mas sem comprometer a forma com que ele já funcionava. Segue, em forma de lista, as novidades do pacote.

Velocidade

O electionsBR já era extremamente rápido (em poucos segundos ele é capaz de baixar e processar centenas de milhares de informações do website do TSE), especialmente comparado à tarefa manual de baixar separadamente os arquivos do TSE, tratar e limpar cada um para, enfim, unir todos numa base única.

Nessa versão, melhoramos esse desempenho ainda mais: alteramos internamente as formas de leitura e união dos arquivos por meio das funções fread e rbindlist do pacote data.table. Com isso, o pacote ficou cerca de 6x mais rápido do que já era.

Resultados por estado

Anteriormente, só era possível pegar dados eleitorais para todo o Brasil com o pacote – o que significa que, caso desejássemos ter resultados apenas para um ou mais estados, teríamos que extrair dados do país todo para, aí sim, filtrar as informações.

Agora, a maioria das funções possui um argumento opcional chamado uf, que serve para indicar estados para os quais queremos dados – e isto de forma eficiente, sem ter de processar informações dos demais estados. Para pegar dados sobre as candidaturas (nome, sexo, partido, número de urna, profissão, entre outros, dos[as] candidatos[as]) nas eleições federais de 2010 apenas em Minas Gerais, por exemplo, podemos fazer isso:

# Instala a nova versão do pacote 
# (é preciso descomentar a linha abaixo)
# install.packages("electionsBR")

# Carrega o pacote
library(electionsBR)

# Pega dados de candidaturas em 2010 apenas para Minas Gerais
mg2010 <- candidate_fed(2010, uf = "MG")

# Um panorama dos dados
mg2010
## # A tibble: 1,789 × 43
##    DATA_GERACAO HORA_GERACAO ANO_ELEICAO NUM_TURNO DESCRICAO_ELEICAO
##           <chr>        <chr>       <chr>     <chr>             <chr>
## 1    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 2    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 3    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 4    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 5    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 6    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 7    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 8    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 9    19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## 10   19/02/2016     19:56:37        2010         1     ELEIÇÕES 2010
## # ... with 1,779 more rows, and 38 more variables: SIGLA_UF <chr>,
## #   SIGLA_UE <chr>, DESCRICAO_UE <chr>, CODIGO_CARGO <chr>,
## #   DESCRICAO_CARGO <chr>, NOME_CANDIDATO <chr>,
## #   SEQUENCIAL_CANDIDATO <chr>, NUMERO_CANDIDATO <chr>,
## #   CPF_CANDIDATO <chr>, NOME_URNA_CANDIDATO <chr>,
## #   COD_SITUACAO_CANDIDATURA <chr>, DES_SITUACAO_CANDIDATURA <chr>,
## #   NUMERO_PARTIDO <chr>, SIGLA_PARTIDO <chr>, NOME_PARTIDO <chr>,
## #   CODIGO_LEGENDA <chr>, SIGLA_LEGENDA <chr>, COMPOSICAO_LEGENDA <chr>,
## #   NOME_COLIGACAO <chr>, CODIGO_OCUPACAO <chr>, DESCRICAO_OCUPACAO <chr>,
## #   DATA_NASCIMENTO <chr>, NUM_TITULO_ELEITORAL_CANDIDATO <chr>,
## #   IDADE_DATA_ELEICAO <chr>, CODIGO_SEXO <chr>, DESCRICAO_SEXO <chr>,
## #   COD_GRAU_INSTRUCAO <chr>, DESCRICAO_GRAU_INSTRUCAO <chr>,
## #   CODIGO_ESTADO_CIVIL <chr>, DESCRICAO_ESTADO_CIVIL <chr>,
## #   CODIGO_NACIONALIDADE <chr>, DESCRICAO_NACIONALIDADE <chr>,
## #   SIGLA_UF_NASCIMENTO <chr>, CODIGO_MUNICIPIO_NASCIMENTO <chr>,
## #   NOME_MUNICIPIO_NASCIMENTO <chr>, DESPESA_MAX_CAMPANHA <chr>,
## #   COD_SIT_TOT_TURNO <chr>, DESC_SIT_TOT_TURNO <chr>

Também é possível pegar dados de mais de um estado por vez passando um vetor para a função:

# Pega dados de estados da região sul
sul <- candidate_fed(2010, uf = c("RS", "SC", "PR"))

As siglas dos estados podem ser passadas em maiúsculo, minúsculo ou combinação dos dois: MG, mg, Mg ou mG são todos inputs igualmente válidos.

Percentual de votos

Para além das funções que o pacote já tinha (ver aqui uma descrição de todas as funções disponíveis), incluímos quatro funções para facilitar a extração de resultados eleitorais, que já retornam o percentual de votos válidos (nominais e de legenda somados) de cada partido nas eleições presidenciais, para o Senado e para a Câmara Federal agregados por estado ou por município. Estas funções são, respectivamente:

No caso das eleições legislativas, as funções aceitam um argumento opcional, house indicando a casa a ser analisada, se Senado ou Câmara (senate ou chamber).

Por exemplo, o código abaixo pega os resultados presidenciais do segundo turno de 2014 por estado:

pres <- president_state_vote(2010)

E o abaixo pega o total de votos percentuais de cada partido na disputa para a Câmara Federal em 2010, por estado:

cam <- legislative_state_vote(2010, house = "chamber")

Vagas em disputa

Também acrescentamos uma função para coletar dados sobre o número de cadeira para cada cargo em disputa (seats_fed, para eleições federais, e seats_local, para eleições municipais). Para saber quantas vagas nas Câmara municipais estavam disponíveis em cada município em 2016, por exemplo, use:

vagas <- seats_local(2016)

Exportar dados para Stata e SPSS

Para quem não usa, ou não tem tanta familiaridade com o R, incluímos uma opção para exportar os dados pegos pelas funções do pacote para arquivos .dta e .sav, que podem ser analisados pelo Stata e pelo SPSS, respectivamente. O argumento opcional para fazer isso é o export, que, por padrão, é igual a FALSE. Para exportar os resultados das funções, é só passar ele para TRUE:

# Resultados eleitorais federais de 2010, agregados por zona eleitoral
df <- vote_mun_zone_fed(2010, export = TRUE)

# Resultados eleitorais municipais de 2012, agregados por zona eleitoral
df2 <- vote_mun_zone_local(2012, export = TRUE)

Siglas de estados e partidos

Para consultar uma lista de siglas de estados e partidos, que pode ser útil para filtrar resultados, use:

# Sigla dos estados brasileiros
uf_br()
##  [1] "AC" "AL" "AM" "AP" "BA" "CE" "DF" "ES" "GO" "MA" "MG" "MS" "MT" "PA"
## [15] "PB" "PE" "PI" "PR" "RJ" "RN" "RO" "RR" "RS" "SC" "SE" "SP" "TO"
# Sigla dos partidos que disputaram a eleicao de 2016
parties_br()
##  [1] "PPS"     "PSB"     "PSOL"    "PP"      "PSL"     "PR"      "PSDB"   
##  [8] "PDT"     "PSDC"    "PHS"     "PT"      "PROS"    "PTC"     "PSC"    
## [15] "PC do B" "PRB"     "PMDB"    "DEM"     "PMB"     "PTB"     "PEN"    
## [22] "PTN"     "SD"      "PMN"     "PT do B" "PSD"     "PV"      "PRP"    
## [29] "REDE"    "PPL"     "PRTB"    "PSTU"    "PCB"     "PCO"     "NOVO"

Tutoriais

Para quem deseja ver um tutorial mais completo do funcionamento do electionsBR, adicionamos uma vignette ao pacote, que pode ser visto em:

Na mesma página, também existem outros tutoriais sobre em inglês e em português.

Website

Por fim, em vez de ter toda a documentação espalhada por aí, reunimos tudo num único website, que agora é também o site oficial do projeto.

[1] Para instalar a nova versão, basta abrir o R e executar no console o seguinte código: install.packages("electionsBR").


« electionsBR: uma nova versão (0.2.0)
genderBR: predizendo sexo a partir de nomes próprios »