Introduction to the ces package

Available Datasets

The package currently provides access to CES datasets spanning from 1965 to 2021:

# List all available datasets
list_ces_datasets()
#>  [1] "1965"      "1968"      "1974-1980" "1984"      "1988"      "1993"     
#>  [7] "1997"      "2000"      "2004"      "2006"      "2008"      "2011"     
#> [13] "2015"      "2019"      "2021"

# Get detailed information about available datasets
list_ces_datasets(details = TRUE)
#> # A tibble: 15 × 3
#>    year      type      description                                            
#>    <chr>     <chr>     <chr>                                                  
#>  1 1965      Survey    1965 Canadian Election Study                           
#>  2 1968      Survey    1968 Canadian Election Study                           
#>  3 1974-1980 Panel     1974-1980 Canadian Election Study Panel                
#>  4 1984      Survey    1984 Canadian Election Study                           
#>  5 1988      Survey    1988 Canadian Election Study                           
#>  6 1993      Survey    1993 Canadian Election Study                           
#>  7 1997      Survey    1997 Canadian Election Study                           
#>  8 2000      Survey    2000 Canadian Election Study                           
#>  9 2004      Survey    2004 Canadian Election Study                           
#> 10 2006      Survey    2006 Canadian Election Study                           
#> 11 2008      Survey    2008 Canadian Election Study                           
#> 12 2011      Survey    2011 Canadian Election Study                           
#> 13 2015      Web/Phone 2015 Canadian Election Study - Online and Phone Surveys
#> 14 2019      Web/Phone 2019 Canadian Election Study - Online and Phone Surveys
#> 15 2021      Web/Phone 2021 Canadian Election Study - Online Survey

Getting Data

Basic Usage

The primary function for accessing CES data is get_ces(), which downloads and processes the dataset for a specified year:

# Get the 2019 CES data
ces_2019 <- get_ces("2019")

# View the first few rows
head(ces_2019)

# Get information about the dataset
dim(ces_2019)

Customizing Data Retrieval

The get_ces() function offers several options for customizing how data is retrieved and processed:

# Get raw (uncleaned) data
ces_raw <- get_ces("2019", clean = FALSE)

# Get data as a data.frame instead of a tibble
ces_df <- get_ces("2019", format = "data.frame")

# Bypass cache and download fresh data
ces_fresh <- get_ces("2019", use_cache = FALSE)

# Disable metadata preservation if needed (not recommended)
ces_without_metadata <- get_ces("2019", preserve_metadata = FALSE)

# Silent mode - no progress messages
ces_silent <- get_ces("2019", verbose = FALSE)

Working with Variable Metadata

CES datasets contain rich metadata including question text and value labels. The package preserves this metadata, which you can access:

# All metadata is preserved by default
ces_data <- get_ces("2019")

# Access variable label (question text)
attr(ces_data$vote_choice, "label")

# Access value labels
attr(ces_data$vote_choice, "labels")

# See all attributes of a variable
attributes(ces_data$vote_choice)

You can also examine metadata across the entire dataset with the examine_metadata() function:

# Get an overview of all variables with metadata
metadata_summary <- examine_metadata(ces_data)

# Show the first few entries
head(metadata_summary)

# Find variables with value labels about voting
voting_metadata <- examine_metadata(ces_data, 
                                  show_labels = TRUE,
                                  variable_pattern = "vote")

Working with Subsets of Variables

For many analyses, you may only need a subset of variables. The get_ces_subset() function allows you to select specific variables:

# Get a subset of variables by name
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)

Understanding Variables with Codebooks

CES datasets contain many variables with complex coding schemes. The create_codebook() function helps you understand these variables:

# Get 2019 data
ces_2019 <- get_ces("2019")

# Create a codebook
codebook <- create_codebook(ces_2019)

# View the first few entries
head(codebook)

# Find variables about a specific topic
library(dplyr)
voting_vars <- codebook %>%
  filter(grepl("vote|voted", question, ignore.case = TRUE)) %>%
  pull(variable)

# Use these variables in your analysis
voting_data <- get_ces_subset("2019", variables = voting_vars)

You can export the codebook to a CSV or Excel file:

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

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

You can also download the official PDF codebook documents:

# Download the official CES codebook PDF
download_pdf_codebook("2019")

# Download to a specific folder
download_pdf_codebook("2015", path = "~/Documents/CES_codebooks")

The package also allows downloading the raw data files directly:

# Download a single CES dataset
download_ces_dataset("2019", path = "~/Documents/CES_datasets")

# Download all available CES datasets to a folder
download_all_ces_datasets(path = "~/Documents/CES_datasets")

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

Example Analysis

Here’s a simple example of how to use the package to analyze voting patterns:

# Get 2019 data
ces_2019 <- get_ces("2019")

# Table of vote choice by province
if (requireNamespace("dplyr", quietly = TRUE)) {
  library(dplyr)
  
  # Create a table of vote choice by province
  vote_by_province <- ces_2019 %>%
    group_by(province, vote_choice) %>%
    summarize(count = n(), .groups = "drop") %>%
    pivot_wider(names_from = vote_choice, values_from = count, values_fill = 0)
  
  print(vote_by_province)
}

Conclusion

The ces package aims to make working with Canadian Election Study data more accessible to R users. By handling the downloading, storage, and initial processing of these datasets, researchers can focus on analysis rather than data wrangling.

For more information about the Canadian Election Study, visit the official website or refer to the dataset documentation.

Acknowledgments

This package accesses data from the Borealis Data repository, which serves as the official host for the Canadian Election Study datasets. We gratefully acknowledge Borealis Data for maintaining and providing access to these valuable datasets.

Important Disclaimer: This package is not officially affiliated with the Canadian Election Study or Borealis Data. Users of this package should properly cite the original Canadian Election Study data in their research publications according to the citation guidelines provided by the CES.

The package was developed with assistance from Claude Sonnet 3.7, an AI assistant by Anthropic, demonstrating how these tools can be used to create helpful resources for the research community.