qualtRics v2.0

0

Monthly downloads

0th

Percentile

Download Qualtrics Survey Data Directly into R

Qualtrics <https://www.qualtrics.com/about/> allows users to collect online data through surveys. This package contains convenience functions to pull survey results straight into R using the Qualtrics API. See <https://api.qualtrics.com/> for more information about the Qualtrics API.

Readme

qualtRics

Build Status AppVeyor Build Status CRAN STATUS CRAN LICENSE DOWNLOADSPM DOWNLOADSTOTAL CODECOV

This project contains an R package to download surveys from Qualtrics using the API.

Note that your institution must support API access and that it must be enabled for your account. Whoever manages your Qualtrics account can help you with this. Please refer to the Qualtrics documentation to find your API token.

Installation

To install this package, execute the following in R:

install.packages("qualtRics")

Or, if you want to install the latest development version, run:

install.packages("devtools")
devtools::install_github("JasperHG90/qualtRics")

Dependencies

All dependencies will be installed when you install qualtRics.

Updates

Periodically check this repository for updates and execute devtools::install_github("JasperHG90/qualtRics") to update.

Usage

Currently, the package contains three core functions:

  1. getSurveys() fetches a list of all surveys that you own or have access to from Qualtrics.
  2. getSurvey() downloads a survey from Qualtrics and loads it into R.
  3. readSurvey() allows you to read CSV files you download manually from Qualtrics.

It further contains three helper functions:

  1. registerOptions() stores your API key and root url in environment variables.
  2. getSurveyQuestions() retrieves a data frame containing questions and question IDs for a survey.
  3. qualtRicsConfigFile() prints information on how to make a .qualtRics.yml configuration file that stores your qualtRics API key, root url and other options in your working directory.

Note that you can only export surveys that you own, or to which you have been given administration rights.

Registering your Qualtrics credentials

There are two ways to register your Qualtrics credentials (your API key and institution-specific root url) and other options in R. As in earlier versions of the qualtRics package, you can register your credentials at the start of each R session:

registerOptions(api_token="<YOUR-API-TOKEN>", root_url="<YOUR-ROOT-URL>")

You can set some global options via the registerOptions() function:

  1. verbose: Logical. If TRUE, verbose messages will be printed to the R console. Defaults to TRUE.
  2. useLabels: Logical. TRUE to export survey responses as Choice Text or FALSE to export survey responses as values.
  3. convertStandardColumns: Logical. If TRUE, then the getSurvey() function will convert general data columns (first name, last name, lat, lon, ip address, startdate, enddate etc.) to their proper format. Defaults to TRUE.
  4. useLocalTime: Logical. Use local timezone to determine response date values? Defaults to FALSE.
  5. dateWarning: Logical. Once per session, qualtRics will emit a warning about date conversion for surveys. You can turn this warning off by changing the flag to FALSE. Defaults to TRUE.

You can change some of these options without having to pass the api_token or root_url parameters every time as long as you have registered the api token and root url previously:

registerOptions(verbose=FALSE, useLocalTime=TRUE)

The second method involves placing a configuration file called .qualtRics.yml in your working directory.

Using a configuration file

qualtRics supports the use of a configuration file to store your Qualtrics credentials. Executing qualtRicsConfigFile() returns information that explains how you can do this:

Copy-paste the lines between the dashes into a new plain text file, replace the values for the
api_token and root_url if they are not yet filled out. and save it in your working directory 
as '.qualtRics.yml'. Execute '?qualtRics::qualtRicsConfigFile' to view an explanation of the additional arguments. Visit https://github.com/JasperHG90/qualtRics/blob/master/README.md#using-a-configuration-file 
for more information.

--------------
api_token: <YOUR-API-TOKEN-HERE>
root_url: <YOUR-ROOT-URL-HERE>
verbose: TRUE
uselabels: TRUE
convertstandardcolumns: TRUE
uselocaltime: FALSE
dateWarning: TRUE
--------------

