Import poll station data — import_poll_station

Import and preprocess elections data at poll stations level for given election types and dates. This function supports both single values and vector inputs for fetching and combining data for multiple elections at once.

Usage

import_poll_station_data(
  type_elec,
  year = NULL,
  date = NULL,
  prec_round = 3,
  short_version = TRUE,
  verbose = TRUE
)

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.

Value

A tibble with rows corresponding to municipalities 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_elec: type of election.
date_elec: date of the election.
id_INE_mun: municipality ID constructed from the ccaa-prov-mun codes provided by INE.
id_INE_poll_station: poll station's id constructed from the ccaa-prov-municipality and poll station codes.
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 provinces to which 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. Codes available only for long version.
census_counting_mun: population eligible to vote after claims at municipality level.
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.
porc_valid, porc_invalid, porc_parties, porc_blank: perc (%) values of valid_ballots, invalid_ballots, party_ballots and blank_ballots.
pop_res_mun: population census of residents (CER + CERA) at municipality level.

Details

This function fetches poll station-level data for the specified elections by downloading the corresponding files from {pollspaindata} and processing them into a tidy format. It automatically handles the download, loading, and merging of data across multiple election periods as specified by the user.

Author

Javier Alvarez-Liebana, David Pereiro Pol, Mafalda Gonzalez Gonzalez, Irene Bosque Gala and Mikaela De Smedt.

Examples


## Correct examples

# Fetch poll station data for congress elections in multiple dates
# in a short version
poll_station_data <-
  import_poll_station_data(type_elec = "congress", year = 2023,
                           date = "2019-04-28")
#> Import poll station data
#>    [x] Checking if parameters are allowed...
#>    [x] Importing the following poll station data ...
#>        - congress elections on 2023-07-24
#>        - congress elections on 2019-04-28
#> 
#> ! A short version was asked (if you want all variables, run with `short_version = FALSE`)

# Fetch poll station data for congress elections in multiple dates
# in a long version
poll_station_data <-
  import_poll_station_data(type_elec = "congress",
                           date = c("2019-04-28", "2023-07-24"),
                           short_version = FALSE)
#> Import poll station data
#>    [x] Checking if parameters are allowed...
#>    [x] Importing the following poll station data ...
#>        - congress elections on 2019-04-28
#>        - congress elections on 2023-07-24
#> 

# ----
# Incorrect examples
# ----

if (FALSE) { # \dontrun{
# Wrong examples

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

# Invalid verbose argument: verbose should be a logical variable
import_poll_station_data(type_elec = "congress", year = 2023,
                         verbose = "yes")

# Invalid election: no congress elections are available in 2018
# Please check dataset dates_elections_spain
import_poll_station_data(type_elec = "congress", year = 2018)

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

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