Skip to content

Tutorial

To get started with making experiments in ROLEG, you can follow this tutorial and learn everything you need to know to set up your own (simple) experiment. If you are looking for any specific information or if you forgot how to write a certain block, take a look at the References section.

Creating the experiment

The first step is to create and initialise the file for your experiment. Go ahead and open the Live Editor in a new tab, or alternatively your text editor of choice (see Preliminaries) and start by writing the following:

1
2
3
experiment {

}

This will serve as the basis for your experiment. Save this file as a .roleg in your desired location. We will call it example_experiment.roleg for now.

Everything you write from now on should be between the curly brackets { }.

If you use a text editor on your computer, make sure the experiment filename ends with .roleg and not .txt or another extension before uploading your script to ROLEG.

Starting simple

Let's start with some additions to make your experiment actually do something. The first step will be to add a trial with a text stimulus and a button response to our experiment. We can do this by specifying a trial block within our experiment like so:

example_experiment.roleg
1
2
3
4
5
experiment {
    trial {

    }
}

A trial has a number of parameters and members that can be specified. One example is a maximum duration which specifies how many milliseconds the trial will go on for, if not terminated earlier by a response. The reference documentation trial states the corresponding parameter is called max_duration of an Integer type, a number without any decimals. Let's set it to 5 seconds (5000 milliseconds) for now:

example_experiment.roleg
1
2
3
4
5
experiment {
    trial {
        max_duration = 5000
    }
}

We now have a trial, but there is nothing presented yet. If we want to add a stimulus to present to the participant, we need to specify a stimulus block within our trial block:

example_experiment.roleg
1
2
3
4
5
6
7
8
experiment {
    trial {
        max_duration = 5000
        stimulus {

        }
    }
}

In such a stimulus block, there are a number of different kinds of stimuli we can add. Let's add some text, so can give some information to the participant:

example_experiment.roleg
1
2
3
4
5
6
7
8
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
    }
}

This is already a working experiment! If you click on the pencil-in-square icon in the top-right of the code block, the code will automatically load into the Live Editor. There, you can see the experiment that displays the specified text to the participant for 5 seconds, after which the experiment is done. You can open any example in this manual this way.

Let's also add a button response, such that the participant can end the experiment themselves. We can specify a response block the same way as we defined the stimulus block before, and add a button response with a specified text, like so:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "End the experiment"
        }
    }
}

Now the experiment shows the text to the participant, as well as a button that says "End the experiment". If they click on the button before the 5 seconds are over, the experiment will also end.

Tip

Try removing both the max_duration and button parameters and see what happens!
ROLEG will provide you with useful warnings like this one, to prevent you from making any mistakes.

Adding more trials

The next step is to expand our experiment to contain multiple trials. Each time you want to present a participant with a new combination of a stimulus and a response, you can define a new trial block:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    // (More trials to come go here)

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."

            // Confused about the '\' signs? (1)
        }
        response {
            button = "End the experiment"
        }
    }
}
  1. Confused about this? See Preliminaries for a refresher on how linebreaks work.

The participant will now first be shown a welcome text. After five seconds (or a click on the button), they will be shown the text from the last trial, thanking them for participating in the experiment. If they then click on the button, the experiment will be finished.

Tip

Closely look at the Results section in the live editor!
Can you spot the difference in results between ending the first trial by waiting five seconds, or by clicking the button?

Different kinds of stimuli

In a real experiment, you might want to give the participant a stimulus as an image or a video. Let's try to add an image stimulus to our experiment in between the start and end of the experiment. There are two ways to do this. If you only want to add an image, you can do the following:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    trial {
        stimulus {
            text = "Look at this image!"
            image = "sample_image.png"
        }
        response {
            button
        }
    }

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."
        }
        response {
            button = "End the experiment"
        }
    }
}

We now did not specify a text for the button, in which case it uses the default text which depends on the set experiment language.