You can also call this function while passing api_token and root_url values to the function, in which case <YOUR-API-TOKEN-HERE> and <YOUR-ROOT-URL-HERE> will be replaced by your credentials. After saving the file, you can register your credentials by calling registerOption() without passing any parameters.

When you load the qualtRics package, it will automatically look for a .qualtRics.yml file in the working directory, in which case you don't need to call the registerOption() function to register your qualtRics credentials at the beginning of your session.

You can override your configuration file settings by calling registerOption() with the changes you want to make:

registerOptions(verbose=FALSE, useLabels=FALSE, root_url="myinstitution.qualtrics.com")

Setting up a config file

Open an existing R project or start a new one. Then, open up an empty text file:

Execute qualtRicsConfigFile(api_token="<YOUR-API-TOKEN-HERE>", root_url="<YOUR-ROOT-URL-HERE>") and copy-paste the text between the dashes to the empty text file:

Save the file as .qualtRics.yml and execute registerOptions() or restart your R session and execute library(qualtRics) to load the configuration file.

You can edit your configuration file by executing file.edit(".qualtRics.yml") in the R console.

Commands

Load the package:

library(qualtRics)

Register your Qualtrics credentials if required:

registerOptions(api_token="<YOUR-API-TOKEN>", root_url="<YOUR-ROOT-URL>")

Get a data frame of surveys:

surveys <- getSurveys()

Export a survey and load it into R:

mysurvey <- getSurvey(surveyID = surveys$id[6], 
                      verbose = TRUE) # You can set this option globally
                                      # or pass it to the function.

You can add a from/to date to only retrieve responses between those dates:

surv <- getSurvey(survs$id[4],
                  startDate = "2016-09-18",
                  endDate = "2016-10-01",
                  useLabels = FALSE) # You can set this option 
                                     # globally or pass it to this
                                     # function.

Note that your date and time settings may not correspond to your own timezone. You can find out how to do this here. See this page for more information about how Qualtrics handles dates and times.

You may also reference a response ID. getSurvey will then download all responses that were submitted after that response:

surv <- getSurvey(survs$id[4],
                  lastResponseId = "R_3mmovCIeMllvsER",
                  useLabels = FALSE,
                  verbose = TRUE)

You can filter a survey for specific questions:

# Retrieve questions for a survey
questions <- getSurveyQuestions(surveyID = surveys$id[6])
# Retrieve a single survey, filtering for questions I want.
mysurvey <- getSurvey(surveyID = surveys$id[6],
                      save_dir = tempdir(),
                      includedQuestionIds = c("QID1", "QID2", "QID3"),
                      verbose=TRUE)

Setting convertStandardColumns to TRUE converts common variables such as 'StartDate', 'EndDate' and Longitude, Latitude to their proper data types.

surv <- getSurvey(survs$id[5],
                  convertStandardColumns = TRUE,
                  useLabels = TRUE,
                  verbose = TRUE)

Note that dates are converted without a specific timezone in mind. You can specify your own timezone using these instructions.

You can store the results in a specific location if you like:

mysurvey <- getSurvey(surveyID = surveys$id[6], 
                      save_dir = "/users/jasper/desktop/", 
                      verbose = TRUE)

Note that surveys that are stored in this way will be saved as an RDS file rather than e.g. a CSV. Reading an RDS file is as straightforward as this:

mysurvey <- readRDS(file = "/users/jasper/desktop/mysurvey.rds")

You can read a survey that you downloaded manually using readSurvey:

mysurvey <- readSurvey("/users/jasper/desktop/mysurvey.csv")

To avoid special characters (mainly periods) in header names, readSurvey uses question labels as the header names. The question belonging to that label is then added using the sjlabelled package. Qualtrics gives names to these labels automatically, but you can easily change them.

Other information

For specific information about the Qualtrics API, you can refer to the official documentation.

Issues

Should you encounter any bugs or issues, please report them here

Requests

If you have a request (like adding a new argument), please leave it here

Changelog

[development branch]

  • *

