-
Notifications
You must be signed in to change notification settings - Fork 8
/
README.Rmd
149 lines (106 loc) · 6.31 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit this file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
warning = FALSE,
message = FALSE,
comment = "#>",
fig.path = "man/figures/",
fig.retina = 3
)
```
# surveydown
<!-- badges: start -->
[](https://CRAN.R-project.org/package=surveydown)
[](https://cran.r-project.org/package=surveydown)
<!-- badges: end -->
> Note: This site only documents the {surveydown} R package - visit our main site at [surveydown.org](https://surveydown.org) for more information!
**surveydown** is a flexible, open-source platform for making surveys with [R](https://www.r-project.org/), [Quarto](https://quarto.org/), [Shiny](https://shiny.posit.co/), and [Supabase](https://supabase.com/).
<br>
<div align="center">
<img src='man/figures/technologies.png' width="550px" alt="image showing the three technologies used in the surveydown platform along with their logos: quarto (for designing surveys), shiny (for rendering the survey), and supabase (for storing data)"/>
</div>
<br>
The basic concept is:
1. Design your survey as a [Quarto](https://quarto.org/) document using markdown and R code.
2. Convert your survey into a [Shiny](https://shiny.posit.co/) app that can be hosted online and sent to respondents.
3. Store your survey responses in a [Supabase](https://supabase.com/) database (or any Postgres database).
The {surveydown} R package provides functions to bring this all together.
**See the [documentation](https://surveydown.org) to get started making your own surveydown survey!**
# Installation
### Install R & Quarto
- [R](https://CRAN.R-project.org/)
- [Quarto](https://quarto.org/)
We also recommend working with an IDE that has good support for R, Quarto, and Shiny. [RStudio](https://posit.co/products/open-source/rstudio/) is great, and we also like [VSCode](https://code.visualstudio.com/) and [Positron](https://github.com/posit-dev/positron).
### Install the {surveydown} R package
You can install {surveydown} from CRAN in your R console:
```{r}
#| eval: false
install.packages("surveydown")
```
or you can install the development version from [GitHub](https://github.com/surveydown-dev/surveydown):
```{r}
#| eval: false
# install.packages("pak")
pak::pak('surveydown-dev/surveydown')
```
Load the package with:
```{r}
#| eval: false
library(surveydown)
```
You can also check which version you have installed:
```{r}
#| eval: false
surveydown::sd_version()
```
# Background & Motivation
Most survey platforms (e.g., Google forms, Qualtrics, etc.) use drag-and-drop interfaces to design surveys, making version control and collaboration with others difficult. They're also not reproducible (others cannot easily reproduce a survey made on these platforms), and many require a paid subscription or license to use.
The surveydown package was designed to address these problems. As an open-source, markdown-based platform, all survey content is defined with plain text (markdown and R code) in a `survey.qmd` file and an `app.R` file that renders your survey into a Shiny app that can be hosted online. This makes your survey easy to reproduce, share, and version control with common tools like Git. The survey data collected is also owned by the survey designer in a separate Postgres database (we recommend Supabase as a free and open-source database provider).
If you're curious where this whole idea came from, check out this [blog post](https://www.jhelvy.com/blog/2023-04-06-markdown-surveys/), which outlines more on the general idea and the motivation for it. The post is now outdated in terms of the overall package design, but it provides something of an origin story and some of the motivation for developing this project.
# TODO List
This is a running list of things we're working on / have already added to the project:
- [x] show_if (conditionally display question)
- [x] skip_if (conditionally skip to page)
- [x] Set defaults for questions to not have any choices selected on launch.
- [x] Ability to embed markdown inside choice options (like mc buttons in formr)
- [x] Option for `ignore = TRUE` setting (database connection is ignored)
- [x] Automatically include timestamps on each page and question interaction in the data
- [x] Option to start at a designated page, e.g. `start_page = 'page_name'`
- [ ] A `show_all_pages = TRUE` argument to show all the pages and hidden questions when launched (e.g. to be able to print out the entire survey text). Could also be a `sd_print_survey()` function to print it to pdf.
- [x] Set up SCSS to be compatible with Quarto-supported bootstrap themes.
- [x] Include an optional progress bar.
- [x] Include input checks for `skip_if` and `show_if` (`question_id` exists, and data frame names are correct)
- [x] Required questions: post a popup if a question is required before allowing next button.
- [x] Add a `sd_get_data()` function so the survey designer can obtain the current survey results from inside the app: https://shinysurveys.jdtrat.com/articles/get-survey-data.html
- [x] Ability to pass url parameters, e.g. for tracking users.
- [x] Ability to redirect users to another url.
- [ ] Admin page w/password to preview / download data (see https://github.com/daattali/shinyforms)
- [ ] Form validation: Make sure the user inputs the correct type depending on the question type. (see https://shiny.posit.co/r/reference/shiny/0.14/validate.html)
- [ ] Leverage cookies so users who close the browser can start back where they left off.
- Question types:
- [x] Multiple choice (single choice)
- [x] Multiple choice (multiple choices)
- [x] Select
- [x] Text
- [x] Numeric
- [x] Multiple choice (button...like formr mc_button)
- [x] Text area
- [x] Date
- [x] Slider
- [x] Matrix
- [ ] Best worst
Resources / other related examples:
- [shinysurveys](https://github.com/jdtrat/shinysurveys)
- [shinyforms](https://github.com/daattali/shinyforms)
## [License Information](https://github.com/surveydown-dev/surveydown/blob/master/LICENSE.md)
## Citation Information
If you use this package for in a publication, please cite it! You can get the citation by typing `citation("surveydown")` into R:
```{r}
#| eval: false
citation("surveydown")
```