Giter VIP home page Giter VIP logo

qualtrics's Introduction

qualtRics

Authors: Julia Silge, Joseph O’Brien, Jasper Ginn
License: MIT

R-CMD-check CRAN_Status_Badge Codecov test coverage rOpenSci DOI DOI Downloads Total Downloads Project Status: Active – The project has reached a stable, usable state and is being actively developed.

Qualtrics is an online survey and data collection software platform. Qualtrics is used across many domains in both academia and industry for online surveys and research. While users can manually download survey responses from Qualtrics through a browser, importing this data into R is then cumbersome. The qualtRics R package implements the retrieval of survey data using the Qualtrics API and aims to reduce the pre-processing steps needed in analyzing such surveys. Currently, this package is the only package on CRAN that offers such functionality, and is included in the official Qualtrics API documentation.

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.

The authors of this package are not affiliated with Qualtrics, and Qualtrics does not offer support for this package. For specific information about the Qualtrics API, you can refer to the official documentation.

Installation

This package can be installed from CRAN:

install.packages("qualtRics")

Alternatively, you can install the development version with the remotes package (or alternatively, devtools):

install.packages("remotes")
remotes::install_github("ropensci/qualtRics")

Access your Qualtrics data

Currently, the package contains three core functions:

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

It also contains multiple helper functions, including:

  1. qualtrics_api_credentials() stores your API key and base URL in environment variables.
  2. survey_questions() retrieves a data frame containing questions and question IDs for a survey; extract_colmap() retrieves a similar data frame with more detailed mapping from columns to labels.
  3. metadata() retrieves metadata about your survey, such as questions, survey flow, number of responses etc.

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

Register your Qualtrics credentials

There are two important credentials you need to authenticate with the Qualtrics API. These are your API key and datacenter-specific base URL. The base URL you pass to the qualtRics package should look like yourdatacenterid.qualtrics.com, without a scheme such as https://. The Qualtrics API documentation explains how you can find your base URL.

You can store your API credentials QUALTRICS_API_KEY and QUALTRICS_BASE_URL in your .Renviron file for repeated use across sessions. The qualtRics package has a function to help with this.

library(qualtRics)

qualtrics_api_credentials(api_key = "<YOUR-QUALTRICS_API_KEY>", 
                          base_url = "<YOUR-QUALTRICS_BASE_URL>",
                          install = TRUE)

After you use this function, reload your environment (readRenviron("~/.Renviron")) so you can use the credentials without restarting R.

A simple Qualtrics workflow

Once your Qualtrics API credentials are stored, you can see what surveys are available to you.

surveys <- all_surveys() 

You can then download the data from any of these individual surveys (for example, perhaps the sixth one) directly into R.

mysurvey <- fetch_survey(surveyID = surveys$id[6], 
                         verbose = TRUE)

See the qualtRics vignette for more details on variable metadata, automatic conversion of variables, retrieving responses between specific dates or for specific survey items, and more.

Related work

  • Jason Bryer wrote an R package to work with the previous version of the Qualtrics API
  • QualtricsTools creates automatic reports in shiny.
  • qsurvey by James Dunham focuses on testing and review of surveys before fielding, and analysis of responses afterward.

Community Guidelines

This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. Feedback, bug reports (and fixes!), and feature requests are welcome; file issues or seek support here.

ropensci_footer

qualtrics's People

Contributors

chrisumphlett avatar dsen6644 avatar eknud avatar jasperhg90 avatar jeanetteclark avatar jmobrien avatar jntrcs avatar juliasilge avatar lyh970817 avatar maelle avatar markjrieke avatar mkearney avatar phoebewong avatar samuelkaminsky avatar seanchrismurphy avatar shaun-jacks avatar strengejacke avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

qualtrics's Issues

Return value 'getSurvey'

Currently:

  • Names are screwed up 'contains a lot of '
  • Data types are not clear.

Possibly:

  • Integrate tidyverse?

Warning about sjmisc

Thank you for Providing qualtRics to download survey information and responses. It is really a great tool. I've recently started getting this "Warning message:
This function will be removed in future versions of sjmisc and has been moved to package 'sjlabelled'. Please use sjlabelled::set_label() instead."

How will this affect how we use qualtRics? Will we need to do something different when downloading survey responses?
Thank you!

datewarning option in yml misspecified

Using the config file option the print out in the console datewarning option does NOT have the capitalized W as seen in your vignette. This spits an error saying the last line is unclear.

registerApiKey() - make so that user only has to do this once

Currently, the API key needs to be registered every session. The key is then saved in a temporary directory which gets deleted after the R session is terminated.

According to CRAN policies, R packages cannot change files on-disk. Specifically, this:

