get_elections: Extract data from CEPESPData

In Cepesp-Fgv/cepesp-r: R API for extrating data storaged on CEPESPData

Extract data from CEPESPData

Description

The get_* functions from cepespR extract alternative slices of the processed TSE data avaiable at CEPESPData.

* get_elections() is the most comprehensive function which merges data on election results, candidates and coalitions to enable more complex analysis. Be aware that this function still is in development.

* get_votes() extracts details about the number of votes won by each candidate in a specific election.

* get_candidates() extracts details about the characteristics of individual candidates competing in an election.

* get_coalitions() extracts details about the parties that constitute each coalition that competed in each election.

Usage

get_elections(
  year,
  position,
  state = "all",
  regional_aggregation = "Municipality",
  political_aggregation = "Candidate",
  cached = FALSE,
  columns_list = list(),
  party = NULL,
  candidate_number = NULL,
  only_elected = FALSE,
  dev = FALSE,
  blank_votes = FALSE,
  null_votes = FALSE,
  lambda = FALSE
)

get_votes(
  year,
  position,
  regional_aggregation = "Municipality",
  state = "all",
  cached = FALSE,
  columns_list = list(),
  party = NULL,
  candidate_number = NULL,
  dev = FALSE,
  blank_votes = FALSE,
  null_votes = FALSE,
  lambda = FALSE
)

get_candidates(
  year,
  position,
  cached = FALSE,
  columns_list = list(),
  party = NULL,
  candidate_number = NULL,
  only_elected = FALSE,
  dev = FALSE,
  lambda = FALSE
)

get_coalitions(
  year,
  position,
  columns_list = list(),
  party = NULL,
  cached = FALSE,
  dev = FALSE,
  lambda = FALSE
)

Arguments

year	a integer scalar
position	a character or intecer scalar with the correpondend political contest position.
state	character vector. Default value is "all".
regional_aggregation	character with desired regional aggregation.
political_aggregation	character with desired political aggregation.
cached	a logical scalar. If TRUE, cepespdata will store the dataset inside your computes. Thus, if the same request is made, the data will be immediately available. Note that if you use this feature the app will create a sub-directory /static/cache of your working directory to store the downloaded data. If you are planning to use the functions several times, you should considers setting the parameter to TRUE.
columns_list	a list with the columns needed. If supplied, cepespdata will return only the specified variables.
party	Optional character with a specified party.
candidate_number	Optional integer scalar.

Warning

get_elections() is a function in development. Thus, merges performed by it remain imperfect due to errors in the underlying TSE data and so this function should be treated as beta and used with caution.

Selecting Variables

The default setting is for the function to return all the available variables (columns). To select specific variables and limit the size of the request, you can specify a list of required columns in the columns_list property. The specific columns available depend on the political and regional aggregation selected so you are advised to refer to the API documentation at https://github.com/Cepesp-Fgv/cepesp-rest for further details.

Filters

To limit the size of the data returned by the API, the request can be filtered to return data on specific units: By state (using the two-letter abbreviation, eg. "RJ"); by party (using the two-digit official party number, eg. 45), or by candidate number.

Cache

Each time a request is made to the cepesp-R API, the specific dataset is constructed and downloaded to your local system. To limit processing and bandwidth utilization, the cepespR package includes the option to cache your requests so that they are stored locally and immediately available when that request is repeated.

Note that if you use this feature the app will create a sub-directory /static/cache of your working directory to store the downloaded data. You can manually delete this data to force a new download the next time the same request is made.

Examples

## Not run: 
#Basic use of get_* functions.

data <- get_elections(year = 2014, position = "Federal Deputy")

data <- get_votes(year = 2014, position = "Federal Deputy")

data <- get_candidates(year = 2014, position = "Federal Deputy")

data <- get_coalitions(year = 2014, position = "Federal Deputy")

#If needed, it is possible to change regional and political aggregation

data <- get_elections(year = 2014,
                      position = "Federal Deputy",
                      regional_aggregation = "State",
                      political_aggregation = "Party")

## End(Not run)

Cepesp-Fgv/cepesp-r documentation built on Oct. 17, 2023, 5:54 a.m.