library(electionsBR)
electionsBR
is an R
package used to pull and clean Brazilian electoral data, directly from the Superior Electoral Court (TSE) website. Among others, electionsBR
retrieves data on electoral results, candidates' personal and professional backgrounds, parties' electoral performances, electoral coalitions, available seats under dispute, and voters' profile.
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")
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:
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)
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 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)
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)
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()
A character
vector with a list os party abbreviations, valid for 2016 elections, can be obtained with:
parties_br()
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)
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)
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.
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).
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()
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.
electionsBR
internal documentation is entirely based on the official documentation provided by the TSE in the Repositorio de Dados Eleitorais.^[To access the documentation for each type of electoral data, it is necessary to download and open the correspondent compressed files (.zip
).]
The electionsBR
package does not modify nor filter the data provided by the TSE -- despite its many problems.^[The only exceptions are the president_
and legislative_
functions, which aggregates electoral data in a different unit than in the original files.] 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.
To cite electionsBR
in publications, please use:
citation("electionsBR")
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.