Packages should not write in the users’ home filespace, nor anywhere else on the file system apart from the R session’s temporary directory (or during installation in the location pointed to by TMPDIR: and such usage should be cleaned up). Installing into the system’s R installation (e.g., scripts to its bin directory) is not allowed.

But I'd like to save the results of the registerApiKey function to a local file because it makes the whole process a lot easier and prevents users from accidentally sending API keys along with R scripts. Perhaps create a separate data file with a placeholder file as a standard part of the package (i.e. a data set).

Data imported to R is not current

When importing survey data into R, is there a delay between what is current in the Qualtrics system and what is being downloaded?

Is it possible that the data is having problems importing? I enter the following into R:
loyperc <- getSurvey("SV_5nIBD5iRalXmdNz", useLabels=FALSE, useLocalTime=TRUE, dateWarning=FALSE, convertStandardColumns=TRUE, force_request=TRUE)
I get the following warning:
Warning message: In scan(file = file, what = what, sep = sep, quote = quote, dec = dec, : invalid input found on input connection 'C:/Users/cb37543/AppData/Local/Temp/RtmpeEgLjr/Loyalty perceptions (Jamie).csv'
I can only import 88 observations, when there is actually much more than this.

Invalid input error when running on Ubuntu

Hi,
I'm having an issue with qualtRics where when I run my script to download results of a survey to a specified directory, I get the error message below:

Warning message:
In scan(file = file, what = what, sep = sep, quote = quote, dec = dec,  :
  invalid input found on input connection '/tmp/RtmpVQGNZ1/<my_survey_name>.csv'

What is odd is that this is not the folder I indicate to save the file to, and I only get 14 rows of data read (out of ~1500).

I have changed the permissions of that folder, thinking that may help, and it hasnt.

If I put NULL in save_dir, I still get the same error.

Thanks in advance!

Lag time? Doesn't seem to be updating?

R newbie here.

Made changes to the survey in Qualtrics, changes not observed when I run the script in R. Is there a lag between making updates in Qualtrics and downloading the data using this package?

Request: Add arguments to getSurvey to set useLabels to true/false and to modify startDate/endDate

The default setting of true for useLabels pulls question response labels and not values, which can make some survey data harder to analyze. It would be useful to be able to choose whether the labels are outputted or not whenever the getSurvey function is run.

It is also useful to only export survey data from certain dates, and arguments for startDate and endDate would be helpful.

Thanks!

Set proper rules for file encoding

In #57 , Erulluvatar set file encoding to be UTF-8. While this is correct for current surveys, legacy files do not use this format. If I remember correctly, it also gives issues for special characters.

Perhaps the best thing to do is to write a little part about it in the README. I can't really test this myself anymore because ironically I don't have a qualtrics account. But if anyone can test special characters for me that'd be great!

With API token correct, but authentication still failed.

Hi Jasper,

I started to play your package. I used registerApiKey function to register my API and made sure it returned 'TRUE'. However, when i followed steps on vignette and tried to download one specific survey with its survey ID found in the account setting-Qualtrics IDs. It returned the below error:

Query returned status "401 - Unauthorized". Please check your code.

Can you add a user credential argument in your getsurveys functions. Thank you!

Error: package or namespace load failed for ‘qualtRics’:

I was terminated my R terminal and now I am receive the following error:

Error: package or namespace load failed for ‘qualtRics’:
.onLoad failed in loadNamespace() for 'qualtRics', details:
call: yaml.load(paste(readLines(input, encoding = "UTF-8"), collapse = "\n"),
error: Scanner error: while scanning a simple key at line 4, column 1could not find expected ':' at line 5, column 1

Any ideas?

Downloading Survey Responses Since last Download

Jasper,

I really appreciate the work you have provided for us in this package. It is a wonderful tool. It would be a great help if it was possible to have either the datetime or last survey id retained in qualtRics or the .yml at the the end of a download of a specific survey so it could be added to a new getsurvey request. This would work great with scheduled downloads so only new responses were download. We collect responses from our surveys daily or weekly and this would allow the process to be automated without downloading all the responses again.

Thanks for considering this.

Delkine

Have you seen this error before?

Just wondering if you have seen this error/ warning message before.
Do you know what it is? Do I need to fix it?

Sincerely,

W Christopher King
Polynesian Cultural Center
[email protected]

|=================================================================| 100%
Warning message:
In scan(file = file, what = what, sep = sep, quote = quote, dec = dec, :
invalid input found on input connection 'C:/Users/SDR-RE~1/AppData/Local/Temp/Rtmpgre0N8/Mindshare English v21.csv'

Avoiding API#

Hi Jasper,

Thanks for creating this tool.

Is it possible to avoid the API Number or get around it? I would love to be able to use this but my organization does not have access to our API numbers in the Qualtrics platform, thus limiting my ability to use this tool.

Thank you.
Neil

Unknown Warning

I'm receiving the following warning when I us qualtRics to download a survey.
"Warning message:
In scan(file = file, what = what, sep = sep, quote = quote, dec = dec, :
invalid input found on input connection 'C:/Users/del/AppData/Local/Temp/RtmpQZ7nvM/Mindshare English v21.csv'"

Can you point me some help with this? I'm also not getting all the respondent surveys in the download.

Del

authentication error

Hi
Thanks for the great package.

getSurveys() keeps telling me
Qualtrics API raised an authentication (401) error - you may not have the required authorization. Please check your API key and root url.

Well, obviously that seems (and most likely is) very stupid of me. However, I followed the documentation and registered using:
registerOptions(api_token="MYTOKEN", root_url="ROOTURL")

I also consulted the API Docs of Qualtrics and can't come up with a different rooturl... Do you have any advice on this?

Thanks in advance.
Tom

What was working how throws a 400 error

This code has worked for quite a while but now throws a 400 error. Here is a snippet of the code where the error shows up.

surveys <- getSurveys()
#####---------------------------------------------------------------------------------------------------------
#####---------------------------------------------------------------------------------------------------------
lastid1.rds <-"R_2D5NheqdikcY0p2" ## Replace ResponseID with chosen ResponseID when it is known.
lastid2.rds <-lastid1.rds
#####---------------------------------------------------------------------------------------------------------
mysurvey <- getSurvey(surveyID = surveys$id[9],

  •                   save_dir = "/users/del/dropbox/Polynesian_Cultural_Center/Shared_PCC/Qualtrics_Data/",
    
  •                   lastResponseId = lastid2.rds,
    
  •                   verbose=TRUE,
    
  •                   uselabels=FALSE,
    
  •                   force_request = TRUE)
    

Error in qualtRicsResponseCodes(res, raw = raw) :
Qualtrics API raised a bad request (400) error - Please report this on https://github.com/JasperHG90/qualtRics/issues

#####-------------------------

Any suggestions?

too many columns error

When using the getSurvey function I get the following error for one particular survey:

Error in read.table(file = file, header = header, sep = sep, quote = quote,  : 
  more columns than column names

I don't know how to debug this error. Any suggestions?

New Error

Beginning Saturday I began experiencing problems running qualtRics that I had never seen before. I checked your documentation and it looks like you have implemented some new features and made several changes. It looks like the changes will be nice improvements but for now I'm having issues that I can't find any documentation about. I installed your latest version of qualtRics. I have created registerOptions () file and placed it in my wd. When I run my whole script I get several errors. It appears that the regiserOptions file is not being read. When I put enter my API token and root_url directly in the registerOptions() command it seems to work now.

Error when running script in taskscheduleR

When I run my script following your examples from Rstudio I have no problem getting the script to run and create a *.csv file with the responses to my survey. However when I try to automate its execution and run it from taskscheduleR as an Addin called from Rstudion I get the following error message in the log file and I get no output. Can you help me fix this. Other scripts I run work just fine using the same process.

"Installing package into 'C:/Users/del/Documents/R/win-library/3.4'
(as 'lib' is unspecified)
Error in contrib.url(repos, "source") :
trying to use CRAN without setting a mirror
Calls: install.packages -> contrib.url
Execution halted"

Thank you!

Del

400 error with getSurvey

Error in qualtRicsResponseCodes(res) :
Qualtrics API raised a bad request (400) error - Please report this on https://github.com/JasperHG90/qualtRics/issues

I get the error with both the main package and development version. Was working fine before I updated today, I think the last time I downloaded was late December. getSurveys works as intended.

documentation mistake

In the Vignette, under Commands, the example documentation for getSurveys() should have a URL that ends with '/v3/surveys' rather than '/v3/responseexports/'.

Possible Encoding Issue with Windows 10

Hi Jasper,

I tried to getSurvey from my qualtrics, but got the following error message. My platform is Windows 10 Professional Simplified Chinese. The same code works under Ubuntu 16.04 LTS. So I guess it's probably an encoding issue.

Thanks.

Best,
Sean

mysurvey.2 <- getSurvey(surveyID = surveys$id[2])
|======================================================================================| 100%
Error in read.table(file = file, header = header, sep = sep, quote = quote, :
no lines available in input
In addition: Warning messages:
1: In readLines(file, skip) :
invalid input found on input connection '.../China Survey.csv'
2: In readLines(file, skip) :
incomplete final line found on '.../China Survey.csv'

Assert That Logical Error with registerOptions

Hey Jasper. I am very eager and excited to try out the qualtrics API integration package. However, I am stuck on step 1. I run the following code with my token and institution url:

registerOptions(api_token = "my-api-token",
root_url = "montclair.co1.qualtrics.com")

But it throws the error:
Error: assert_that: assertion must return a logical value

I have tried with config file and changing the url, but I continue receiving this error. I feel like I'm missing something obvious.

Bad Request (400) Raised

Japser,

After almost 2 weeks of error free use of script I'm now repeatedly getting a bad request (400) error when it is run. The script is unchanged. Has anything changed with qualtRics or with the API that would cause this error to be raised now? Do you need to see the whole script or part of the script?

Delkine

Question on "registerOptions"

When I tried to initialize the registerOptions, it pops up "Error: assert_that: assertion must return a logical value"

Code:
registerOptions(api_token="[token with length of 40]",
root_url="mit.co1.qualtrics.com")

Thanks!

Get contact lists?

Hi Jasper,

Thanks for building this package for us R users.
I was wondering if there are any plans to implement a way to get contact list to a particular survey?

Sincerely,

Kai

new line in column names breaks readSurvery

We found that surveys that use new lines in the questions break the readSurvey function.
The problem is, that read.csv (and read.table as well as the readr library implementation) ignore the quote = "\"" option when a skip = 2 or skip = 3 parameter is set.
As a result the read function slices off the questions row somewhere in the middle when first importing just the table body using skip.

Do you have any idea how to circumvent that?
One workaround is to export the csv using the "strip new lines" option in qualtrics.
So if this is the only way to handle the situation, we should put that in the Readme.

Ability to use Export Tag

Not sure if this already exists, but is it possible to use the export tags set in Qualtrics instead of the long field name as the column headers?

do.call error

registerApiKey("mytoken")
[1] TRUE

surveys <- getSurveys(root_url="https://ohio.qualtrics.com")
Error in do.call(rbind.data.frame, content(res)$result$elements) :
second argument must be a list

Any idea what could be going on here, Jasper?

Better error handling

Better error handling in following situations:

  1. User registers wrong root url returns:

screen shot 2017-06-20 at 11 29 49

  • Check if root url ends with '.qualtrics.com'
  • Return more informative message
  1. User executes getSurveys() before registering any options
    If a user loads library & doesn't have a config file, and the user then calls 'getSurveys()' straight away (without registering options), the user will see an unclear error because code contains ifelse statements. Best set options when library is loaded. These will then be overwritten straight after but that's OK.

  2. Incomplete final line
    #37 notified that readLines throws error if .qualtRics.yml does not contain empty line at the end of file (on Windows). Consider turning qualtRicsConfigFile() into function that writes configuration file for user.

Max 100 obs. with getSurveys

Hi Jasper,

It seems the getSurveys option stops at 100 observations. Is it possible to adjust this? We have a lot more, and I also don't know how it selects the 100 that do show up.

Kind regards, Daniël

Error in registerOptions()

I ran into an error when trying to use registerOptions() to configure my qualtrics account. I tried to both specify the API token and root_url within the function or use the yml file in the working directory.

The error seems to be related to the assert_that() function. Below is the error.

Error: assert_that: assertion must return a logical value
stop("assert_that: assertion must return a logical value", call. = FALSE)
check_result(res)
see_if(..., env = env)
assertthat::assert_that(!is.na(root_url) | Sys.getenv("QUALTRICS_ROOT_URL") != "", msg = "'root_url' parameter must either be specified in the .qualtRics.yml configuration file or passed to the 'registerOptions' function. To view an example of a configuration file, execute 'qualtRicsConfigFile()'.")

I didn't have an issue of configuring my account when I use the same token and URL

  1. the older version of the package with the registerApiKey() function
  2. in HTTP requests (with httr package)

Let me know if you need any other info, thanks!

"incomplete final line" in `registerOptions` in `qualtRics 2.0`

I've used qualtRics 1.0 without issue (and really like the R API!). Yesterday, when setting up a co-worker's computer, I noticed 2.0 is out on CRAN. I adapted the code I had used for qualtRicsConfigFile and created the .qualtRics.yml file as instructed into a new plain text file with Notepad (Windows machine). Unfortunately, when I ran registerOptions it threw an error: incomplete final line. So, it found the file OK but presumably hit a harmless error on readLines. Fortunately I was able to download the data by reading through registerOptions and setting the relevant options and environment variables.

Sys.setenv(QUALTRICS_ROOT_URL = "https://someorganization.qualtrics.com")
Sys.setenv(QUALTRICS_API_KEY = "ASDFqwertyNOTanAPIkey")
options(QUALTRICS_VERBOSE = T, QUALTRICS_USELABELS = T,
        QUALTRICS_CONVERTSTANDARDCOLUMNS = T,
        QUALTRICS_USELOCALTIME = F)

Maybe it's just a notepad issue, not sure. Wanted to let you know. Wonder if it wouldn't be easier to generate the yml file for the user...

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.