2. General settings for experiment design - fildpauz/jespr GitHub Wiki
The main task of getting a JESPR experiment ready is to create the design file (e.g., jespr-sample1.js above). The design file must be laid out using the JSON (JavaScript Object Notation) data format. If this is not familiar to you, a gentle introduction can be found at the W3C Schools. For those not confident with how to construct and error-check JSON format, it may be useful to use an editor. A search for "json editor" or "json online editor" will yield several good options.
An important point to make at the outset, though, is that the entire purpose of the design file is to define the experiment object using JSON format and then assign it to the jesprExperimentDesign variable.
var jesprExperimentDesign =
{
// Design definition here...
};
The following sections explain how to organize the design file as well as what setting options are available and what they do. Those marked with an asterisk (*) are required in the design file.
title
This is the title of the experiment and will be shown on an obligatory title screen together with the investigators names below.
investigators
This is a list of the investigators and will be displayed on the title screen. the primary investigators will be listed first and in bold face and other investigators will be listed afterward in the normal font face.
font-name (default: Courier new)
The name of the desired font to be used as the base font for all text in the experiment. The actual font used will be somewhat browser and system-dependent, so using a web-safe font (e.g., Arial, Times New Roman, Courier) is recommended.
font-size (default: 12)
The size of the font in pt units (but without the units). While any desired font size setting is possible, experimenters should confirm that their selected font size does not result in wrapping of stimulus sentences (which might produced systematic latencies in keypress timings).
text-color (default: black)
The color of all text in the experiment (with the optional exception of feedback; see below). Colors are limited to one of the 147 HTML valid color names (e.g., http://www.w3schools.com/colors/colors_hex.asp).
background-color (default: white)
The color of the screen background throughout the experiment. Colors are limited to one of the 147 HTML valid color names (e.g., http://www.w3schools.com/colors/colors_hex.asp).
display (default: moving window)
This determines how the regions of each stimulus item will be displayed:
moving window-- As each region is unmasked, the previously displayed window is masked, yielding a display where only one region is visible at a time.cumulative-- Unmasked regions remain unmasked for the continuation of the stimulus.
orientation (default: horizontal)
This determines the orientation of the stimulus regions.
horizontal-- The regions are arranged on a single line, horizontally. This would be the typical arrangement for stimuli where the entire stimulus is one sentence, and each region is one (or more) words.vertical-- The regions are arranged vertically, in the center of the screen. This would be teh typical arrangement for stimuli that are, say, short stories, and each region is one sentence in the story.
masking-character (default: _)
This is the character that will be used to mask each region, by substituting the character for all non-whitespace characters (including punctuation) within the region. Note that different potential masking characters (e.g., _, *, X) will have different widths in different fonts and could result in some unusual display effects during the experiment. Therefore, carefully consider font-name, font-size, and masking-character together.
fixation-character (default: +);
At the beginning of each stimulus item, a fixation character will be displayed as is typical in self-paced reading experiments. The selected fixation character will be presented at a font-size approximately 5 times the normal font size.
min-instruction-time (default: 3000 milliseconds)
In order to prevent participants from accidentally jumping pasts instruction screens that they need to read, this value sets a minimum amount of time that the screen must remain visible before the experiment may proceed. Hence, it effectively disables the advancement of the experiment for the specified number of milliseconds. This might also be set to a much higher number (e.g., 60000 for one minute) in order to ensure that participants spend enough time on the instructions.
feedback-options
Feedback to the experimental participant may be given during the experiment regarding their responses to optional post-stimulus prompts (e.g., comprehension questions). feedback-options is the place to define one or more generic feedback options that may be used through the experiment. Each option has three parameters, as follows.
name* -- the name of the option. This is used within the design file to indicate which responses should receive which feedback-option. This name is never displayed to the experimental participant, but will be used in the data output to indicate which feedback was given.string* -- the actual feedback to be given to the participant (e.g., That's correct, That's not correct).text-color-- The (optional) color in which the feedback text will be displayed (e.g.,redfor That's not correct). Colors are limited to one of the 147 HTML valid color names (e.g., http://www.w3schools.com/colors/colors_hex.asp).
show-progress-bar (default: false)
During the experiment, a simple progress bar may be displayed across the bottom of the screen to show how far the participant has progressed through the experiment. It is updated only at the beginning of each new screen (hence, for each instruction screen or at the beginning of a stimulus item, together with the fixation symbol).
input-method (default: keyboard)
The input method may be defined as either keyboard (using the space bar to advance through the regions and using {1|q|a|z} and {0|p|l|m} to indicate the left-hand or right-hand options to prompts) or as html-button (creating an on-screen button which can either be clicked with the mouse cursor or tapped on a touch-enabled screen).
quote-mark (default: double_quote)
By default, strings in the results will be delimited with double_quote marks: ". However, if preferred, this may be changed to single_quote marks (i.e., vertical apostrophes) ' or curly_brackets {}. When using JESPR with Mechanical Turk, the last would be recommended since the experimental results will be embedded as a single data field within the MT results file inside double quotes. Hence, the brackets allow it to be distinguished and extracted more easily. Afterward, the brackets can be converted to quotes if needed for further processing.
show-results-display (default: false)
After the experiment is completed, the results will be stored in a form variable, jesprResults. If the form is submitted the results will thus be submitted as form data. However, there may reasons the experimenter wishes to display the results before submission (or to extract results without submitting at all). Thus, if the show-results-display variable is set to true, a textarea will appear in the browser window after the experiment containing the csv-formatted results (see below for detailed description).
show-log-display (default: false)
After the experiment is completed, JESPR log information will be stored in a form variable, jesprLog. If desired, the log information may be displayed to the browser screen by setting show-log-display to true. This may be useful when debugging the design file.