Skip to content

Template Trials

Most experiments want to present the participant with similar trial blocks, with different stimuli. An example would be a trial with a media stimulus of an image with a keyboard response, where a different image stimulus is presented each time. One naive approach would be to set up a trial block for each trial, but with a different media file. This however, would be a lot of work and result in badly readable code with a lot of unnecessary repetitions. Therefore, ROLEG provides an alternative approach by offering the ability to define template trials. The structure of a template block as well as how it is used, is summarised below.

Tip

The use of template trials is not required to write an experiment, but can significantly speed up the process. Although the specification may seem complex, we invite you to first look at the Example usage and Example experiments for concise examples to learn from.

The define_template block can only be used before any other blocks, at the top of an experiment block. This ensures that all templates are clearly defined at the start of the experiment and usable for the rest of the script that follows.

Parameters

A define_template block has an identical structure to a trial block and can use the same members and parameters, except for id. A define_template block has one additional parameter, defined below.

name
Required.
String that defines the name of the template. This name is necessary when using the template later on (see Template application).

Furthermore, each parameter or shorthand inside a define_template block, such as the stimulus text or response choice options can be bound. To bind a parameter or shorthand inside a define_template block means that you declare it variable and will provide its concrete value later on. You can already provide default values for some parameters which will then not have to be repeated anymore and later only need specify the bound parameters.

You can bind any parameter or shorthand by setting its value to the Keyword BOUND, regardless of the parameter type description the manual provides. You can bind any number of parameters. You cannot bind entire members. Any members and parameters you specify that are not bound act as default values and can still be overwritten later on, if desired.

Example: text = BOUND

Template application

A defined template can be used later in the experiment, by using a [name]_template block, where [name] should be replaced with the name you defined in the define_template block. The [name]_template block is equivalent to a trial block and can use the same members and parameters. It inherits default member and parameter values from the corresponding define_template block. A [name]_template block has additional functionalities, explained below.

fill

Optional.
Block that contains parameter names set to a value. In this block, you can specify which previously bound parameter should be filled with what value.

Example: 

fill {
    text = "The quick brown fox jumped over the lazy dog"
}

We recommend that any use of fill is placed last in a template application, to avoid accidentally losing its effect.

fill_repeated

Optional.
Block that contains parameter names set to a List of values. In this block, you can specify which previously bound parameter should be filled with what values.

Example: 

fill_repeated {
    text = [
        "The quick brown fox jumped over the lazy dog",
        "The brown quick fox jumped over the lazy dog",
        "The lazy fox jumped over the quick brown dog"
    ]
}

If you fill multiple parameters and supply lists of different lengths, as many trials will be created as the length of the longest list. Parameters supplied with a shorter list will wrap around.

Example usage

The code below illustrates how a template trial might be used.

experiment {
    // --- Defining the template ---
    define_template {
        name = "speech"

        // All parameters and members of a `trial` block are available here
        // We use this to set sensible defaults, such as a maximal trial duration and fixed response options
        max_duration = 7000
        pre_delay = 2000

        stimulus {
            text = BOUND // We bind the `text` shorthand, to be specified later 
        }
        response {
            speech {
                max_duration = 6800
            }
        }
    }

    // Introductory trial
    text = "Read out loud the following sentences."

    // --- Using the template ---
    speech_template { //(1)
        // We fill in the `text` previously bound. We do so within the template.
        fill {
            text = "The fox jumped onto the box."
        }

        // The trial inherits its response options from the template definition and we do not need to repeat it here.
    }

    speech_template {
        // We can also override the default parameters specified in the template definition
        max_duration = 10000

        // We recommend that any use of `fill` is placed last in a template application, to avoid accidentally losing its effect.
        fill {
            text = "The cat crouched near the box."
        }
    }

    speech_template {
        // We can also fill `text` multiple times, using `fill_repeated`
        fill_repeated {
            text = [
                "The fox jumped onto the box.",
                "The cat crouched near the box.",
                "The dog ran past the box.",
                "The bird flew over the box."
            ]
        }
    }
}
  1. Note that the name used in the trial definition is now used here when applying the template.

List of example templates

A list of example template definitions may be obtained from the Example experiments.

Back to top