Import candidacies data — import_candidacies

Import and preprocess candidacies data. This function supports both single values and vector inputs for fetching and combining data for multiple elections at once.

Usage

import_candidacies_data(
  type_elec,
  year = NULL,
  date = NULL,
  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.
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 candidacies data at poll station level 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_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. Codes available only for long version.
id_candidacies: id for candidacies (at province level).
id_candidacies_ccaa, id_candidacies_nat: id for candidacies (at region - ccaa - and national level). Id's available only for long version.
abbrev_candidacies, name_candidacies: acronym and full name of the candidacies.
ballots: number of ballots obtained for each candidacy at each poll station.

Details

This function fetches candidates data for the specified elections by downloading the corresponding files from {pollspaindata} package 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 candidacies data for congress elections in multiple dates
# in a short version
candidacies_data <-
  import_candidacies_data(type_elec = "congress",
                          year = 2023,
                          date = "2019-04-28")
#> Import candidacies data
#>    [x] Checking if parameters are allowed...
#>    [x] Importing candidacies data at poll station level ...
#> ... Please be patient, the volume of data downloaded, your memory size and the internet connection may take a few seconds
#> ! A short version was asked (if you want all variables, run with `short_version = FALSE`)

# Fetch candidacies data for congress elections in multiple dates
# in a long version
candidacies_data <-
  import_candidacies_data(type_elec = "congress",
                          year = c(1982, 2008),
                          short_version = FALSE)
#> Import candidacies data
#>    [x] Checking if parameters are allowed...
#>    [x] Importing candidacies data at poll station level ...
#> ... Please be patient, the volume of data downloaded, your memory size and the internet connection may take a few seconds

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

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

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

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

# Invalid election: no congress elections are available in 2018.
import_candidacies_data(type_elec = "congress", 2018)

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

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