Similarly, you could add a video or audio stimulus to your experiment. But, we are actually using a so-called shorthand here; a shorter way to write the code at the loss of some flexibility and options. Media stimuli also can be added by specifying a media block within a stimulus block. Within this media block, you can specify the file to be shown in the same way, but there is room for more details such as the total number of times a video can be replayed:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    trial {
        stimulus {
            text = "Look at this image!"
            image = "sample_image.png"
        }
        response {
            button
        }
    }

    trial {
        stimulus {
            text = "Look at this video!"
            media {
                video = "sample_video.mp4"
                max_number_plays = 3
            }
        }
        response {
            button
        }
    }

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."
        }
        response {
            button = "End the experiment"
        }
    }
}

The experiment above now first shows the participants a welcome message, after which it shows an image for 5 seconds. Then, it displays a video, which the participants can replay for a maximum number of 3 times after which they can continue with a click on the button. Lastly, the participants are shown the text from the last trial, thanking them for participating in the experiment. If they now click on the button, the experiment will be finished.

For an overview of all types of stimuli and their parameters, see the documentation on the stimulus block.

Different kinds of responses

So far, we have only presented the participants with a button as a response option. There are a couple of other types of response blocks, which we will dive into now.

Let's say that we want the participants to describe what they see in the image we show to them. We can do this by adding a textfield block. We will specify some aspects of this response option, such as whether to continue after the enter key has been pressed and which placeholder should be shown in the input field:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    trial {
        stimulus {
            text = "Look at this image!"
            image = "sample_image.png"
        }
        response {
            textfield {
                placeholder = "Describe what you see"
                continue_on_enter = false
            }
            button
        }
    }

    trial {
        stimulus {
            text = "Look at this video!"
            media {
                video = "sample_video.mp4"
                max_number_plays = 3
            }
        }
        response {
            button
        }
    }

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."
        }
        response {
            button = "End the experiment"
        }
    }
}

Another example of a response option is the slider block where participants can provide a response by dragging a slider along a range. Let's make it possible to respond to the video:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    trial {
        stimulus {
            text = "Look at this image!"
            image = "sample_image.png"
        }
        response {
            textfield {
                placeholder = "Describe what you see"
                continue_on_enter = false
            }
            button
        }
    }

    trial {
        stimulus {
            text = "What do you think of this video?"
            media {
                video = "sample_video.mp4"
                max_number_plays = 3
            }
        }
        response {
            slider {
                steps = 10
                labels = ["Hated it", "Loved it"]
            }
            button
        }
    }

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."
        }
        response {
            button = "End the experiment"
        }
    }
}

One other example of a very useful response option is the speech block. This allows participants to provide an audio response to the experiment. We will add a new trial block with an audio stimulus and a speech response block:

example_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    trial {
        stimulus {
            text = "Look at this image!"
            image = "sample_image.png"
        }
        response {
            textfield {
                placeholder = "Describe what you see"
                continue_on_enter = false
            }
            button
        }
    }

    trial {
        stimulus {
            text = "What do you think of this video?"
            media {
                video = "sample_video.mp4"
                max_number_plays = 3
            }
        }
        response {
            slider {
                steps = 10
                labels = ["Hated it", "Loved it"]
            }
            button
        }
    }

    trial {
        stimulus {
            text = "Please repeat what you hear"
            audio = "sample_audio.mp3"
        }
        response {
            speech {
                max_duration = 8000
                max_number_recordings = 3
            }
            button
        }
    }

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."
        }
        response {
            button = "End the experiment"
        }
    }
}

In a real experiment, you should properly inform participants of speech recording. See the documentation on the speech for more information. In the live editor, sound is recorded but no results, including sound, are sent to ROLEG and remain on your browser only.

Now we're getting somewhere!

For an overview of all types of responses, and for all the different details, see the documentation on the response block.

Include files

It is possible to move part of your code from the experiment file (.roleg) into a different, so-called 'include file' (.rolinc). This can help you with keeping an overview of everything that is present within the experiment and makes it possible to provide different participant groups with different trials.

Let's add a trial block to our experiment where we want the every even participant to answer a different question than odd participants. Let's first define a main experiment in a new .roleg file:

example_include_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
experiment {
    trial {
        max_duration = 5000
        stimulus {
            text = "Hello, welcome to this experiment!"
        }
        response {
            button = "Start the experiment"
        }
    }

    include = ["group1.rolinc", "group1.rolinc"]

    trial {
        stimulus {
            text = "\
                |Thank you for participating in the experiment.\n\
                |If you have any remaining questions, please contact us."
        }
        response {
            button = "End the experiment"
        }
    }
}

