Defining an experiment

Back to Experiment Generator main page…

This page is a technical explanation of how you use Experiment Generator. To actually generate & run the experiment, go to this page.

An experiment can be defined by creating a configuration file – an Excel file containing all the experiment parameters and definitions (trial flow, trial contents, etc.). The configuration file should have the format specified below. 

Experiment Generator translates your configuration file into a web page. This web page is written in HTML and javascript, and it uses the jspsych experimentation framework. One advantage of this method is that you can download the generated web page and edit it manually to obtain additional features not supported by Experiment Generator – for example, adding graphics. This means that if your requirements are more complicated than the standard, e.g., you want to locate the layout elements in certain a very precise manner on the screen, you need to be familiar with HTML/CSS.

If you created an experiment, ran it, and nothing appears on screen – it means you probably defined something incorrectly, which resulted in errors in the HTML page, but Experiment Generator missed this error. You can try debugging your script with HTML/javascript tools if you know how to do this, or let us know about the problem at info@mathinklab.org (attach the generated HTML file + the Excel configuration file that you used) – we will try help, but we don’t promise, as we do not have the resources for ongoing support .

Here is an example for a configuration file for a simple experiment called “was it here”: in each trial in this experiment you see a digit followed by a multi-digit number, and you need to decide whether the number contains the digit (press the “/” key) or not (press “z”). Try it! (it’s short – only 5 trials)

When defining an experiment you should specify several kinds of information about your experiment. Here are the main kinds of information (each is defined in a separate worksheet in the Excel configuration file):

  1. Layout elements (“layout” worksheet): define “placeholders” for stimuli that will appear on screen during the experiment. For example, in the “was it here” experiment we defined 3 layout items: the multi-digit number, the target digit, and the fixation cross that precedes them. For each layout item, we can define its appearance – e.g., font, size, location on screen, etc. Several of these definitions can be later overridden for specific trials.
  2. Possible responses (“responses” worksheet): define any keyboard key that the participant can type as response. For now, only single-key responses are supported. Alternatively, you can define response buttons that will appear on screen and can be clicked using the mouse. In the “was it here” experiment, we defined 3 keyboard responses: the “z” and “/” keys, which are used as responses in the experimental trials, and the space key, which is the response in the instructions stage.
  3. Trial types (“trial_type” worksheet): define the flow of each trial as a sequence of layout elements that will appear during the trial. Each layout element is a stage in the flow, and you can define its timing (onset, duration), whether a response is expected following this stage, and which responses are valid. If different trials have different flows, define them as separate trial types, each with its own sequence of stages (but this is not yet possible – we hope to add this feature very soon).
    In our sample experiment all trials have the same flow, so there’s a single trial type, with 3 stages: showing the fixation cross, presenting the target digit, and finally presenting the target number.
  4. Trials (“trials” worksheet): this defines the specific list of trials, with the specific values that will be shown in each trial.
  5. General parameters (“general” worksheet): general experiment definitions such as whether the results should be saved, the title of the experiment web page, etc.
  6. Finally, the “instructions” worksheet specifies what to show as instructions when the experiment begins.

Each of the worksheets is formatted as a table. The first row (A) contains the titles of each column; below, there is one row for each specific configuration item.

“general” worksheet

This worksheet contains general experiment definitions such as whether the results should be saved, the title of the experiment web page, etc.

Each row is a single parameter. It is defined by 2 columns: param and value, defining the name and value of this parameter. These are the parameter names:

  • save_results: Whether the experiment results should be saved (specify value = Y) or not (N). The results are a CSV file with the participant’s responses to each trial and the reaction times (see detailed description of this file format in the bottom of this page). When the experiment ends, the participant will be prompted to download the results to their computer.
  • results_filename_prefix: The CSV results filename will be a concatenation of the prefix defined here and the experiment’s date and time. Of course, when saving the file the participant can change this name,
  • full_screen: Whether the experiment will run in full screen mode (specify value = Y) or not (N). When not in full screen mode, the participant can still see the browser’s tabs and menus, the Windows/Mac taskbar, etc.
  • title: the web page title (displayed on the browser tab).
  • start_of_session_beep: Whether to play a short beep when the experiment starts (Y) or not (N) – right after the participant leaves the instructions page. This is useful in case you audio record or video record the experiment and you want to be able to syncronize the recording with the data from the results CSV file. The results file specifies each trial’s start time. If you specify here Y, the start time will be specified relative to the precise timing in which the beep ended.

