Introduction to the electionsBR package

How to install

Since the version 0.1.1, electionsBR is on CRAN and can be installed with:

install.packages("electionsBR")

You can install these pre-release versions from GitHub with:

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

How to use

No previous experience with R is required to use the electionsBR package. In fact, it takes only two lines of code to download, clean and export (to Stata and SPSS formats) Brazilian electoral data. For example, here is how we get a full, cleaned dataset with electoral results for the 2010 Federal election:

install.packages("electionsBR")
electionsBR::vote_mun_zone_fed(2010, export = TRUE)

By setting the export argument to TRUE in the vote_mun_zone_fed 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:

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

Data on elections results

electionsBR‘s chief functions are the ones used to get electoral results, which includes candidates’ number of votes and electoral status (i.e., elected and non-elected), among many others. To get these data, use vote_mun_zone_ functions:

# Load the package
library(electionsBR)

# Use vote_mun_zone_fed function to download 2014 election results
df <- vote_mun_zone_fed(2014)

# Get results for the 2000 local elections
df <- vote_mun_zone_local(2000)

Federal elections results

There are also functions used to quickly access presidential and legislative elections results per state and per municipality – with vote proportions (i.e., vote share) reported. To get presidential runoff (second round) results in runoff, use president_ functions:

# Get presidential electoral results by municipality in tidy format
pres_mun <- president_mun_vote(2010, prop = TRUE)

# Get presidential electoral results by state in tidy format
pres_st <- president_state_vote(2010, prop = TRUE)

To get legislative election results, use instead:

legislative_mun_vote(year)
legislative_state_vote(year)

Data on running candidates

Data on candidates’ party affiliation, ballot number, backgrounds and personal information can be retrieved with candidate_ functions:

# Get data on candidates running in local elections
df <- candidate_local(2016)

# Get data on candidates running in federal elections
df <- candidate_fed(2016)

Data on parties and electoral coalitions

Parties’ electoral performances in both local and federal elections, for all electoral positions, are extracted with:

# Get data on parties' electoral performances in the federal election of 2006
federal <- party_mun_zone_fed(2006)

# Get data on parties' electoral performances in the local election of 2004
municipal <- party_mun_zone_local(2004)

To get the composition of electoral coalitions (common in proportional elections), use instead:

legend_fed(year)
legend_local(year)

Data on voters

To get data on voters’ profile in both local and federal elections, use the voter_profile function:

# Get data on voters' profile
voters02 <- voter_profile(2002)
voters04 <- voter_profile(2004)

Individual records of partisan affiliation are extracted with the voter_affiliation function:

# PT (Brazilian Workers' Party) in Distrito Federal (DF)
df <- voter_affiliation("PT", "DF")

# PSDB (Brazilian Social Democracy Party) in Sao Paulo (SP)
df <- voter_affiliation("PSDB", "SP")

# PT and PC do B (Brazilian Communist Party) in DF, MG and AL
df <- voter_affiliation(c("PT", "PC do B"), c("DF", "MG", "AL"))

To consult state abbreviations, use:

uf_br()

##  [1] "AC" "AL" "AM" "AP" "BA" "CE" "DF" "ES" "GO" "MA" "MG" "MS" "MT" "PA" "PB"
## [16] "PE" "PI" "PR" "RJ" "RN" "RO" "RR" "RS" "SC" "SE" "SP" "TO"

A character vector with a list os party abbreviations, valid for 2016 elections, can be obtained with:

parties_br()

##  [1] "AVANTE"         "CIDADANIA"      "DC"             "DEM"           
##  [5] "MDB"            "NOVO"           "PATRIOTA"       "PC do B"       
##  [9] "PCB"            "PCO"            "PDT"            "PEN"           
## [13] "PHS"            "PMB"            "PMN"            "PODE"          
## [17] "PP"             "PPL"            "PPS"            "PR"            
## [21] "PRB"            "PROS"           "PRP"            "PRTB"          
## [25] "PSB"            "PSC"            "PSD"            "PSDB"          
## [29] "PSDC"           "PSL"            "PSOL"           "PSTU"          
## [33] "PT"             "PT do B"        "PTB"            "PTC"           
## [37] "PTN"            "PV"             "REDE"           "REPUBLICANOS"  
## [41] "SD"             "SOLIEDARIEDADE" "UP"

Other functions

electionsBR also includes functions to download data on valid and residual votes and on the number of seats under dispute in each election. The relevant functions are, respectively:

details_mun_zone_fed(year)
details_mun_zone_local(year)

seats_fed(year)
seats_local(year)

Optional arguments

Exporting Brazilian electoral data

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

df <- party_mun_zone_fed(2010, export = TRUE)

Removing UTF-8 special characters from texts

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

df <- candidate_fed(2010, ascii = TRUE)

In Mac computers, this option may cause errors (or may retrieve incomplete data for the 2016 elections). To avoid them, you may use the encoding optional argument as follows:

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

encoding may also be 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 <- vote_mun_zone_fed(2010, uf = "SP")

# Electoral results for the 2010 federal elections in Minas Gerais (MS)
df <- vote_mun_zone_fed(2010, uf = "mg")

# Electoral results for the 2010 federal elections in RS, SC, and PR
df <- vote_mun_zone_fed(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).

A complete list of functions

candidate_fed()
candidate_local()
details_mun_zone_fed()
details_mun_zone_local()
legend_fed()
legend_local()
legislative_mun_vote()
legislative_state_vote()
parties_br()
party_mun_zone_fed()
party_mun_zone_local()
president_mun_vote()
president_state_vote()
seats_fed()
seats_local()
uf_br()
vote_mun_zone_fed()
vote_mun_zone_local()
voter_affiliation()
voter_profile()

Elections in Brazil

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

Are carried out together the federal elections and the state elections, for president and vice president, senator and alternates, governor and vice governor, federal deputies and state deputies. Two years later, will be municipal elections, of mayor and vice mayor and city councils. Note that the distinguishing criterion is by federal level and not by powers – the representatives from the executive and legislative are elected at the same time.

In case of elections for president and vice president, governor and vice governor, senator and alternates and mayor and vice mayor, the system used is the majoritary, in which the most voted candidate will be elected. If none of candidates for president, governor or mayor from a municipality over 200,000 habitants reach the absolute majority of the valid votes, will be convened the second round with the two most voted.

Now for the city council elections and state deputy and federal deputy, the criterion is proportional, which considers not only the candidate votes, but also his party’s votes. Hence, not always the best voted candidate will be elected. The filling of vacancies will depend on the performance of the whole group of candidates of the party or alliance.

Official documentation

electionsBR internal documentation is entirely based on the official documentation provided by the TSE in the Repositorio de Dados Eleitorais.¹

Disclaimer

The electionsBR package does not modify nor filter the data provided by the TSE – despite its many problems.² Additionally, users must be aware that the TSE updates its databases frequently, so it is important to register when a version of the electoral data is used. In any case, we are not responsible for problems with the data users may find.

How to cite

To cite electionsBR in publications, please use:

citation("electionsBR")

## 
## To cite electionsBR in publications, please 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/},
##   }

To access the documentation for each type of electoral data, it is necessary to download and open the correspondent compressed files (.zip).↩︎
The only exceptions are the president_ and legislative_ functions, which aggregates electoral data in a different unit than in the original files.↩︎