Be careful, opening these examples in the Live Editor will not work as the neccessary .rolinc files will not be copied over. To test the include files, create two new files inside the Live Editor and give these the same name and contents as these examples.

Now, we define two other files that will host the experiment sections different for each participant group.

group1.rolinc
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
include {
    trial {
        stimulus {
            text = "What do you think about apples?"
        }
        response {
            textfield {
                placeholder = "Your answer here"
            }
        }
    }
}
group2.rolinc
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
include {
    trial {
        stimulus {
            text = "What do you think about pears?"
        }
        response {
            textfield {
                placeholder = "Your answer here"
            }
        }
    }
}

Notice that we use include { ... } to define these files instead of experiment { ... }.

The experiment will now show the first participant the question defined in group1.rolinc and the second participant will be shown the question from group2.rolinc. After this, the experiment will start at the beginning of the list of include files again. This means that the third participant will be shown the question from group1.rolinc again.

For more information on how to use .rolinc files, see the page Include Files.

Templates

Most of the times when you are defining an experiment, you want to present the participants with similar trials that have different stimuli. An example would be to give your participants a sequence of different image inputs to which they have to respond in the same manner. To make it easier to write your script, ROLEG provides the ability to define templates that can be used later on in the experiment. You can find all the necessary information about templates here.

Our goal will be to create an experiment that presents the participants with different questions to which they can respond with a slider response. Since templates are a very useful tool that require a bit of a different approach, let's make a new file to try it out. We will call this file template_experiment.roleg.

template_experiment.roleg
1
2
3
experiment {

}

The first step is to create your own template, this can be done with the define_template block, which we will give a name: "sliderresponse".

template_experiment.roleg
1
2
3
4
5
6
experiment {
    // --- Template definition ---
    define_template {
        name = "sliderresponse"
    }
}

A define_template block has an identical structure to a trial block and can use the same members and parameters. Let's build the structure for our intended purpose, we want a textual stimulus and a slider response.

template_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
experiment {
    // --- Template definition ---
    define_template {
        name = "sliderresponse"
        stimulus {
            text = BOUND
        }
        response {
            slider {
                steps = 5
                labels = ["Completely disagree", "Completely disagree"]
            }
            button = "Next question"
        }
    }
}

You might have noticed something weird in this code. The value assigned to text has no quotation marks and is in uppercase. This is because it is a special Keyword. The BOUND Keyword indicates this value will be specified later on, because it should be different each time we use this template. The experiment above will not show the participants anything yet: it only defines a template that can later on be used. Let go ahead and use this template.

template_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
experiment {
    // --- Template definition ---
    define_template {
        name = "sliderresponse"
        stimulus {
            text = BOUND
        }
        response {
            slider {
                steps = 5
                labels = ["Completely disagree", "Completely disagree"]
            }
            button = "Next question"
        }
    }

    // --- Experiment trials ---
    sliderresponse_template { // (1)
        fill {
            text = "I like to swim"
        }
    }
}
  1. Note that the name used in the trial definition is now used here when applying the template.

Participants will now be shown the statement "I like to swim" to which they can respond with a slider, as defined in the define_template block. We can also use fill_repeated to add multiple trials in one go.

template_experiment.roleg
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
experiment {
    // --- Template definition ---
    define_template {
        name = "sliderresponse"
        stimulus {
            text = BOUND
        }
        response {
            slider {
                steps = 5
                labels = ["Completely disagree", "Completely disagree"]
            }
            button = "Next question"
        }
    }

    // --- Experiment trials ---
    sliderresponse_template {
        fill_repeated {
            text = [
                "I like to swim",
                "I like to run",
                "I like to eat cheese"
            ]
        }
    }
}

As you can see, each time we want to present the participants with a new statement, we do not have to define the slider response all over again. We only need to define the information that will change (which, in this case, is the text).

You can find some example experiments that use templates here.

Further reading

There are a lot of other blocks you can add and other behaviour that you can change. All the different blocks and details can be found in the References section. Some examples that have not been explained here, but might be interesting are:

Back to top