Title:	Access to Canadian Election Study Data
Version:	1.0.1
Author:	Laurence-Olivier M. Foisy [aut, cre]
Maintainer:	Laurence-Olivier M. Foisy <mail@mfoisy.com>
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.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, openxlsx
Config/testthat/edition:	3
Imports:	dplyr, haven, tibble, utils
VignetteBuilder:	knitr
URL:	https://github.com/laurenceomfoisy/ces
BugReports:	https://github.com/laurenceomfoisy/ces/issues
Depends:	R (≥ 3.5)
NeedsCompilation:	no
Packaged:	2025-07-25 15:00:09 UTC; ral
Repository:	CRAN
Date/Publication:	2025-07-25 17:40:07 UTC

Canadian Election Study Data Package

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.

Key Functions

• 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 Sources

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.

Author(s)

Laurence-Olivier M. Foisy

References

For more information about the Canadian Election Study, visit: https://ces-eec.arts.ubc.ca/

See Also

Useful links:

• https://github.com/laurenceomfoisy/ces

• Report bugs at https://github.com/laurenceomfoisy/ces/issues

Check if file exists and handle overwrite safely

Description

Check if file exists and handle overwrite safely

Usage

check_file_conflict(file_path, overwrite = FALSE)

Arguments

Value

TRUE if file can be written, FALSE or error otherwise

Clean Canadian Election Study Dataset

Description

This function performs cleaning operations on CES data, including recoding variables, converting factors, and standardizing column names.

Usage

clean_ces_data(data, year, language = "en")

Arguments

Value

A cleaned tibble with standardized variables.

Clean Canadian Election Study Dataset while Preserving Metadata

Description

This function performs minimal cleaning operations on CES data to maximize preservation of variable metadata, including labels and attributes.

Usage

clean_ces_data_preserve_metadata(data, year, language = "en")

Arguments

Value

A cleaned tibble with preserved metadata.

Create a Codebook for Canadian Election Study Dataset

Description

This function generates a comprehensive codebook for a CES dataset, including variable names, question labels, and response options.

Usage

create_codebook(data, include_values = TRUE, format = "tibble")

Arguments

Value

A tibble or data.frame containing the codebook with columns for variable name, question label, and response options.

Examples

# 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)

Download All Canadian Election Study Datasets

Description

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.

Usage

download_all_ces_datasets(
  path = NULL,
  years = NULL,
  variants = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Invisibly returns a character vector with the file paths of the downloaded datasets.

Examples

# 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 a Canadian Election Study Dataset

Description

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).

Usage

download_ces_dataset(
  year,
  variant = NULL,
  path = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Invisibly returns the file path of the downloaded dataset.

Examples

# 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 Canadian Election Study PDF Codebook

Description

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.

Usage

download_pdf_codebook(
  year,
  variant = NULL,
  path = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Invisibly returns the file path of the downloaded codebook.

Examples

# 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)

Examine Variable Metadata in a CES Dataset

Description

This function provides an overview of the metadata available in a CES dataset, showing which variables have labels, value labels, and other attributes.

Usage

examine_metadata(data, show_labels = FALSE, variable_pattern = NULL)

Arguments

Value

A data.frame with metadata information for each variable.

Examples

# 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")

Export Codebook to CSV or Excel

Description

This function exports a CES codebook to a CSV or Excel file for easier viewing and sharing.

Usage

export_codebook(codebook, file_path, ...)

Arguments

Value

Invisibly returns the file path where the codebook was saved.

Examples

# Get data and create codebook
ces_data <- get_ces("2019")
codebook <- create_codebook(ces_data)

# Export to CSV
export_codebook(codebook, "ces_2019_codebook.csv")

# Export to Excel
export_codebook(codebook, "ces_2019_codebook.xlsx")

Extract data file from ZIP archive

Description

This function downloads a ZIP file, extracts only the data file (.dta or .sav), and cleans up the ZIP file and any non-data files (PDFs, etc.).

Usage

extract_data_from_zip(url, destfile, expected_format, quiet = FALSE)

Arguments

Value

Path to the extracted data file

Get Canadian Election Study Dataset

Description

This function downloads and processes a Canadian Election Study dataset for the specified year.

Usage

get_ces(
  year,
  variant = NULL,
  format = "tibble",
  language = "en",
  clean = TRUE,
  preserve_metadata = TRUE,
  use_cache = TRUE,
  verbose = TRUE
)

Arguments

Value

A tibble or data.frame containing the requested CES data.

Note

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.

Examples

# 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 Subset of Variables from Canadian Election Study Dataset

Description

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.

Usage

get_ces_subset(
  year,
  variant = NULL,
  variables = NULL,
  regex = FALSE,
  format = "tibble",
  clean = TRUE,
  use_cache = TRUE
)

Arguments

Value

A tibble or data.frame containing the requested CES data variables.

Examples

# 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 default download directory that works across platforms

Description

Get default download directory that works across platforms

Usage

get_download_dir()

Value

Path to the default download directory

List Available Canadian Election Study Datasets

Description

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.

Usage

list_ces_datasets()

Value

Invisibly returns a tibble with columns for year and variants. The catalog is printed to the console for easy viewing.

Examples

# Display catalog of all available datasets by year
list_ces_datasets()

Platform-specific utility functions

Description

These are internal helper functions to ensure cross-platform compatibility. They handle differences between operating systems for file paths, encodings, and other platform-specific behaviors.

Usage

normalize_path(path, must_work = FALSE)

Arguments

Value

Normalized absolute path

Safely create a directory with proper checks

Description

Safely create a directory with proper checks

Usage

safe_dir_create(dir, recursive = TRUE, verbose = TRUE)

Arguments

Value

TRUE if successful, error message if not

Safe file download with platform-specific handling

Description

Safe file download with platform-specific handling

Usage

safe_download(
  url,
  destfile,
  mode = "wb",
  quiet = FALSE,
  timeout = 600,
  max_retries = 3
)

Arguments

Value

0 if successful, error code otherwise

Show variant information message when multiple variants are available

Description

This helper function displays an informative message when a user accesses a year with multiple variants without specifying a variant parameter.

Usage

show_variant_message(year, selected_variant, is_variant_null, verbose = TRUE)

Arguments

Value

NULL (invisible), message shown as side effect