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.
Since version 0.1.1, the easiest way to install
electionsBR is to use the install.packages
function:
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:
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:
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:
vote_mun_zone: Downloads data on the verification,
disaggregated by cities and electoral zones.details_mun_zone: Downloads data on the details,
disaggregated by town and electoral zone.legends: Downloads data on the party denomination
(coalitions or parties), disaggregated by cities.party_mun_zone: Downloads data on the polls by parties,
disaggregated by cities and electoral zones.personal_finances: Downloads data on personal financial
disclosures. Each observation corresponds to a candidate’s
property.seats: Downloads data on the number of seats under
dispute in elections.vote_section: Downloads data on candidate electoral
results in elections in Brazil by electoral section.voter_profile_by_section: Downloads data on the voters’
profile by vote section.voter_profile: Downloads data on the voters’
profile.social_media: Downloads data on the candidates’ links
to social media in federal elections.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")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:
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:
To obtain a list of party abbreviations, use:
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)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.
By default, electionsBR’s functions maintain original
encoding (Latin-1) in special characters. To convert
strings to ASCII, set the ascii argument to
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:
encoding may also be set to UTF-8 or other
valid encodings.
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).
Federal elections and state elections are conducted simultaneously, including the election of the president and vice president, senators and alternates, governors and vice governors, federal deputies, and state deputies. Two years later, municipal elections are held for mayors, vice mayors, and city councils. It is important to note that the distinction is based on the federal level, not on the branches of government. The executive and legislative representatives are elected at the same time.
In the case of elections for president and vice president, governor and vice governor, senator and alternates, and mayor and vice mayor, the majoritarian system is used, where the candidate with the most votes is elected. If none of the candidates for president, governor, or mayor in a municipality with over 200,000 inhabitants reaches an absolute majority of valid votes, a second round will be held with the two most voted candidates.
For city council elections, state deputies, and federal deputies, the proportional criterion is used, which takes into account not only the votes received by the candidate but also the votes received by their party. Therefore, the candidate with the highest number of votes may not always be elected. The allocation of seats depends on the performance of the entire group of candidates from the party or alliance.
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.
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.
To cite electionsBR in publications, please use:
## 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/novo/
##
## 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/novo/},
## encoding = {UTF-8},
## }