Introduction to the electionsBR package

Fernando Meireles, Denisson Silva, Beatriz Costa

2024-02-05

Thanks to the Superior Electoral Court (TSE), any person with an internet connection can access a wide range of Brazil’s electoral data. However, the TSE website used to lack a user-friendly interface, and the data was not available in a tidy format until very recently, which made it difficult to use these data in R for research purposes. In a nutshell, this was our main motivation to develop the electionsBR, an R package specifically designed to retrieve and clean Brazilian electoral data directly from the TSE website, making it easy and fast to obtain electoral data in a tidy format.

At its core, electionsBR provides a comprehensive set of functions that download and clean various types of information using modern backends available in R to handle data retrieving, importing, and transforming. With this, users can access data that includes candidates’ personal and professional backgrounds, parties’ electoral performances, electoral coalitions, available seats under dispute, and voters’ profiles.

In what follows, we provide a brief overview of the package’s main features. For a complete list of functions, see the package’s reference manual.

How to install

Since version 0.1.1, the easiest way to install electionsBR is to use the install.packages function:

install.packages("electionsBR")

Frequently, however, the CRAN version is not the most recent one. In these cases, pre-release versions from GitHub, you can use the following command:

if (!require("devtools")) install.packages("devtools")
devtools::install_github("silvadenisson/electionsBR")

Usage

No previous experience with R is required to use the electionsBR package. In fact, it only takes two lines of code to download, clean, and export Brazilian electoral data in Stata and SPSS formats. For example, you can easily obtain a complete and tidy dataset with candidates’ background information for the 2010 Federal election using the following code:

install.packages("electionsBR")
electionsBR::elections_tse(year = 2010, type = "candidate", export = TRUE)

By setting the export argument to TRUE in the elections_tse function, the package will download and clean the relevant data directly from the TSE website and save it in the R working directory (the function automatically tells the user where this directory is located) in two different files:

  1. electoral_data.dta, to be used with Stata;
  2. electoral_data.sav, to be used with SPSS.

Different types of electoral data

electionsBR’s chief function, elections_tse, contains the argument type (character), which controls the type of electoral data to be retrieved. The possible values for type are:

Using the type argument, to download electoral results for 2014 federal elections, for example, you can use:

# Download electoral results for 2014 federal elections
df <- elections_tse(year = 2014, type = "vote_mun_zone")

CEPESP Data Integration

The package also provides an alternative API for downloading data from the CEPESP Data project, including information on candidates, electoral results, and voters’ profiles. To download data on candidates in the 2018 presidential election, simply use the following code:

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

Other functionality

The electionsBR package also includes additional functionality that may be useful for users. For example, the uf_br function returns a character vector with a list of state abbreviations:

uf_br()

To obtain a list of party abbreviations, use:

parties_br(year)

In recent years, the TSE has made available data on presidential elections in separate files (indicated by the BR or _BR suffix). To download these files, use the br_archive argument as follows:

# Download electoral results for 2014 federal elections
df <- elections_tse(year = 2014, type = "vote_mun_zone", br_archive = TRUE)

To obtain the TSE’s official README files that describe the variables in each type of electoral data, make sure to set readme_pdf to TRUE:

# Download candidates' social media information for 2022 elections
df <- elections_tse(year = 2014, type = "social_media", readme_pdf = TRUE)

Exporting Brazilian electoral data

Most electionsBR’s functions accept an export argument (logical, must be TRUE or FALSE; defaults to the latter) that controls whether the functions should export the retrieved data to Stata and SPSS files or not.

df <- elections_tse(2010, export = TRUE)

Removing UTF-8 special characters from texts

By default, electionsBR’s functions maintain original encoding (Latin-1) in special characters. To convert strings to ASCII, set the ascii argument to TRUE.

df <- elections_tse(2010, ascii = TRUE)

Using Mac OS, this option may cause errors (or may retrieve incomplete data for the 2016 elections). To avoid these issues, use the encoding optional argument as follows:

df <- elections_tse(2010, ascii = TRUE, encoding = "Latin-1")

encoding may also be set to UTF-8 or other valid encodings.

Filtering results by state

Sometimes, getting state electoral data, and not for the whole country, is what one needs. To achieve this, use the uf optional argument (available in most functions):

# Electoral results for the 2010 federal elections in Sao Paulo (SP)
df <- elections_tse(2010, uf = "SP")
http://www.tse.jus.br/eleicoes/estatisticas/repositorio-de-dados-eleitorais
# Electoral results for the 2010 federal elections in Minas Gerais (MS)
df <- elections_tse(2010, uf = "mg")

# Electoral results for the 2010 federal elections in RS, SC, and PR
df <- elections_tse(2010, uf = c("RS", "SC", "PR"))

Notice that the input must be a character vector – with case insensitive state abbreviations (MG, Mg, mG, and mg are all equally valid inputs).

How Elections in Brazil Work

All the data retrieved by electionsBR is made available online by the Brazilian Superior Electoral Court (TSE). As stated on the English version of the TSE website, elections in Brazil are organized in the following way:

Official documentation

The internal documentation of the electionsBR package is based entirely on the official documentation provided by the TSE in the Repositório de Dados Eleitorais. To access the documentation for each type of electoral data, set the readme_pdf argument in the elections_tse to TRUE and the package will save the relevant documentation in PDF format.

Disclaimer

The electionsBR package does not modify or filter the data provided by the TSE. Additionally, users must be aware that the TSE updates its databases frequently, so it is important to note the version of the electoral data used. However, we are not responsible for any issues with the data that users may encounter.

How to cite

To cite electionsBR in publications, please use:

citation("electionsBR")
## To cite package 'electionsBR' in publications use:
## 
##   Meireles, Fernando; Silva, Denisson; Costa, Beatriz. (2016).
##   electionsBR: R functions to download and clean Brazilian electoral
##   data. URL: http://electionsbr.com/
## 
## A BibTeX entry for LaTeX users is
## 
##   @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/},
##     encoding = {UTF-8},
##   }