Skip to contents

An end-to-end survey research workflow with svmkR

svmkR.Rmd

Installation

To install the stable version of svmkR from GitHub:

# install.packages("devtools")
devtools::install_github("soubhikbarari/svmkR")

To install the development version of svmkR from GitHub:

# install.packages("devtools")
devtools::install_github("soubhikbarari/svmkR@dev")

Authentication

Before going any further you’ll need an OAuth token, and for that you’ll need to set up an app on the SurveyMonkey Developer portal.

  1. Navigate to SurveyMonkey Developer portal. Log in to SurveyMonkey in your browser, then navigate to https://developer.surveymonkey.com/apps.

  2. Create an app. It should be private, and you should enable the relevant scopes: Create/Modify Surveys, View Surveys, View Collectors, View Contacts, View Responses, View Response Details. You don’t need to click “deploy”, as long as the setting selected have been updated you’re set.

  3. Copy access token. Look at the settings page for your app and take note of the “Access Token” field, which should contain a very long character string.

  4. Add to R environment. Add the SurveyMonkey account’s OAuth token to your .Rprofile file. To open and edit that file, run usethis::edit_r_profile(), then add a line like this: options(sm_oauth_token = "MY-OAUTH-TOKEN-FROM-STEP-3").

  5. Test that it works. Restart R for changes to take effect. If this is all set up successfully, the token will print when you run getOption("sm_oauth_token"). Guard this token: don’t share it and don’t commit it in any repository.

Workflow

The following demonstrates how to write a SurveyMonkey workflow that covers four major steps in survey research: survey creation, response downloading/parsing, weighting, and banner creation.

Create a survey

When creating a survey, you typically start with writing up the questionnaire. Once this is done you have two options:

  1. Program the survey in the SurveyMonkey platform itself
  2. Automatically parse your questionnaire and upload to SurveyMonkey with svmkR.

The second option is possible with the help of QDOC, a questionnaire syntax we have developed to mark up your questionnaire document and make it machine readable. See the related vignette("qdocs") for details.

A example QDOC (written in the simple, less verbose format) might start off like this:

1. How familiar are you with SurveyMonkey?
[[Choices]]
Very familiar
Somewhat familiar
Not so familiar
Not at all familiar

2. How well do each of the following terms apply to SurveyMonkey? [[Matrix]]
[[Rows]]
High-quality
Innovative
Trustworthy
Fun
Easy to use
Fast
Flexible
Powerful
Cost-efficient
[[Columns]]
Very well
Somewhat well
Not so well
Not at all well

See data("qdocs") for more examples.

Once your questionnaire is marked up with the QDOC, you can read it in:

# if it's a local file
qdoc <- read_qdoc(file = "my_qdoc.txt")

# if it's a Google Doc
qdoc <- read_qdoc(gdoc = my_qdoc_url)

# if it's a character string
qdoc <- read_qdoc(text = my_qdoc)

Check that it conforms to expectation by printing it.

print(qdoc)

This should step through each question and show you the format that it has been parsed into. If there are any unexpected results, check any warnings raised from read_qdoc or revise the original QDOC.

Upload your survey

Once you’re happy with your QDOC, you can go ahead and upload it to your account with a particular title.

upload_qdoc(qdoc, title = "My Survey")

Browse your surveys

To find the ID number of your survey in your account, you can browse your surveys like this:

surveys <- browse_surveys(200) # see your most recent 200 surveys

An easy way to retrieve the ID number is to run View(surveys) and start typing the name of the survey you want into the search window at the top right of the RStudio data.frame viewer.

That will get you the survey’s ID number. Copy it.

Download survey responses

Once you’ve fielded your survey (currently can only be done on the SurveyMonkey platform), download the survey responses by first downloading the raw survey:

a_survey_obj <- fetch_survey_obj(123456789) # your survey's ID goes here

This first step returns a list of metadata about the survey. To actually download and parse the responses, use the following:

survey_df <- parse_survey(a_survey_obj)

That will give you a tidy data.frame with all of your responses.

In the future you can run it all as one command:

survey_df <- fetch_survey_obj(123456789) %>%
  parse_survey()

Estimate margin of error

There are two twin functions you can use to estimate margin of error (MOE) for your survey.

  • Estimate the MOE using an asymptotic formula (esti_moe())
  • Simulate the MOE using non-parametric bootstraps (simu_moe())

Both incorporate any weights estimated for the survey.

Here’s an example using some dummy data included in the package:

data(ev22)

esti_moe(ev22$weight_genpop)
simu_moe(ev22$weight_genpop)

Weight your survey

You may be interested in re-weighting your survey responses to a specific target population. To see a list of available populations, you can run:

Once you find a named target suitable for your application you can read it into a target object. You can then print it out and it will step through each distribution, either marginal (one variable) or joint (multiple variables), specified in the target.

tgt <- get_target("us_genpop_acs19")
print(tgt)

Note: if you have an existing list of joint and marginal distributions, you can also use this as your weighting target.

We can then simply run weight_to using our survey dataframe (the smda23 example dataset used below) and our population target.

data("smda23")
wtd <- weight_to(smda23, target = tgt)

A bunch of informative output will be displayed when running this function that should help you determine whether (a) the automated mapping of columns in the survey dataset to variables in the target object was successful and (b) the quality of your weights is satisfactory.

For more helpful guidance on how to weight your surveys, see vignette("weights").

Create banners

Banners are the bread and butter of the SurveyMonkey Research Insights Team.

To see how the svmkR package can do this, check out the examples in make_banners() and write_banners().

API Considerations

Your account will likely be limited to 500 hits per day to the API. This package will print reminders of how many calls you have left in the day.

The main thing to keep an eye on is respondent counts; as only 100 responses can be fetched per API call, a survey with X respondents will make at least X/100 calls to the API.