General note: ILS labs used to be called UiL OTS labs; that is why sometimes you'll see the name UiL or UiL OTS pop up in links and documentation. We are working to change all instances of UiL OTS to ILS, but that will take awhile!
- This page provides generic background information on ILS 'templates' (or 'boilerplates') for jsPsych experiments (mostly linguistic experimental paradigms) and some additional tools that can be reused.
- Any new template links to this overview in its README.md, so that we can keep core documentation in one place.
This documentation provides information about using some templates that we developed at the ILS labs for (time critical reaction time) paradigms and tools needed to make your own online experiment using jsPsych. The aims for this repository are:
- Keep documentation on a selection of code bases in one place.
- Separate generic documentation from template-specific documentation.
- Give some background information to help Students, Researchers, and Developers plan online experimenting.
At this point, every ILS jsPsych template comes with the following 'default' components included:
A consent page placeholder is included before the experiment starts. It is up to the specifics of your own goals (and organisation) what information should be given. A consent page must always implement a combination of a consent statement, a checkbox that must be checked and a button that needs to be clicked to give consent. See consent.js for (placeholder) content.
You can adapt the survey questions to your own needs, but it is not as easy as it may seem. Please think carefully about what you want to accept as 'valid' in your survey. Read up about input (data) validation. For instance, you may want an e-mail address to be in the form of [email protected] and not allow people to fill out whatever in a survey field. Input validation is important for quality of online research. Also think about data management, and make sure to formulate your survey questions so that they will provide you with answers you can and will actually use (so, be very specific in your questions). See survey.js.
This utility library was created to enable:
- Mobile/Tablet detection (because those are not the type of devices we want participants to use).
- Randomisation using criteria about how many stimuli of a certain type are allowed to follow each other. Make sure to discuss with your supervisor which criteria to use!
Some templates have additional files and folders included, for example:
Sometimes, a custom plugin is used, for instance in the Self-paced reading template. See the folder plugins and its contents.
The Lexical Decision Templates use a custom keyboard setting procedure. See keyboard.js
Some templates use audio, if they do, there is or will be a simple testing procedure.
Specific information about the output (data) of each template experiment can be found in its README.md. In addition, there is a general primer describing jsPysch's way of "dealing with data" and some of the ILS template's defaults for data output. Absolutely make sure that you read that primer on data output, especially if this is your first time using one of these templates!
In a nutshell a reminder to summarize with regard to experiment data output:
- jsPsych experiments always return all data for each type of stimulus/trial/trial phase in 'trial' objects, that have keys and values.
- Many of our templates add data (subject ID & list ID as key, value pairs) to all the aforementioned objects, so the (sub)trial-data always have this information available for analysis.
- In the case of a trial or trial phase where the output contains relevant variables (experimental item, Reaction Time, etc), we sometimes add a key "useful_data_flag" with a value 'true' in the experiment; note that this may or may not include "practice trials", so always keep checking your code and your output!
- The above mentioned use of flags can be of use for filtering your data.
Certain information should be in every template. The elements below should be in every repository's README.md (Markdown):
The text within < > are 'placeholder text', the ones without them should be 'as is'.
# <Template name>
<A human redadable intuitive description related to the template name.>
# Generic documentation
Please read the [generic documentation](https://github.com/UiL-OTS-labs/jspsych-uil-template-docs) for some context and scope.
ILS-affiliated students and researchers should follow [this how-to](https://uilots-labs.wp.hum.uu.nl/how-to/online-experimenting/).
# Paradigm-specific template related documentation
<If there are clearly shared properties of templates (a general paradigm), like in the case of the Lexical Decision Paradigm, they may be referenced here.>
# Task Description
<Optionally, some scope information about the paradigm or shared organisation, if relevant.>
### Short description
<A short description of what _this specific template_ does and what output is given on top of [the output all the templates give](https://github.com/UiL-OTS-labs/jspsych-output).>
### Longer Description
<A longer description that reflects on, for instance a paradigm's variations.>
# Output (data)
The data of all (sub) trial phases are logged. Please read the [general primer on jsPsych's data output](https://github.com/UiL-OTS-labs/jspsych-output) if you are new to jsPsych data output.
<Specific template output variables and how to adapt your stimuli.js and/or other files regarding data output.>
# Getting started
<How to use/start the experiment.>
Some of the javascript (jsPsych) code (that is used by the experiments' 'index.html') is separated into separate files/modules. After unzipping a template download, you will often find the following files/folder structure.
template_download_main_folder\
| plugins/
| |
| \ someplugin.js # _Only_ if there is a custom plugin needed, you will find this folder 'plugins'.
| consent.js # Informed consent related code.
| globals.js # Global template settings/constants (buttonlabels/html messages, etc.).
| index.html # The main experiment file, always called 'index.html'. Always there!
| instructions.js # Instruction-related code.
| stimuli.js # Stimuli and their designs. Experimental, often Reaction Time (RT) critical!
| survey.js # Survey tools.
/
As a general rule, we design templates in such a way, that the main experiment's file (index.html) remains rather 'minimal'. That is: not too many lines of code in the main experiment's index.html, but bundle shared functionalities in separate files with functional, descriptive names.
The first templates were developed for the liguistics RMA course Experimental Design and Data Analysis in 2021. Given this context, we've made the templates so that they behave quite similarly to the ZEP templates that are used in the ILS labs for traditional, lab bound research. However, although JavaScript and ZEP may share some features (like coding syntax, code organisation), they are of course not the same.
See the ILS labs website here.
A tool that may help with things like restrained randomisation, detecting mobile phone/tablets and other reusable functionality.
jsPsych uses a cominbation of a markup language (html), a styling language (css) and JavaScript, this last one is a programming language.
How some concepts relate to each other:
- HTML is a markup language, not a programming language
- All HTML files have a similar structure
- With the
<script>somescipt.js</scipt>tags, you can use Javascript in HTML
- Javascipt is a (web) programming language.
- You can use functions, create custom code with interaction!
- There is no "official standard" for coding Javascipt, but it is very powerful
- CSS mainly deals with styling, like layouts, fonts, colors, backgrounds.
- CSS evolved from being primarily a styling language, but is also becoming a bit more like a 'programming language', in a way.
- jspsych uses Javascript code for a specific experimental purpose and the functions from this library need to be imported in the top of your html file before you can use them.
jsPsych was developed with scientists in mind, not developers. In essence, the jsPsych library tries to let you focus on mainly writing a html file and (re-)use simple JavaScript-style code blocks for trials or trial parts. However, once you get started with jsPsych, you will become a bit of a 'web developer' anyway, in the sense that:
- You will need tools for editing html files, JavaScript code blocks and stylesheets (not Word, Pages, LibreOffice, but a plain text editor).
- You will need to learn about debugging and the debugging capabilities of (most) web-browsers. (In Firefox, try F12).
- You will be confused when things 'don't work'.
- You will need to accept that you cannot control everything.
- Windows users may want to download Notepad++, or try out the free Visual Studio Code IDE (todo)
- Mac users can use BBedit, or TextEdit in plain text mode (preferences) or try out Visual Studio Code, use XCode, Sublime Text, etc.
- (Linux users will usually find their way with this step.)
Before you start editing one of these templates, reading up about jsPsych will usually be a good primer. We encourage anyone to get a gist of the 'simple' (but powerful!) way of doing things by following the recommendations given at jsPsych's site and to follow the first two tutorials. The basic things like how some index.html file imports from the jspsych library, where and how plugins can be used are very relevant to understand.
As always, the easy things tend to be easy to read (lines of code and examples) and understand, but in order to conduct a full-fledged online experiment, you need to invest a lot more time to make things work. This is why we chose to equip this selection of templates with the aforemetioned 'standard components' (consent, survey, a shared common utilities library). Also, by default, the templates implement stimulus lists with a so-called 'timelineVariable' implementation.
There are multiple ways to test, run and configure jsPsych-based experiments:
- Locally on your (or a participant's) PC, by double-clicking the
index.htmlfile. - Full web server implementation (getting a link to the experiment, served by DH-IT).
These two modes will likely confuse those who are not web developers, but the bottom line is:
- A locally developed experiment will not guarantee that the same experiment will run in a server setup, or vice versa!
Many browsers and versions have their own defaults for security like 'autoplay', allowing sounds, pop-ups and alerts, importing images from local sources, etc. It is impossible to be sure 100% if things will work in your browser in advance, so be prepared to deal with some confusion.
While you could -- in principle -- use jsPsych offline in the traditional lab context, it will typically not make a lot of sense. Especially if you want to store your research data for an experiment in one place, a web-server setup is the way to go.
Linguistics students and researchers affiliated with the ILS labs can use the templates from our lab webiste; expand the "Online experiments using jsPsych" section for details. Please follow this how-to to create your own experiment.
This documentation is aimed at people affiliated with the ILS labs (Utrecht University: Linguistics students and researchers). The infrastructure and support for doing online experiments will be only availble for those people. People not affiliated with our lab can of course use the templates, but will have to do without (support for, access to) the ILS Experiment Datastore.