Title:	Access to Canadian Election Study Data
Version:	0.1.0
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 the 'Borealis' Data repository https://borealisdata.ca/, which serves as the official host for 'CES' datasets. This package is not officially affiliated with the Canadian Election Study or 'Borealis' Data, 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-05-26 14:18:21 UTC; ral
Repository:	CRAN
Date/Publication:	2025-05-28 15:40:06 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 Source

Data is accessed from the Borealis Data repository, which serves as the official host for CES datasets. This package is not officially affiliated with the Canadian Election Study or Borealis Data, 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>.<format>⁠, where the format extension corresponds to the original dataset format (e.g., .sav for SPSS, .dta for Stata).

Usage

download_all_ces_datasets(
  path = NULL,
  years = 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())

# Download only specific years
download_all_ces_datasets(years = c("2015", "2019", "2021"), path = tempdir())

# 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>.<format>⁠, where the format extension corresponds to the original dataset format (e.g., .sav for SPSS, .dta for Stata).

Usage

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

Arguments

Value

Invisibly returns the file path of the downloaded dataset.

Examples

# Download the 2019 CES dataset to a temporary directory
download_ces_dataset("2019", path = tempdir())

# Download to a specific directory
download_ces_dataset("2015", path = tempdir())

# 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, 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
download_pdf_codebook("2019", path = tempdir())

# Download to a temporary directory
download_pdf_codebook("2015", path = tempdir())

# 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

## Not run: 
# 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")

## End(Not run)

Get Canadian Election Study Dataset

Description

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

Usage

get_ces(
  year,
  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 data
ces_2019 <- get_ces("2019")

# Get the 1993 CES data, unprocessed
ces_1993_raw <- get_ces("1993", clean = FALSE)

# Download the official codebook to temporary directory
download_pdf_codebook("2019", path = tempdir())

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,
  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
variables <- c("vote_choice", "age", "gender", "province", "education")
ces_subset <- get_ces_subset("2019", variables)

# Get all variables containing "vote" in their name (using regex)
vote_vars <- get_ces_subset("2019", "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 returns information about available CES datasets that can be accessed through the package.

Usage

list_ces_datasets(details = FALSE)

Arguments

Value

If details is FALSE, a character vector of available dataset years. If TRUE, a tibble with columns for year, type, and description.

Examples

# Get list of available years
list_ces_datasets()

# Get detailed information
list_ces_datasets(details = TRUE)

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)

Arguments

Value

0 if successful, error code otherwise