Function to get jointly information on polling stations and votes for candidacies.

Import and preprocess poll stations info but jointly with the preprocessed candidacies data, for given election types and dates, at poll station level. This function supports both single values and vector inputs for fetching and combining data for multiple elections at once.

Usage

get_election_data(
  type_elec,
  year = NULL,
  date = NULL,
  prec_round = 3,
  short_version = TRUE,
  verbose = TRUE,
  col_id_elec = "id_elec",
  col_id_poll_station = "id_INE_poll_station",
  col_id_mun = "id_INE_mun",
  col_id_candidacies = c(id_prov = "id_candidacies", id_nat = "id_candidacies_nat")
)

Arguments

type_elec: Type elections for which data is available. It should be one of the following values: "referendum", "congress", "senate", "local", "cabildo" (Canarian council) or "EU".
year: A vector or single value representing the years of the elections to be considered. Please, check in dates_elections_spain that elections of the specified type are available for the provided year.
date: A vector or single value representing the dates of the elections to be considered. If date was provided, it should be in format %Y-%m-%d (e.g., '2000-01-01'). Defaults to NULL. If no date was provided, year should be provided as numerical variable. Please, check in dates_elections_spain that elections of the specified type are available.
prec_round: Rounding accuracy. Defaults to prec_round = 3.
short_version: Flag to indicate whether it should be returned a short version of the data (just key variables) or not. Defaults to TRUE.
verbose: Flag to indicate whether detailed messages should be printed during execution. Defaults to TRUE.
col_id_elec, col_id_poll_station, col_id_mun, col_id_candidacies: (Optional) Column names for election's id, poll station's id, municipalities' id and candidacies' id

Value

A tibble with rows corresponding to poll-stations for each election, including the following variables:

id_elec: election's id constructed from the election code cod_elec and date date_elec.
cod_elec: code representing the type of election: "01" (referendum), "02" (congress), "03" (senate), "04" (local elections), "06" (cabildo - Canarian council - elections), "07" (European Parliament elections). Variable available only for long version.
type_election: type of the election.
date_elec: date of the election. Variable available only for long version.
id_INE_poll_station: poll station's id constructed from the ccaa-prov-municipality and poll station codes.
id_INE_mun: municipality ID constructed from the ccaa-prov-mun codes provided by INE.
cod_INE_ccaa, ccaa: codes and names for regions (ccaa) to which the municipalities belong. Codes available only for long version.
cod_INE_prov, prov: codes and names for the provinces to which the municipalities belong. Codes available only for long version.
cod_INE_mun, mun: code, and name for municipalities. Codes available only for long version.
cod_mun_district, cod_sec, cod_poll_station: codes for the municipal district, census tract and poll station. They are only available for long version.
ballots_1, turnout_1: number of total ballots and turnout percentage in the first round. Variables available only for long version.
ballots_2, turnout_2: number of total ballots and turnout percentage in the second round (if applicable). Variables available only for long version
blank_ballots, invalid_ballots: blank and invalid ballots.
party_ballots, valid_ballots, total_ballots: ballots to candidacies/parties, valid ballots (sum of blank_ballots and party_ballots) and total ballots (sum of valid_ballots and invalid_ballots).
turnout: final turnout percentage. It is only available for long version.
porc_valid, porc_invalid, porc_parties, porc_blank: perc (%) values of valid_ballots, invalid_ballots, party_ballots and blank_ballots.
n_poll_stations: number of polling stations. It is only available for long version.
pop_res_mun: population census of residents (CER + CERA) at municipality level.
census_counting_mun: population eligible to vote after claims at municipality level.
id_candidacies: id for candidacies at province level.
id_candidacies_ccaa, id_candidacies_nat: id for candidacies at ccaa level (only provided for long version) and at national level.
abbrev_candidacies, name_candidacies: acronym and full name of the candidacies. They are only available for long version.
ballots: number of ballots obtained for each candidacy at each poll station.

Details

The purpose of this function is to easily combine the outputs of import_poll_station_data(), import_mun_census_data(), and import_candidacies_data(), providing a tibble at the polling station level with both general voting data (blank votes, null votes, etc.) and votes for each candidacy (identified by their corresponding ids). This function does not perform aggregations and is not intended as a final-use tool for basic users, but rather as an intermediate step for the summary_election_data() function.

Author

Javier Alvarez-Liebana and David Pereiro-Pol.

Examples


## Correct examples

# Congress elections in year 2008, 2016 and "2023-07-24"
# in a short version
elections_data <-
  get_election_data(type_elec = "congress", year = c(2008, 2016),
                    date = "2023-07-24")
#> Get and join election data
#>    [x] Checking if parameters are allowed...
#>    [x] Importing the following poll station data ...
#>        - congress elections on 2008-03-09
#>        - congress elections on 2016-06-26
#>        - congress elections on 2023-07-24
#> 
#>    [x] Importing candidacies and ballots data (at poll station level) ...
#> ... Please be patient, volume of data downloaded and internet connection may take a few seconds
#> ! A short version was asked (if you want all variables, run with `short_version = FALSE`)

# Congress elections in 2008 in a long version
elections_data <-
  get_election_data(type_elec = "congress", year = 2008,
                    short_version = FALSE)
#> Get and join election data
#>    [x] Checking if parameters are allowed...
#>    [x] Importing the following poll station data ...
#>        - congress elections on 2008-03-09
#> 
#>    [x] Importing candidacies and ballots data (at poll station level) ...
#> ... Please be patient, volume of data downloaded and internet connection may take a few seconds

if (FALSE) { # \dontrun{
# ----
# Incorrect examples
# ----

# Invalid election type: "national" is not a valid election type
get_election_data(type_elec = "national", year = 2019)

# Invalid date format: date should be in %Y-%m-%d format
get_election_data(type_elec = "congress", date = "26-06-2016")

# Invalid short version flag: short_version should be a
# logical variable
get_election_data(type_elec = "congress", year = 2019,
                  short_version = "yes")

} # }