##
## To cite electionsBR in publications, use: citation('electionsBR')## To learn more, visit: http://electionsbr.comelectionsBR 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:
You can install these pre-release versions from GitHub with:
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:
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:
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:
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:
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:
## [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"A character vector with a list os party abbreviations, valid for 2016 elections, can be obtained with:
## [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"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.
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.
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:
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.1
The electionsBR package does not modify nor filter the data provided by the TSE – despite its many problems.2 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:
##
## 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/},
## }