forked from ropensci/qualtRics
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
116 lines (74 loc) · 6.44 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# qualtRics
**Authors:** [Julia Silge](https://juliasilge.com/), [Jasper Ginn](https://jasperhg90.github.io/)<br/>
**License:** [MIT](https://opensource.org/licenses/MIT)
<!-- badges: start -->
[](https://github.com/ropensci/qualtRics/actions)
[](https://cran.r-project.org/package=qualtRics)
[](https://codecov.io/gh/ropensci/qualtRics)
[](https://github.com/ropensci/software-review/issues/192)
[](https://zenodo.org/badge/latestdoi/70817337)
[](https://doi.org/10.21105/joss.00690)
[](https://CRAN.R-project.org/package=qualtRics)
[](https://CRAN.R-project.org/package=qualtRics)
[](https://www.repostatus.org/#active)
<!-- badges: end -->
[Qualtrics](https://www.qualtrics.com/) 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](https://api.qualtrics.com/docs/) 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](https://api.qualtrics.com/docs/).
## Installation
This package can be installed from CRAN:
```{r eval=FALSE}
install.packages("qualtRics")
```
Alternatively, you can install the development version with the [remotes](https://cran.r-project.org/package=remotes) package (or alternatively, [devtools](https://cran.r-project.org/package=devtools)):
```{r eval=FALSE}
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 helper functions:
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 **institution-specific base URL**. The base URL you pass to the qualtRics package should either look like `yourdatacenterid.qualtrics.com` or like `yourorganizationid.yourdatacenterid.qualtrics.com`, without a scheme such as `https://`. The [Qualtrics API documentation](https://api.qualtrics.com/instructions/) 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.
```{r, eval=FALSE}
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.
```{r, eval=FALSE}
surveys <- all_surveys()
```
You can then download the data from any of these individual surveys (for example, perhaps the sixth one) directly into R.
```{r, eval=FALSE}
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](https://github.com/jbryer/qualtrics) wrote an R package to work with the previous version of the Qualtrics API
- [QualtricsTools](https://github.com/emma-morgan/QualtricsTools) creates automatic reports in shiny.
- [qsurvey](https://github.com/jamesdunham/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](https://github.com/ropensci/qualtRics/blob/master/CONDUCT.md). 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](https://github.com/ropensci/qualtRics/issues).
[](https://ropensci.org)