| Title: | Access to Canadian Election Study Data |
|---|---|
| Description: | Provides tools to easily access and analyze Canadian Election Study data. The package simplifies the process of downloading, cleaning, and using 'CES' datasets for political science research and analysis. The Canadian Election Study ('CES') has been conducted during federal elections since 1965, surveying Canadians on their political preferences, engagement, and demographics. Data is accessed from multiple sources including the 'Borealis' Data repository <https://borealisdata.ca/> and the official 'Canadian Election Study' website <https://ces-eec.arts.ubc.ca/>. This package is not officially affiliated with the Canadian Election Study, 'Borealis' Data, or the University of British Columbia, and users should cite the original data sources in their work. |
| Authors: | Laurence-Olivier M. Foisy [aut, cre]
|
| Maintainer: | Laurence-Olivier M. Foisy <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.1.0 |
| Built: | 2026-06-06 21:02:32 UTC |
| Source: | https://github.com/laurenceomfoisy/ces |
Provides tools to easily access and analyze Canadian Election Study data. The package simplifies the process of downloading, cleaning, and using CES datasets for political science research and analysis. The Canadian Election Study (CES) has been conducted during federal elections since 1965, surveying Canadians on their political preferences, engagement, and demographics.
get_ces: Download and load CES data for a specific year
list_ces_datasets: List available CES datasets
get_ces_subset: Get a subset of variables from a CES dataset
create_codebook: Generate a comprehensive codebook for CES datasets
download_pdf_codebook: Download official PDF codebooks
download_ces_dataset: Download a single CES dataset
download_all_ces_datasets: Download all CES datasets
Data is accessed from multiple sources including the Borealis Data repository (the primary institutional repository for most CES datasets) and the official Canadian Election Study website. This package is not officially affiliated with the Canadian Election Study, Borealis Data, or the University of British Columbia, and users should cite the original data sources in their work.
Laurence-Olivier M. Foisy
For more information about the Canadian Election Study, visit: https://ces-eec.arts.ubc.ca/
Useful links:
This function generates a comprehensive codebook for a CES dataset, including variable names, question labels, and response options.
create_codebook(data, include_values = TRUE, format = "tibble")create_codebook(data, include_values = TRUE, format = "tibble")
data |
A CES dataset, typically retrieved using |
include_values |
Logical indicating whether to include response values in addition to labels. Default is TRUE. |
format |
A character string indicating the format to return the codebook in. Default is "tibble". Options include "tibble" or "data.frame". |
A tibble or data.frame containing the codebook with columns for variable name, question label, and response options.
# Get the 2019 CES data ces_2019 <- get_ces("2019") # Create a codebook codebook <- create_codebook(ces_2019) # View the first few entries head(codebook) # Create a codebook without values codebook_simple <- create_codebook(ces_2019, include_values = FALSE)# Get the 2019 CES data ces_2019 <- get_ces("2019") # Create a codebook codebook <- create_codebook(ces_2019) # View the first few entries head(codebook) # Create a codebook without values codebook_simple <- create_codebook(ces_2019, include_values = FALSE)
This function downloads all available Canadian Election Study datasets to a specified directory.
Each dataset is saved with a standardized filename in the format of ces_<year>_<variant>.<format>,
where the format extension corresponds to the original dataset format (e.g., .sav for SPSS,
.dta for Stata). For ZIP archives, only the data files are extracted and saved, with all other
files (PDFs, etc.) discarded.
download_all_ces_datasets( path = NULL, years = NULL, variants = NULL, overwrite = FALSE, verbose = TRUE )download_all_ces_datasets( path = NULL, years = NULL, variants = NULL, overwrite = FALSE, verbose = TRUE )
path |
A character string indicating the directory where the datasets should be saved. If NULL (default), the datasets will be saved to the Downloads directory if available, otherwise to a temporary directory. |
years |
Optional character vector specifying which years to download. If NULL (default), all available years will be downloaded. |
variants |
Optional character vector specifying which variants to download. If NULL (default), all available variants will be downloaded. |
overwrite |
Logical indicating whether to overwrite existing files. Default is FALSE. |
verbose |
Logical indicating whether to display detailed progress messages during download. Default is TRUE. |
Invisibly returns a character vector with the file paths of the downloaded datasets.
# Download all CES datasets to a temporary directory download_all_ces_datasets(path = tempdir(), overwrite = TRUE) # Download only specific years (all variants for those years) download_all_ces_datasets(years = c("2015", "2019", "2021"), path = tempdir(), overwrite = TRUE) # Download only web surveys for 2015 and 2019 download_all_ces_datasets(years = c("2015", "2019"), variants = "web", path = tempdir(), overwrite = TRUE) # Download to a temporary directory with overwrite download_all_ces_datasets(path = tempdir(), overwrite = TRUE)# Download all CES datasets to a temporary directory download_all_ces_datasets(path = tempdir(), overwrite = TRUE) # Download only specific years (all variants for those years) download_all_ces_datasets(years = c("2015", "2019", "2021"), path = tempdir(), overwrite = TRUE) # Download only web surveys for 2015 and 2019 download_all_ces_datasets(years = c("2015", "2019"), variants = "web", path = tempdir(), overwrite = TRUE) # Download to a temporary directory with overwrite download_all_ces_datasets(path = tempdir(), overwrite = TRUE)
This function downloads a single Canadian Election Study dataset for a specified year.
The dataset is saved with a standardized filename in the format of ces_<year>_<variant>.<format>,
where the format extension corresponds to the original dataset format (e.g., .sav for SPSS,
.dta for Stata).
download_ces_dataset( year, variant = NULL, path = NULL, overwrite = FALSE, verbose = TRUE )download_ces_dataset( year, variant = NULL, path = NULL, overwrite = FALSE, verbose = TRUE )
year |
A character string indicating the year of the CES data to download. Available years include "1965", "1968", "1972", "1974", "1984", "1988", "1993", "1997", "2000", "2004", "2006", "2008", "2011", "2015", "2019", "2021", "2025". |
variant |
A character string indicating the survey variant to download.
Options depend on the year: "single_survey" (default for most years), "web" (default for 2015, 2019),
"phone", "combo", "1974_1980", "jnjl", "sep", "nov". Use |
path |
A character string indicating the directory where the dataset should be saved. If NULL (default), the dataset will be saved to the Downloads directory if available, otherwise to a temporary directory. |
overwrite |
Logical indicating whether to overwrite existing files. Default is FALSE. |
verbose |
Logical indicating whether to display detailed progress messages during download. Default is TRUE. |
Invisibly returns the file path of the downloaded dataset.
# Download the 2019 CES web survey dataset to a temporary directory download_ces_dataset("2019", path = tempdir(), overwrite = TRUE) # Download the 2019 phone survey to a specific directory download_ces_dataset("2019", variant = "phone", path = tempdir(), overwrite = TRUE) # Download 1972 September survey download_ces_dataset("1972", variant = "sep", path = tempdir(), overwrite = TRUE) # Overwrite existing file download_ces_dataset("2021", path = tempdir(), overwrite = TRUE)# Download the 2019 CES web survey dataset to a temporary directory download_ces_dataset("2019", path = tempdir(), overwrite = TRUE) # Download the 2019 phone survey to a specific directory download_ces_dataset("2019", variant = "phone", path = tempdir(), overwrite = TRUE) # Download 1972 September survey download_ces_dataset("1972", variant = "sep", path = tempdir(), overwrite = TRUE) # Overwrite existing file download_ces_dataset("2021", path = tempdir(), overwrite = TRUE)
This function downloads the official PDF codebook for a specified year of the Canadian Election Study. The codebook contains detailed information about all variables, question wording, response codes, and methodological details.
download_pdf_codebook( year, variant = NULL, path = NULL, overwrite = FALSE, verbose = TRUE )download_pdf_codebook( year, variant = NULL, path = NULL, overwrite = FALSE, verbose = TRUE )
year |
A character string indicating the year of the CES data. Available years include "1965", "1968", "1972", "1974", "1984", "1988", "1993", "1997", "2000", "2004", "2006", "2008", "2011", "2015", "2019", "2021", "2025". |
variant |
A character string indicating the survey variant to download. For years with multiple variants (1972, 2015, 2019), this specifies which one to use. If NULL (default), uses the first available variant for the year. |
path |
A character string indicating the directory where the codebook should be saved. If NULL (default), the codebook will be saved to the Downloads directory if available, otherwise to a temporary directory. |
overwrite |
Logical indicating whether to overwrite existing files. Default is FALSE. |
verbose |
Logical indicating whether to display detailed progress messages during download. Default is TRUE. |
Invisibly returns the file path of the downloaded codebook.
# Download the 2019 CES codebook to a temporary directory (defaults to web variant) download_pdf_codebook("2019", path = tempdir(), overwrite = TRUE) # Download the 2019 phone survey codebook download_pdf_codebook("2019", variant = "phone", path = tempdir(), overwrite = TRUE) # Download the 1972 September survey codebook download_pdf_codebook("1972", variant = "sep", path = tempdir(), overwrite = TRUE) # Overwrite existing file download_pdf_codebook("2021", path = tempdir(), overwrite = TRUE)# Download the 2019 CES codebook to a temporary directory (defaults to web variant) download_pdf_codebook("2019", path = tempdir(), overwrite = TRUE) # Download the 2019 phone survey codebook download_pdf_codebook("2019", variant = "phone", path = tempdir(), overwrite = TRUE) # Download the 1972 September survey codebook download_pdf_codebook("1972", variant = "sep", path = tempdir(), overwrite = TRUE) # Overwrite existing file download_pdf_codebook("2021", path = tempdir(), overwrite = TRUE)
This function provides an overview of the metadata available in a CES dataset, showing which variables have labels, value labels, and other attributes.
examine_metadata(data, show_labels = FALSE, variable_pattern = NULL)examine_metadata(data, show_labels = FALSE, variable_pattern = NULL)
data |
A CES dataset, typically retrieved using |
show_labels |
Logical indicating whether to show the actual labels. Default is FALSE. |
variable_pattern |
Optional regular expression to filter variables. |
A data.frame with metadata information for each variable.
# Get CES data with preserved metadata ces_2019 <- get_ces("2019", preserve_metadata = TRUE) # Examine metadata for all variables metadata_overview <- examine_metadata(ces_2019) # Examine metadata for voting-related variables, showing labels voting_metadata <- examine_metadata(ces_2019, show_labels = TRUE, variable_pattern = "vote|ballot")# Get CES data with preserved metadata ces_2019 <- get_ces("2019", preserve_metadata = TRUE) # Examine metadata for all variables metadata_overview <- examine_metadata(ces_2019) # Examine metadata for voting-related variables, showing labels voting_metadata <- examine_metadata(ces_2019, show_labels = TRUE, variable_pattern = "vote|ballot")
This function exports a CES codebook to a CSV or Excel file for easier viewing and sharing.
export_codebook(codebook, file_path, ...)export_codebook(codebook, file_path, ...)
codebook |
A codebook dataframe created with |
file_path |
The path where the file should be saved, including file extension. Use .csv for CSV or .xlsx for Excel. |
... |
Additional arguments passed to write functions. |
Invisibly returns the file path where the codebook was saved.
# Get data and create codebook ces_data <- get_ces("2019") codebook <- create_codebook(ces_data) # Export to CSV (written to a temporary directory) csv_path <- file.path(tempdir(), "ces_2019_codebook.csv") export_codebook(codebook, csv_path) # Export to Excel (requires the 'openxlsx' package) if (requireNamespace("openxlsx", quietly = TRUE)) { xlsx_path <- file.path(tempdir(), "ces_2019_codebook.xlsx") export_codebook(codebook, xlsx_path) }# Get data and create codebook ces_data <- get_ces("2019") codebook <- create_codebook(ces_data) # Export to CSV (written to a temporary directory) csv_path <- file.path(tempdir(), "ces_2019_codebook.csv") export_codebook(codebook, csv_path) # Export to Excel (requires the 'openxlsx' package) if (requireNamespace("openxlsx", quietly = TRUE)) { xlsx_path <- file.path(tempdir(), "ces_2019_codebook.xlsx") export_codebook(codebook, xlsx_path) }
This function downloads and processes a Canadian Election Study dataset for the specified year.
get_ces( year, variant = NULL, format = "tibble", language = "en", clean = TRUE, preserve_metadata = TRUE, use_cache = TRUE, verbose = TRUE )get_ces( year, variant = NULL, format = "tibble", language = "en", clean = TRUE, preserve_metadata = TRUE, use_cache = TRUE, verbose = TRUE )
year |
A character string indicating the year of the CES data. Available years include "1965", "1968", "1972", "1974", "1984", "1988", "1993", "1997", "2000", "2004", "2006", "2008", "2011", "2015", "2019", "2021", "2025". |
variant |
A character string indicating the survey variant to download.
Options depend on the year: "single_survey" (default for most years), "web" (default for 2015, 2019),
"phone", "combo", "1974_1980", "jnjl", "sep", "nov". Use |
format |
A character string indicating the format to return the data in. Default is "tibble". Options include "tibble", "data.frame", or "raw". |
language |
A character string indicating the language of the survey questions. Default is "en" (English). Alternative is "fr" (French). |
clean |
Logical indicating whether to clean the data (recode variables, convert factors, etc.). Default is TRUE. |
preserve_metadata |
Logical indicating whether to prioritize preserving all variable metadata (labels, attributes) over standardization. Default is TRUE. This ensures all original question labels and value labels are maintained. |
use_cache |
Logical indicating whether to use cached data if available. Default is TRUE. |
verbose |
Logical indicating whether to display detailed progress messages during data retrieval and processing. Default is TRUE. |
A tibble or data.frame containing the requested CES data.
Official PDF codebooks for each CES year are available via the
download_pdf_codebook function, which provides detailed information
about variables, question wording, and methodology.
# Get the 2019 CES web survey data (default) ces_2019_web <- get_ces("2019") # Get the 2019 CES phone survey data ces_2019_phone <- get_ces("2019", variant = "phone") # Get the 1993 CES data, unprocessed ces_1993_raw <- get_ces("1993", clean = FALSE) # Get 1972 September survey ces_1972_sep <- get_ces("1972", variant = "sep") # Download the official codebook to temporary directory download_pdf_codebook("2019", path = tempdir(), overwrite = TRUE)# Get the 2019 CES web survey data (default) ces_2019_web <- get_ces("2019") # Get the 2019 CES phone survey data ces_2019_phone <- get_ces("2019", variant = "phone") # Get the 1993 CES data, unprocessed ces_1993_raw <- get_ces("1993", clean = FALSE) # Get 1972 September survey ces_1972_sep <- get_ces("1972", variant = "sep") # Download the official codebook to temporary directory download_pdf_codebook("2019", path = tempdir(), overwrite = TRUE)
This function allows users to get a specific subset of variables from a CES dataset. It's useful for selecting only the variables of interest for a specific analysis.
get_ces_subset( year, variant = NULL, variables = NULL, regex = FALSE, format = "tibble", clean = TRUE, use_cache = TRUE )get_ces_subset( year, variant = NULL, variables = NULL, regex = FALSE, format = "tibble", clean = TRUE, use_cache = TRUE )
year |
A character string indicating the year of the CES data. |
variant |
A character string indicating the survey variant to download.
Options depend on the year: "single_survey" (default for most years), "web" (default for 2015, 2019),
"phone", "combo", "1974_1980", "jnjl", "sep", "nov". Use |
variables |
A character vector of variable names to select from the dataset. If NULL (default), all variables are returned. |
regex |
A logical indicating whether to use regex matching for variable names. Default is FALSE. |
format |
A character string indicating the format to return the data in. Default is "tibble". Options include "tibble", "data.frame", or "raw". |
clean |
Logical indicating whether to clean the data. Default is TRUE. |
use_cache |
Logical indicating whether to use cached data if available. Default is TRUE. |
A tibble or data.frame containing the requested CES data variables.
# Get only vote choice and demographic variables from 2019 web survey variables <- c("vote_choice", "age", "gender", "province", "education") ces_subset <- get_ces_subset("2019", variables = variables) # Get subset from 2019 phone survey ces_subset_phone <- get_ces_subset("2019", variant = "phone", variables = variables) # Get all variables containing "vote" in their name (using regex) vote_vars <- get_ces_subset("2019", variables = "vote", regex = TRUE)# Get only vote choice and demographic variables from 2019 web survey variables <- c("vote_choice", "age", "gender", "province", "education") ces_subset <- get_ces_subset("2019", variables = variables) # Get subset from 2019 phone survey ces_subset_phone <- get_ces_subset("2019", variant = "phone", variables = variables) # Get all variables containing "vote" in their name (using regex) vote_vars <- get_ces_subset("2019", variables = "vote", regex = TRUE)
This function displays a formatted catalog of all available CES datasets that can be accessed through the package, showing year and available variants. One row per year with variants listed as comma-separated values.
list_ces_datasets()list_ces_datasets()
Invisibly returns a tibble with columns for year and variants. The catalog is printed to the console for easy viewing.
# Display catalog of all available datasets by year list_ces_datasets()# Display catalog of all available datasets by year list_ces_datasets()