[master branch]

  • registerOptions() now takes more arguments. User can now set global options. See qualtRicsConfigFile() for more information. Same options are now passed through ... in specific functions.
  • Added appveyor testing.
  • Added support for a configuration file to store API key and root url in the working directory.
  • registerApiKey() has been replaced by registerOptions(). This function stores both a user's API key and root url. Function also scans for a configuration file .qualtRics.yml that contains this information.
  • Added a new script called zzz.R. When the package is loaded, the .onLoad() function in this file scans the working directory for a .qualtRics.yml configuration file so that the user doesn't have to register this information manually.
  • Added a new function qualtRicsConfigFile() that prints instructions for the user on how to set up a configuration file to the R Console.
  • Removed the root_url parameter from all functions that required it.
  • Dates are now converted without a specific timezone.
  • Added a new function getSurveyQuestions() that allows the user to download a data frame containing question labels and IDs.
  • Added parameter includedQuestionIds so user can select questions they want to download. Need to use the QID value from getSurveyQuestions().
  • Updated examples and documentation of functions.
  • Added the following parameters to getSurvey():
    • seenUnansweredRecode: String. Recode seen but unanswered questions with a string value.
    • limit: Integer. Maximum number of responses exported. Defaults to NULL (all responses).
    • useLocalTime: Boolean. Use local timezone to determine response date values.
  • getSurveys() now retrieves > 100 results.

[v1.0]

  • Added a new function readSurvey(). This function is used in the getSurvey() function but will also work with surveys downloaded manually from Qualtrics. Standard columns (completed survey/startDate/endDate etc.) are now converted to their proper data types. HT Adrian Brugger & Stefan Borer.
  • User can only download surveys in CSV format, no longer in XML or JSON.
  • Added several new parameters to getSurvey() function. HT @samuelkaminsky & @eknud
    • LastResponseId: If used, only responses that were filled out later than this ID will be downloaded.
    • UseLabels: If TRUE, download will contain character labels. Else, download will contain choice labels.
    • StartDate: Only download responses after this date.
    • EndDate: Only download responses before this date.
  • Survey downloads should be faster now; getSurvey() no longer sleeps when checking download status. Also added progress bar.

[v0.03]

  • User can choose to save results directly in a folder through 'save_dir' parameter in getSurvey()
  • Results can now be requested in .csv, .json or .xml format. The packages jsonlite and XML are added to 'Suggests' in DESCRIPTION.
  • constructHeader() is now deprecated and should no longer be used. Instead, users need to call registerApiKey().
  • Added a new function registerApiKey() which saves the user's API key and header information in the tempdir() environment.

[v0.02]

  • Renamed 'base url' to 'root url' such that it corresponds to Qualtrics documentation.
  • The root url no longer requires API-specific endpoints. So e.g. 'https://leidenuniv.eu.qualtrics.com' now works for all functions. The API-specific endpoints are added in the functions itself.
  • Institution-specific root url is now required by getSurvey()

[v0.01]

  • Added first three functions (constructHeader, getSurvey, getSurveyIDs)
  • base_url parameter is now uniform across functions. Parameter is called 'root url' to bring it in line with Qualtrics documentation.

Functions in qualtRics

Name Description
getSurveys Retrieve a data frame of all active surveys on Qualtrics
qualtRicsConfigFile Prints an example of a qualtRics configuration file to the console.
getSurvey Export a survey and download into R
getSurveyQuestions Retrieve a data frame containing question IDs and labels
readSurvey Read comma separated csv file from Qualtrics.
registerOptions Register qualtrics API key, root url and other options
No Results!

Vignettes of qualtRics

Name
config_step1.png
config_step2.png
qualtRics.Rmd
qualtRics.html
qualtricsdf.png
No Results!

Last month downloads

Details

Type Package
URL https://github.com/JasperHG90/qualtRics
BugReports https://github.com/JasperHG90/qualtRics/issues
License GPL-3 | file LICENSE
Encoding UTF-8
LazyData true
RoxygenNote 6.0.1
VignetteBuilder knitr

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/qualtRics)](http://www.rdocumentation.org/packages/qualtRics)