Skip to main content

clusteR Documentation

2 Quick Start

2.1 Installation

Run the following commands in your R console to install clusteR:

install.packages("devtools")
devtools::install_github("alectries/clusteR")

You can update clusteR by running devtools::update_packages() and selecting the option for clusteR.

2.2 Setting up

Each survey should be run in a unique folder. clusteR will set up a survey environment in this folder with a custom file structure. You may add and modify files and folders within this structure as needed. clusteR will ignore files that it did not create or does not need.

To load clusteR, run:

library(clusteR)

R is case-sensitive, so the capital R matters! On first load in a new folder, clusteR will give a warning:

Warning message:
clusteR environment not configured!
! Please run clusteR::setup() to set up your survey environment.

You will need to run setup() to create the survey environment in your working directory. Use either setwd() or create an R project in RStudio in your desired folder before running setup().

2.3 Workflow

Your project will likely go through three phases: setup, collection, and data analysis. Below is an overview of the functions you are most likely to use in each phase.

2.3.1 Setup and sampling

  • make_clusters to randomly select U.S. Census blocks, weighted by their population, to serve as clusters.
    • view_map to view a simple graphical map of sampled clusters.
  • setup to set up the clusteR environment.
    • setup_get_alc to establish a connection to an Alchemer survey.
    • setup_get_csv to establish a connection to a CSV file with survey response data.

2.3.2 Collection

  • make_email to generate a PDF or CSV with information
    needed to send emails to cohort members.
  • make_mailing to generate a PDF or CSV with information needed to send physical mailings to cohort members.
  • make_phone to generate a PDF or CSV with information needed to make calls to cohort members.
  • make_groups to automatically group clusters by physical proximity and output a file to make manual adjustments for door-to-door interviews.
  • make_walkmap to regenerate the cluster map, taking into account manual adjustments.
  • make_walklist to generate PDF walk lists for groups assigned by make_groups, taking into account manual adjustments.
    • custom_walklist to save a starter custom template for walk lists.
  • update_cohort to obtain, join, and view updated cohort information from the data source and the Editor.
    • update_confirm to apply updates to the cohort file.
    • view_cohort to view the full cohort file.
    • search_cohort to view filtered results from the cohort file.
    • restore_cohort to restore an archived version of the cohort file.
  • view_progress to generate a report on survey completion by cluster.
  • get_data to download and archive survey responses from a pre-specified data source.
    • get_alc, generally used by get_data, to retrieve data from Alchemer.
    • get_csv, generally used by get_data, to retrieve data from a CSV.

2.3.3 Data analysis

  • clean_data to clean downloaded, standardized survey data.
    • clean_weight, within clean_data, to calculate and save survey weights.
  • view_topline to analyze responses and view or export overall results.
    • custom_topline to save a starter custom template for topline reports.
  • view_breakdown to analyze responses and break them down by a stratification variable.
    • custom_breakdown to save a starter custom template for breakdown reports.
  • export_cohort to export the cohort file to a CSV.
  • export_data to export survey responses to a CSV.