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:

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:

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:

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:

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.

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

Disclaimer

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.