In ndphillips/ShinyPsych: An easy way to program psychology experiments using Shiny

About ShinyPsych

General

ShinyPsych is an R package designed to help implementing experiments in shiny apps. If you don't know about shiny yet, we recommend checking out the shiny webpage which contains many great tutorials and explanations on what shiny is and how to build apps. Shiny apps are, in their usual form, not suitable to implement experiments and surveys because they are designed to dynamically display information on one page, possibly with some page navigation by using different panels. In an experiment or survey, however, one typically wants to display items on different pages to which the participant can not switch back and forth but has to follow a predefined order of pages. These tutorials show you how to do this and how to use different functions implemented in ShinyPsych, designed to facilitate programming an experiment. Although we tried to simplify programming the app, you still need to now how to work with R. If you have no experience of using R you best go through some tutorials (e.g. with YaRrr! The Pirate's Guide to R, a free E-book, written by Nathaniel Phillips or the the RStudio online tutorial).

Note that we're still developing ShinyPsych and currently have the first package version. Therefore it is well possible that you will find some bugs in the code or typos in the default lists. If so feel free to write us or to open an issue on the ShinyPsych Github page. Before using ShinyPsych e.g. for a study, make sure to check that everything is displayed and saved the way you want it to be.

If you have questions about ShinyPsych you can write us at [e-mail]. or [e-mail].

Structure

You'll find that every task or page created with ShinyPsych includes more or less the same steps in the code. For all these things (and others) we have functions in ShinyPsych. First you read in the appropriate css and javascript files. Then you specify the list or file from which the pages should be created or outcomes be sampled from. Thirdly, you give this file or list to a function that prepares everything to be in the correct format. When the respective page is called a function takes that list and creates the html pages that are then displayed by shiny. The last two steps are the page navigation, i.e. you set up code to control which page is displayed when and in the end save the data to dropbox or your computer. This is the general framework to set up any survey or task or combination of them with ShinyPsych.

Performance

One important thing about R shiny is that there are some performance issues for large apps hosted online. Sometimes crashes occur. Then the user is shown a message that the connection to the server was lost and if one then clicks the refresh button one is sent back to the first page. Therefore, if you plan to run your experiment online with many participants, be sure to thoroughly test your app. Heres a link to an article we found on this issue, that shows that also others who have thoroughly developped apps experience this issue. We made the same experience as they did with tuning the app settings on shinyapps.io to be not trivial as they put it. That being said, it is possible to gather relatively large amounts of data using shiny apps. We gathered data of around 500 participants. To do this, however, we ran several batches of participants and split the experiment up in different apps linked with each other. However, some crashes still occurred.

If you want to use ShinyPsych to run experiments in the lab, we recommend running the app locally on your computer from an R session and not hosting it online. This will reduce the crashes to an absolute minimum and there will never be issues with requests of different users having to be handled simultaneously.

Get ShinyPsych

If you'd like to use ShinyPsych, download and load it via

devtools::install_github("mdsteiner/ShinyPsych", build_vignettes = TRUE)
library("ShinyPsych")

To see some examples working, you can either look at our apps by clicking on the links in the tutorial sections, or make use of ShinyPsych's callApp()function to which you can give the name of the app you want to see and whether it should be run or if the code should be shown in a new editor tab.

library("ShinyPsych")

# show survey app code
callApp("Survey", "show")

# run app locally in your browser
callApp("Survey", "run")

Saving Data

To Dropbox

In all the surveys and tasks data is generated. You can save this data locally on your computer if you run the app locally. If you run it on a server an easy solution is to use dropbox to store your data. This is why we implemented the possibility the possibility to read and write data from and to dropbox in our functions. To do this we use the rdrop2package. To use this functionality you need to have dropbox access token saved in a file that you can give to our functions. Creating your access tokens is pretty easy, just follow this procedure:

install.packages("rdrop2")                 # install rdrop2 package
droptoken <- rdrop2::drop_auth()           # Will open a browser and ask you to login
saveRDS(droptoken, file = "droptoken.rds") # Save token as droptoken.rds

Locally

You can save data locally to your computer by just giving the local path to the saveData() function.