“instructions” worksheet

This worksheet contains the text to be shown as instructions when the experiment begins.

Each row is a single instructions page. It is defined by 2 columns: text and responses, defining the text to show in this page and the responses that should be made by the participant in order to proceed to the next instructions page.

  • text: Just specify the text, which can be multi-line. It can also contain HTML tags.
  • responses: a comma-separated list of response alternatives. Each response must be defined in the “response” worksheet; here, you only specify the name of that response (same identifier that you wrote in the response_name column in the “response” worksheet, see details below).

“layout” worksheet

This worksheet defines “placeholders” for stimuli that will appear on screen during the experiment. At present, Experiment Generator supports only text stimuli. Each type of stimulus should be defined as a single layout element. For example, if your experiment presents in each trial a fixation cross followed by 2 words, you will probably define 3 layout items – the fixation cross and the two words.

Each row in this worksheet is one layout element, defined by the following parameters (each written in a separate column, whose title is the parameter name).

General parameters

  • layout_name: A name for this element. You will use it later to refer to this element from the “trials” worksheet.
  • type: At present, this must specify “text”.
  • text (optional): The default text to show. Specify this if the same text appears in all trials – e.g., if this row defines the fixation cross, you’ll probably write here “+”. Whether you specify here the default text or not, you can later override it for each specific trial via the “trials” worksheet.
  • border-color (optional): The color of the boundaries of the text element’s bounding box. You can specify one of the color names supported by HTML (e.g. “white”, “black”, “red”, etc.); or the precise color you want, e.g., by specifying the red, green, and blue intensities on a 0-255 scale – e.g., “rgb(255, 0, 0)” is red. See more details here.
  • explanation (optional): This column is not intended for Experiment Generator but for you — use it to write your own comments about the meaning of each layout element.
  • Additional parameters can set the layout element’s position on screen. Use them if you want to modify the default behavior, which is to show the text in the middle of the screen.
  • And yet more parameters can be used to define several more aspects of the text element – e.g., the font size, type, color, and many more.

Under the hood. For each layout element – i.e., each line in the “layout” worksheet – Experiment Generator creates a CSS entry (containing that element’s definitions) in the beginning of the generated HTML file. The HTML code for each particular trial will contain a “style” attributes referencing that CSS entry.

“response” worksheet

This worksheet defines the response alternatives in the experiment – keyboard keys, and/or buttons that are placed on screen and can be clicked by the mouse. Note that a specific trial stage (see below in the documentation of the “trial_type” worksheet) cannot contain both keyboard and mouse responses.

Each row in this worksheet is one possible response – a single key or a single button. These are the columns that define it:

  • response_name: An identifier of this response. Use it to refer to this response alternative from the other worksheets (trial_type, instructions). A valid identified contains only letters, digits, and the _ character.
  • type: the response mode – either “key” or “button”.
  • value: the value that will be saved in the results CSV file (in the response_value column) if the participant made this response.

Specific columns for key responses

  • key: the keyboard key expected for this response. If a letter, use lowercase letters. For space, you can write a space character or the word “space”. Special keys (tab, enter, etc.) are specified by typing their name according to this list. Some useful key names: Backspace, Tab, Enter, Shift, ArrowDown, ArrowUp, ArrowLeft, ArrowRight, Escape.

