R functions to download and clean Brazilian electoral Data

Description

electionsBR provides a set of tools to easily pull and clean several different Brazilian electoral data: election results; candidates' partisan affiliations, personal and professional backgrounds; Brazilian parties' electoral performances; composition of electoral coalitions; among many others.

Details

To learn more about electionsBR, check the package vignette and documentation.

Author(s)

Beatriz Costa (UFMG/Brazil) [ctb], Fernando Meireles (UFMG/Brazil) [author], Denisson Silva (UFMG/Brazil) [author]

See Also

Useful links:

• https://electionsbr.com/novo/

• Report bugs at https://github.com/silvadenisson/electionsBR/issues

Pipe operator

Description

Pipe operator

Usage

lhs %>% rhs

Download data on the candidates' backgrounds in elections

Description

candidate() downloads and aggregates data on the candidates' background who ran in elections in Brazil. The function returns a data.frame where each observation corresponds to a candidate.

Usage

candidate(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

candidate returns a tbl, data.frame with the following variables:

Note

For the elections prior to 2002, some information can be incomplete. For the 2014 and 2018 elections, more variables are available.

Examples

## Not run: 
df <- candidate(2002)

## End(Not run)

Downloads data on the candidates - Addtional information

Description

candidate_add_infor() downloads and aggregates data on the candidates' background who ran in elections in Brazil. The function returns a data.frame where each observation corresponds to a candidate.

Usage

candidate_add_infor(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

candidate_add_infor returns a tbl, data.frame with the following variables:

Note

For the elections prior to 2024.

Examples

## Not run: 
df <- candidate_add_infor(2024)

## End(Not run)

Download data on the candidates' background in federal elections

Description

candidate_fed() downloads and aggregates the data on the candidates' background who competed in the federal elections in Brazil. The function returns a data.frame where each observation corresponds to a candidate.

Usage

candidate_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

candidate_local() returns a data.frame

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, and 2022 elections, more variables are available.

Examples

## Not run: 
df <- candidate_fed(2000)

## End(Not run)

Download data on the candidates' background in local elections

Description

candidate_local() downloads and aggregates the data on the candidates' background who competed in the local elections in Brazil. The function returns a data.frame where each observation corresponds to a candidate.

Usage

candidate_local(year, uf = "all", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

candidate_local() returns a data.frame with the following variables:

Note

For the elections prior to 2000, some information can be incomplete.

Examples

## Not run: 
df <- candidate_local(2000)

## End(Not run)

Download data on the verification of federal elections in Brazil

Description

details_mun_zone() downloads and aggregates data on the verification of federal elections in Brazil, disaggregated by town and electoral zone. The function returns a data.frame where each observation corresponds to a town/zone.

Usage

details_mun_zone(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

details_mun_zone() returns a data.frame.

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, 2022 and 2024 elections, more variables are available.

Examples

## Not run: 
df <- details_mun_zone(2002)

## End(Not run)

Download data on the verification of federal elections in Brazil

Description

details_mun_zone_fed() downloads and aggregates data on the verification of federal elections in Brazil, disaggregated by town and electoral zone. The function returns a data.frame where each observation corresponds to a town/zone.

Usage

details_mun_zone_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

details_mun_zone_fed() returns a data.frame with the following variables:

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, and 2022 elections, more variables are available.

Examples

## Not run: 
df <- details_mun_zone_fed(2002)

## End(Not run)

Download data on the verification of local elections in Brazil

Description

details_mun_zone_local() downloads and aggregates the data on the verification of local elections in Brazil, disaggregated by electoral zone. The function returns a data.frame where each observation corresponds to a town/zone.

Usage

details_mun_zone_local(year, uf = "all", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

details_mun_zone_local() returns a data.frame with the following variables:

Note

For the elections prior to 2000, some information can be incomplete.

Examples

## Not run: 
df <- details_mun_zone_local(2000)

## End(Not run)

Retrieve electoral data from the cepesp API.

Description

Retrieve electoral data from the cepesp API.

Usage

elections_cepesp(year, type, position, data_table = FALSE)

Arguments

Value

The function returns a tibble containing the requested elections data.

Note

The function is a wrapper for the cepesp API. To learn more about the API, please visit cepespdata.io.

Examples

## Not run: 
df <- elections_cepesp(2018, type = "candidate", position = "President")

## End(Not run)

Download data on the candidates' background in local elections

Description

Download data on the candidates' background in local elections

Usage

elections_rda(year, level = "fed", archive = "candidate")

Arguments

Examples

## Not run: 
df <- elections_rda(2018)

## End(Not run)

Function for downloading electoral data from the TSE repository

Description

The elections_tse() function is a wrapper that allows users to download and clean electoral data from Brazil's TSE repository. This function provides data on candidates, electoral results, personal finances, and other election-related information from 1998 to 2024. The returned data.frame contains observations corresponding to candidates, cities, or electoral zones.

Usage

elections_tse(
  year,
  type,
  uf = "all",
  br_archive = FALSE,
  ascii = FALSE,
  encoding = "latin1",
  export = FALSE,
  temp = TRUE,
  data_table = FALSE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

The elections_tse() function returns a data.frame with the requested electoral data.

elections_tse() returns a data.frame with the following variables:

Note

For elections prior to 2002, some information may be incomplete. For the 2014 and 2018 elections, additional columns are available. It is also important to note that in recent years, the TSE has changed the format of some data files, using CSV format with a header.

Examples

## Not run: 
# Download data on the candidates in the 2002 elections
cands <- elections_tse(2002, type = "candidate")

## End(Not run)

Download data on federal election coalitions in Brazil

Description

legend_fed() downloads and aggregates the data on the party denomination (coalitions or parties) from the federal elections in Brazil, disaggregated bi cities. The function returns a data.frame where each observation corresponds to a city.

Usage

legend_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

legend_fed() returns a data.frame.

Note

For elections prior to 2002, some information can be incomplete.

Examples

## Not run: 
df <- legend_fed(2002)

## End(Not run)

Download data on local election coalitions in Brazil

Description

legend_local() downloads and aggregates the party denominations (coalitions or parties) from the local elections in Brazil, disaggregated by cities. The function returns a data.frame where each observation corresponds to a city.

Usage

legend_local(year, uf = "all", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

legend_local() returns a data.frame.

Examples

## Not run: 
df <- legend_local(2000)

## End(Not run)

Download data on federal election coalitions in Brazil

Description

legends() downloads and aggregates the data on the party denomination (coalitions or parties) from the federal elections in Brazil, disaggregated bi cities. The function returns a data.frame where each observation corresponds to a city.

Usage

legends(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

legend_fed() returns a data.frame.

Note

For elections prior to 2002, some information can be incomplete.

Examples

## Not run: 
df <- legends(2002)

## End(Not run)

Returns a vector with the abbreviations of all Brazilian parties

Description

The character vector includes only parties that ran in elections from 1994 to 2022.

Usage

parties_br(year)

Arguments

Examples

## Not run: 
parties_election2002 <- parties_br(2002)

## End(Not run)

Download data on the polls by parties from federal elections in Brazil

Description

party_mun_zone() downloads and aggregates the data on the polls by parties from the federal elections in Brazil, disaggregated by cities and electoral zones. The function returns a data.frame where each observation corresponds to a city/zone.

Usage

party_mun_zone(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

party_mun_zone() returns a data.frame.

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, and 2022 elections, more variable are available.

Examples

## Not run: 
df <- party_mun_zone(2002)

## End(Not run)

Download data on the polls by parties from federal elections in Brazil

Description

party_mun_zone_fed() downloads and aggregates the data on the polls by parties from the federal elections in Brazil, disaggregated by cities and electoral zones. The function returns a data.frame where each observation corresponds to a city/zone.

Usage

party_mun_zone_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

party_mun_zone_fed() returns a data.frame.

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, and 2022 elections, more variable are available.

Examples

## Not run: 
df <- party_mun_zone_fed(2002)

## End(Not run)

Download data on the polls by parties from local elections in Brazil

Description

party_mun_zone_local() downloads and aggregates data on the polls by parties from local elections in Brazil, disaggregated by electoral zone. The function returns a data.frame where each observation corresponds to a city/zone.

Usage

party_mun_zone_local(year, uf = "all", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

party_mun_zone_local() returns a data.frame.

Note

For the elections prior to 2000, some information can be incomplete.

Examples

## Not run: 
df <- party_mun_zone_local(2000)

## End(Not run)

Download data on federal candidates' personal financial disclosures

Description

personal_finances() downloads and aggregates the data on federal candidates' personal financial disclosures. The function returns a data.frame where each observation corresponds to a candidate's property.

Usage

personal_finances(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

personal_finances() returns a data.frame.

Note

For the elections prior to 2000, some information may be incomplete.

Examples

## Not run: 
df <- personal_finances(2006)

## End(Not run)

Download data on federal candidates' personal financial disclosures

Description

personal_finances_local() downloads and aggregates the data on federal candidates' personal financial disclosures. The function returns a data.frame where each observation corresponds to a candidate's property.

Usage

personal_finances_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

personal_finances_fed() returns a data.frame.

Note

For the elections prior to 2000, some information may be incomplete.

Examples

## Not run: 
df <- personal_finances_fed(2006)

## End(Not run)

Download data on local candidates' personal financial disclosures

Description

personal_finances_local() downloads and aggregates the data on local candidates' personal financial disclosures. The function returns a data.frame where each observation corresponds to a candidate's property.

Usage

personal_finances_local(year, uf = "all", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

assets_candidate_local() returns a data.frame.

Note

For the elections prior to 2000, some information may be incomplete.

Examples

## Not run: 
df <- personal_finances_local(2000)

## End(Not run)

Download data on the number of seats under dispute in federal elections

Description

seats() downloads and aggregates data on the number of seats under dispute in federal elections in Brazil. The function returns a tbl, data.frame where each observation corresponds to a district-office dyad.

Usage

seats(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

seats() returns a data.frame.

Note

For the elections prior to 2000, some information can be incomplete.

Examples

## Not run: 
df <- seats(2000)

## End(Not run)

Download data on the number of seats under dispute in federal elections

Description

seats_fed() downloads and aggregates data on the number of seats under dispute in federal elections in Brazil. The function returns a tbl, data.frame where each observation corresponds to a district-office dyad.

Usage

seats_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

seats_fed() returns a data.frame with the following variables:

Note

For the elections prior to 2000, some information can be incomplete.

Examples

## Not run: 
df <- seats_fed(2000)

## End(Not run)

Download data on the number of seats under dispute in local elections

Description

seats_local() downloads and aggregates data on the number of seats under dispute in local elections in Brazil. The function returns a tbl, data.frame where each observation corresponds to a municipality office dyad.

Usage

seats_local(year, uf = "all", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

seats_local() returns a data.frame.

Note

For the elections prior to 2000, some information can be incomplete.

Examples

## Not run: 
df <- seats_local(2000)

## End(Not run)

Download data on the candidates' social media links in federal elections

Description

social_media() is a function that allows you to download data on the social media handles of candidates participating in federal and municipal elections in Brazil. The function returns a data.frame where each observation corresponds to a candidate's social media handles (i.e., usernames).

Usage

social_media(year, encoding = "latin1", temp = TRUE, readme_pdf = FALSE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

social_media() returns a tbl, data.frame.

Examples

## Not run: 
df <- social_media(2022)

## End(Not run)

Returns a vector with the abbreviations of all Brazilian states

Description

Returns a vector with the abbreviations of all Brazilian states

Usage

uf_br()

Download data on candidate electoral results in federal elections in Brazil

Description

vote_mun_zone() downloads and aggregates data on the verification of federal elections in Brazil, disaggregated by cities and electoral zone. The function returns a data.frame where each observation corresponds to a city/zone.

Usage

vote_mun_zone(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

vote_mun_zone() returns a data.frame with the following variables:

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, 2022, and 2024 elections, more variable are available.

Examples

## Not run: 
df <- vote_mun_zone(2002)

## End(Not run)

Download data on candidate electoral results in federal elections in Brazil

Description

vote_mun_zone_fed() downloads and aggregates data on the verification of federal elections in Brazil, disaggregated by cities and electoral zone. The function returns a data.frame where each observation corresponds to a city/zone.

Usage

vote_mun_zone_fed(
  year,
  uf = "all",
  br_archive = FALSE,
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

vote_mun_zone_fed() returns a data.frame with the following variables:

Note

For the elections prior to 2002, some information can be incomplete. For the 2014, 2018, and 2022 elections, more variable are available.

Examples

## Not run: 
df <- vote_mun_zone_fed(2002)

## End(Not run)

Download data on candidate electoral results in local elections in Brazil

Description

vote_mun_zone_local() downloads and aggregates data on the verification from local elections in Brazil, disaggregated by electoral zone. The function returns a data.frame where each observation corresponds to a city/zone.

Usage

vote_mun_zone_local(
  year,
  uf = "all",
  ascii = FALSE,
  encoding = "latin1",
  export = FALSE,
  temp = TRUE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

vote_mun_zone_local() returns a data.frame with the following variables:

• DATA_GERACAO: Generation date of the file (when the data was collected).

• HORA_GERACAO: Generation time of the file (when the data was collected), Brasilia Time.

• ANO_ELEICAO: Election year.

• NUM_TURNO: Round number.

• DESCRICAO_ELEICAO: Description of the election.

• SIGLA_UF: Units of the Federation's acronym in which occurred the election.

• SIGLA_UE: Units of the Federation's acronym (In case of major election is the FU's acronym in which the candidate runs for (text) and in case of municipal election is the municipal's Supreme Electoral Court code (number)). Assume the special values BR, ZZ and VT to designate, respectively, Brazil, Overseas and Absentee Ballot.

• CODIGO_MUNICIPIO: Supreme Electoral code from the city where occurred the election.

• NOME_MUNICIPIO: Name of the city where occurred the election.

• NUMERO_ZONA: Zone number.

• CODIGO_CARGO: Code of the position that the candidate runs for.

• NUMERO_CANDIDATO: Candidate's number in the ballot box.

• SQ_CANDIDATO: Candidate's sequence number generated internally by the electoral

• NOME_CANDIDATO: Candidate's complete name.

• NOME_URNA_CANDIDATO: Candidate's ballot box name.

• DESCRICAO_CARGO: Description of the position that the candidate runs for.

• COD_SIT_CAND_TOT: Candidate's totalization status code in that election round.

• NUMERO_PARTIDO: Party number.

• SIGLA_PARTIDO: Party's acronym.

• NOME_PARTIDO: Party name.

• SEQUENCIAL_LEGENDA: Coalition's sequential number, generated internally by the electoral justice.

• NOME_COLIGACAO: Coalition name.

• COMPOSICAO_LEGENDA: Coalition's composition.

• TOTAL_VOTOS: Total of votes.

• TRANSITO: Electoral result outside the candidates' district? (N for no).

Note

For the elections prior to 2000, some information can be incomplete.

See Also

vote_mun_zone_fed for federal elections in Brazil.

Examples

## Not run: 
df <- vote_mun_zone_local(2000)

## End(Not run)

Download data on candidate electoral results in federal elections in Brazil by electoral section

Description

vote_section() downloads and cleans data on the verification of federal elections in Brazil, disaggregated by electoral section. Different from other electionsBR's functions, results are only extract for individual states, one at a time. The function returns a data.frame where each observation corresponds to an electoral section in a given Brazilian state.

Usage

vote_section(
  year,
  uf = "AC",
  encoding = "latin1",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the data is saved as .dta and .sav files in the working directory.

Value

vote_section() returns a data.frame.

Note

For the elections prior to 2002, some information can be incomplete.

Examples

## Not run: 
df <- vote_section(2002)

## End(Not run)

Download data on candidate electoral results in federal elections in Brazil by electoral section

Description

vote_section_fed() downloads and cleans data on the verification of federal elections in Brazil, disaggregated by electoral section. Different from other electionsBR's functions, results are only extract for individual states, one at a time. The function returns a data.frame where each observation corresponds to an electoral section in a given Brazilian state.

Usage

vote_section_fed(year, uf = "AC", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the data is saved as .dta and .sav files in the working directory.

Value

vote_section_fed() returns a data.frame.

Note

For the elections prior to 2002, some information can be incomplete.

Examples

## Not run: 
df <- vote_section_fed(2002)

## End(Not run)

Download data on candidate electoral results in local elections in Brazil by electoral section

Description

vote_section_local() downloads and cleans data on the verification of local elections in Brazil, disaggregated by electoral section. Different from other electionsBR's functions, results are only extract for individual states, one at a time. The function returns a data.frame where each observation corresponds to an electoral section in a given Brazilian state.

Usage

vote_section_local(year, uf = "AC", encoding = "latin1", temp = TRUE)

Arguments

Details

If export is set to TRUE, the data is saved as .dta and .sav files in the working directory.

Value

vote_section_local() returns a data.frame.

Note

For the elections prior to 2002, some information can be incomplete.

Examples

## Not run: 
df <- vote_section_local(2000)

## End(Not run)

Download data on the voters' profile

Description

voter_profile() downloads and cleans data on the voters' profile aggregated by state, city and electoral zone. The function returns a data.frame where each observation corresponds to a voter profile type.

Usage

voter_profile(year, encoding = "windows-1252", temp = TRUE, readme_pdf = FALSE)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

voter_profile() returns a data.frame.

Examples

## Not run: 
df <- voter_profile(2002)

## End(Not run)

Download data on the voters' profile by vote section

Description

voter_profile_by_section() downloads and cleans data on the voters' profile aggregated by voting section (i.e., voting stations). The function returns a data.frame where each observation corresponds to a voter profile type.

Usage

voter_profile_by_section(
  year,
  uf = "AC",
  encoding = "windows-1252",
  temp = TRUE,
  readme_pdf = FALSE
)

Arguments

Details

If export is set to TRUE, the downloaded data is saved as .dta and .sav files in the current directory.

Value

voter_profile() returns a data.frame with the following variables:

Examples

## Not run: 
df <- voter_profile_by_section(2016)

## End(Not run)