E-Mail

You can save data by sending an email to your adress. For this to work, you need to specify the mail arguments (arguments starting with "mail") of saveData(). Make sure that this works with your mail server! We've tried some and not all of them worked (gmail worked). Please note, that we didn't try this with a large number of mails, so we don't know yet how this works if you expect many mails to be sent in a short time.

Tutorial links

| Vignette Link | Description | |-------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | ShinyPsych - Survey | A short guide on creating surveys and html pages from textfiles using ShinyPsych. | | Implementing a survey - a tutorial | Full code tutorial on implementing a survey in ShinyPsych. | | Check id tutorial | Full code tutorial on implementing an id check in a shiny app. | | Create Textfiles for ShinyPsych apps | A guide on creating the textfiles to then build the survey and text pages with. | | ShinyPsych - BART | A short guide on implementing the BART using ShinyPsych. | | Implementing the BART - a tutorial | Full code tutorial on implementing the BART using ShinyPsych. | | Create files with BART distribution info | Code tutorial on how to create the lists to control the BART. | | ShinyPsych - Bandit | A short guide on implementing the Bandit using ShinyPsych. | | Implementing the bandit task - a tutorial | Full code tutorial on implementing the Bandit task using ShinyPsych. | | ShinyPsych - Delay Discounting | A short guide on implementing the Delay Discounting task using ShinyPsych. | | Implementing the Delay Discounting task - a tutorial | Full code tutorial on implementing the Delay Discounting task using ShinyPsych. | | Create files with DD trial info | Code tutorial on how to create the lists to control the Delay Discounting task. | | ShinyPsych - Decisions from Description | A short guide on implementing the DfD task using ShinyPsych. | | Implementing the Decisions from Description task - a tutorial | Full code tutorial on implementing the DfD task using ShinyPsych. | | Create gamble files | Tutorial on how to create the gamble lists for the DfD and DfE tasks. | | ShinyPsych - Decisions from Experience | A short guide on implementing the DfE task using ShinyPsych. | | Implementing the Decisions from Experience task - a tutorial | Full code tutorial on implementing the DfE task using ShinyPsych. |

Create HTML Pages in ShinyPsych

ShinyPsych comes with functions to prepare and display pages containing text and some input formats available via shiny. This allows you to display instructions or let the participant answer a survey.

Surveys and Text

Surveys are one of the most important methods of gathering informations in studies. ShinyPsych provides a way of including surveys and instructions in an app by simply giving it a text file with the survey. To learn how to format such a text file check out section How to Create the txt Files. Click here for more information on surveys in ShinyPsych

Check Id

The function to display survey and text pages also includes the possibility of an id check, i.e. it is checked whether the id entered by the participant is already in a database of ids. This gives you the possibility to prevent participants from repeated participation. Here's a Tutorial on How to Include an Id Check

How to Create the txt Files

An important part of creating apps with ShinyPsych is to create the files containing the info on creating pages. You can put whole surveys in one file and use this to display the whole survey in the app. Here's a Tutorial on How to Create these Files

Tasks Implemented in ShinyPsych

Currently implemented in ShinyPsych are five different tasks often used in decision making research. You can find a tutorial on how to set up each task below.
Note that all tutorials will explain the whole app without relying on other tutorials here, except the one to create pages, which would take too much space to repeat several times. If you go through several of the tutorials, you will therefore find most things covered multiple times...

Balloon Analogue Risk Task (BART)

Task Tutorial

The bart is a behavioral measure of risk taking developped by @lejuez2002evaluation. In the bart, participants are presented a balloon they have to pump up. With each pump it becomes more likely that the balloon will explode. The more bigger the balloon is pumped, the more money you win given that it does not explode by the last pump. You could either use a single balloon, i.e. you can still have multiple trials but only one balloon type with a specific underlying distribution, or multiple balloons with different underlying distributions. Click here for more information on the BART in ShinyPsych.

If all participants should see the same balloons, or if you have prespecified pop values you want to use, you can create your own list of pop values and load them in, as explained in this tutorial.

Delay Discounting Task

Task Tutorial