Specific columns for button responses

  • text: the text to show on the button. The text may contain HTML tags. You can leave this empty for a button without text, but the “text” column is still mandatory.
  • border-color (optional): The color of the button’s surrounding lines. You can specify one of the color names supported by HTML (e.g. “white”, “black”, “red”, etc.); or the precise color you want, e.g., by specifying the red, green, and blue intensities on a 0-255 scale – e.g., “rgb(255, 0, 0)” is red. See more details here.
  • Button position and size: by default, the buttons are organized in a row and their size is automatically adapted to the text inside the button. You can change that by adding columns that set the button position and/or size.
  • Additional parameters can be used to define several more aspects of the button and of the text in it – e.g., the font size, type, color, and many more.

Under the hood. Experiment Generator collects these responses using two jspsych plugins: html-keyboard-response and html-button-response (note the jspsych version number if you rely on these links). In the javascript code generated for these plugins, the list of responses will be generated as the “choices” entry. Additional definitions and CSS settings of the buttons are generated as part of the “button_html” entry.

“trial_type” worksheet

Each trial type defines the flow of particular type of trials. The flow is defined as a series of steps, where each step consists of layout elements and/or responses. A single row in the Excel worksheet defines a single step, i.e., a multi-step trial type requires defining several rows.

You define trial type steps using the following columns:

  • type_name: A name for this trial type. The name must be a valid identifier (contains only letters, digits, and the _ character).
    If you omit this column, Experiment Generator assumes that all trials belong to the same type, whose name is “default”.
  • layout items: The layout elements that will appear in this step. Specify a comma-separated list of layout names (same identifier you defined in the layout_name column in the “layout” worksheet).
  • duration (optional, specified in milliseconds): for how long the layout elements will appear on screen before disappearing.
  • delay-before (optional, specified in milliseconds): a delay between the beginning of the step and the onset of the layout elements.
  • delay-after (optional, specified in milliseconds): a delay between the end of this step (caused either by the layout element disappearing or by the participant making a response) and the beginning of the next step/trial.
  • responses: The list of valid responses the participant can make on this step. Specify a comma-separated list of response names (same identifier you defined in the response_name column in the “response” worksheet). Leave this column empty of no response is expected at this flow step.

The current version of Experiment Generator supports only one trial type. We hope to fix this soon.

Also, Experiment Generator does not support intrinsically the definitions of steps with partial temporal overlap (e.g., stimulus A appears, then B appears, then A disappears, then B disappears). You can still get this effect by cutting the trial into several steps (in the example above – 3 steps: A, A+B, B). We hope to fix this issue too soon.

Under the hood. In the generated HTML file, each flow step will appear as a single javascript variable that specifies the configuration for a html-keyboard-response or html-button-response plugin. The variable name will be trial_type_<typename>_step<#>, where <name> is the name you defined in the type_name column, and <#> is the step number (in the order of their appearance in the Excel worksheet). The full flow of a particular trial type is generated as a javascript variable called <typename>_procedure.

“trials” worksheet

This worksheet defines the specific list of trials, with the specific values that will be shown in each trial. Each row in the worksheet defines one trial.

This worksheet contains the following columns:

  • type: the trial type. Specify an identifier that you defined in the type_name column in the “trial_type” worksheet. If you have only one trial type, this column is optional.
  • Values to fill in the layout items: Each trial type includes several layout items. Here you should define the actual values to show for each layout item. To do this, add one column for each layout item; the column name is the layout element name (same identifier you wrote in the layout_name column in the “layout” worksheet).
    You must define a column for each layout element you use, unless you defined a default value for this element in the “layout” worksheet.
  • Override formatting: You can override the visual formatting of specific layout elements in specific trials. To do this, define a column whose name is format:layout.css-parameter, where layout is the layout element name (same identifier you wrote in the layout_name column in the “layout” worksheet) and css-parameter is the name of any formatting parameter as defined above in the documentation of the “layout” worksheet.
    For example, a column whose title is format:text1.top will modify the “top” definition of layout element “text1”.
  • Save values to results file: If you add a column whose title is save:xxx, the value in this column will be copied as-is to the results CSV file, to a column titled xxx. This is useful when you want the results file to contain additional information about the trial, which is not shown to the participant. For example, the expected response.