The delay discounting (DD) task is designed to measure a persons impulsivity/ ability to delay rewards @richards1999delay. In DD a person is presented two outcomes, each of which he can receive after an indicated time period. The normal structure is that one is presented with a smaller outcome which he could get sooner, or a larger reward which he could get later. The person then has to indicate his preference by choosing one of the outcome-time pairs. Click here for more information on the DD task in ShinyPsych.

How to Create the DD Lists

In the DD task it's convenient to create a txt file with the variables and load this file into the app with the functions provided by ShinyPsych. For this to work, the file must be in a specific form. Click here for a short explanation with an example on how to set up the file.

Decisions from Description Task

Task Tutorial

Decisions from Description (DfD) are choice problems in the form of lotteries in which participants are presented different options with oucome-probability pairs and then have to indicate their preference for an option. ShinyPsych supports two to four different options with up to six outcomes each (you could have more outcomes but then you'd need to change the css file to change the boxes size). Most studies that used these kinds of choice problems let participants choose between two options. We included some default gamble lists in ShinyPsych that are relatively often used. Sometimes the lists are contain only a subset of the gambles used in the study [e.g. @glockner2012cognitive] or are a composition of gambles from several studies (the Birnbaum gambles). Some of the lists contain additional information you could use such as gamble types [the @brooks2014risk list] or paradox type they belong to [the @birnbaum2008new list]. Available default lists are gambles from @birnbaum2008new, @brooks2014risk, @glockner2012cognitive, @hertwig2004decisions, @loomes2002microeconometric and @rieskamp2008probabilistic.

Click here for more information on Decisions from Description in ShinyPsych.

How to Create the Gamble Lists

In the DfD and DfE tasks it's convenient to create a txt file containing the gambles and load this file into the app with the functions provided by ShinyPsych. For this to work, the file must be in a specific form. Click here for a short explanation with an example on how to set up the file.

Decisions from Experience Task

Task Tutorial

Decisions from Experience (DfE) are choice problems in the form of lotteries in which participants are presented different options with oucome-probability pairs and then have to indicate their preference for an option. In contrast to Decisions from Description however, these outcome-probability pairs are not stated explicitly (i.e. numerically), but have to be learned by the participant through sampling of the options. Each time a participant samples from an option, one of the outcome is drawn with it's associated probability and shown to the participant. One can sample as long as one wishes and then make a decision for one of the options. ShinyPsych supports two to six different options with no limit to outcomes each. Most studies that used these kinds of choice problems let participants choose between two options. We included some default gamble lists in ShinyPsych that are relatively often used. Sometimes the lists are contain only a subset of the gambles used in the study [e.g. @glockner2012cognitive] or are a composition of gambles from several studies (the Birnbaum gambles). Some of the lists contain additional information you could use such as gamble types [the @brooks2014risk list] or paradox type they belong to [the @birnbaum2008new list]. Available default lists are gambles from @birnbaum2008new, @brooks2014risk, @glockner2012cognitive, @hertwig2004decisions, @loomes2002microeconometric and @rieskamp2008probabilistic.

Click here for more information on Decisions from Experience in ShinyPsych.

How to Create the Gamble Lists

In the DfD and DfE tasks it's convenient to create a txt file containing the gambles and load this file into the app with the functions provided by ShinyPsych. For this to work, the file must be in a specific form. Click here for a short explanation with an example on how to set up the file.

n Armed Bandit Task

The Bandit task is an often used reinforcement learning task [@sutton1998reinforcement], in which a person has to learn about the underlying distributions of each arm, by sampling from the options. Each time a person draws a sample from an option, the sampled point value is then added to his total point value. The n in n Armed Bandit indicates the number of options presented. ShinyPsych supports two to six arms, each of which can have a different underlying distribution type (e.g. a three Armed Bandit with $Opt1 \sim\mathcal{N}(\mu, \sigma)$, $Opt2 \sim uniform(min, max)$ and $Opt3 \sim exgauss(\mu, \sigma, \tau)$). Click here for more information on the Bandit task in ShinyPsych.

References

ndphillips/ShinyPsych documentation built on Feb. 14, 2022, 5:53 p.m.