21  / The Builder view

We will use the PsychoPy Builder to create experiments. Figure 21.1 displays PsychoPy’s Builder view1. The Builder window has a toolbar and three panels: routines, components and the flow.

Figure 21.1: The main elements of the PsychoPy Builder.

21.1 Opening the Builder view

If you launch PsychoPy, the Builder view will be one of the windows opened by default. However, if you accidentally close the Builder view, you can re-open it without having to relaunch PsychoPy in the following way:

  • In the menu bar, click on Window and then on PsychoPy.
  • Then click on View and on Open Builder view.

21.2 The multi-course meal analogy

We will use an analogy to help you understand how PsychoPy works. Think of an experiment as a multi-course meal. Then:

  • Components are ingredients that make up an individual dish.
  • Routines are individual dishes.
  • The flow is the order in which the dishes are served.

Like all analogies, it’s not perfect, but it might be a helpful starting point to thinking about experiments in PsychoPy. We’re now going to have a closer look at each of these parts in turn.

21.3 Components

To make a dish, you need some ingredients. Analogously, you need components to make a routine. You can add components to a routine by clicking on a component icon (e.g., Image) in the “Components” panel. Under “Favorites”, you can find the most frequently used components:

Additional components can be found by clicking on the appropriate section headers (i.e., Stimuli, Responses, Custom, etc.). To add a component to a routine, simply click on the component.

The trial routine in Figure 21.1 has two components: a Text component and a Keyboard component:

The Text component will present text on the screen and the Keyboard component will register a response from the participant. The blue and orange bars next to these components present information about the timing of these components:

  • Note how the two bars start at the same time. Therefore, the time measured by the Keyboard component will correspond to the response time. Of course, participants can only begin to react once the imperative stimulus (i.e., the stimulus to which they should respond) has appeared on the screen. It is particularly important to keep this in mind when multiple components with different onsets are presented in a routine and the participant is instructed to react to one specific component (e.g., the target in a priming task).
  • Also note that the two components only start 0.6 s into the trial. This introduces a short gap at the beginning of each trial (the so-called response-stimulus interval or RSI) and thus avoids that a new stimulus is presented immediately after a response.
  • If the bars go all the way to the right, this means that their duration is infinite (however, as experiments lasting infinitely tend to be unpopular with participants, you can tell PsychoPy to end a routine when a response is given!).

If we change the duration of the Text component to 0.5 s, the timeline will change accordingly:

To remove a component from a routine, right-click on the component and select “remove”:

Components have a number of properties. For example, these define the timing, position, size, and orientation of a stimulus. We will have a closer look at some of these properties in Chapter 22.

21.4 Routines

The experiment shown in Figure 21.1 has four routines: feedback, instruction, taskBegin and trial. Note that each routine has a separate tab. The routine trial is currently selected as indicated by the lighter shading and the ⓧ:

In our multi-course meal analogy, routines correspond to individual dishes. Just as some dishes will have very few ingredients, some routines might consist of just one or two components. Others will have many more components, for example in cases where you want to present multiple independent stimuli.

In the flanker task you just downloaded, flankers and target appear at the same time. Therefore, only one Text component is required. This Text component might then present the stimulus HHSHH. What researchers sometimes do is give the flankers a head start. In this case, the flankers appear earlier than the target. Now, your routine needs two Text components. One to present the flankers, e.g. HH HH, and the other to present the target, e.g. S.

You can add a new routine to an experiment by clicking on “Insert Routine” and “(new)” in the flow. Newly created routines will be empty and are waiting for you to add components to them. Note that “Insert Routine” can also be used to add existing routines to the flow:

Upon creating a new routine, you have the option to add it to the flow by clicking on the circle that appears when you move the mouse pointer over the flow:

You can click on “CANCEL Insert” if you’re not yet sure where in the flow you would like to place it.

To remove a routine from an experiment, click on the ⓧ next to the routine’s name. This will automatically remove the routine from the flow as well.

Note that you can also copy and paste existing routines (including from one experiment to another). This can be a great time-saver!:

21.5 Naming components and routines

When you create a routine or add a component to a routine, you need to give it a name. There are some rules you must follow when naming routines and components:

  • Use only letters, numbers, and underscores to name them (e.g., you must not use spaces!).
  • Always begin the name with a letter (numbers and underscores can only come later).
  • You cannot reuse names (once you have labelled a routine or component stim, you cannot give another routine or component the same name).

PsychoPy will usually warn you if you try to use a name that is not possible. In addition, it is good practice to give routines and components names that indicate what they do. For example, our routine presenting the instructions is called instruction. If it was called trial_2, it would be unclear what its role is.

21.6 The flow

In keeping with our analogy, the flow describes the order in which the dishes are served. In our example shown in Figure 21.1, we start with the routine instruction. This routine will be followed by the routine trial, which will be followed by the routine feedback, etc.:

Note that there is a loop surrounding the routines trial and feedback (as well as the trial routine later in the flow). This usually2 means that routines inside the loop will be presented repeatedly. When routines are repeated in a loop, typically something changes from one repetition to the next. If we were to stretch our analogy a bit, it could be the waiter coming over to your table repeatedly and on each occasion serving a new type of bread: “Here is a slice of bread with walnuts.” “Here is a slice of bread with pumpkin seeds.” “Here is a slice of bread with sunflower seeds.” “Here is a slice of bread with flax seeds.” You get the idea. In our flanker task, a loop updates the stimulus from one trial to the next. For example, the first stimulus might be HHHHH, followed by SSHSS, HHSHH, SSSSS and so on. We are going to have a closer look at loops next week.

Also, note that dishes can be served again. In our task, we use the routine trial twice in our flow. What would be a no-go in a restaurant, is a great feature in PsychoPy. If practice and experimental trials require the same components with the same properties, you need to create your trial routine only once and you can then simply reuse it when you need it again!

To remove a routine from the flow, right-click on the routine and select remove:

Note that this only removes the routine from the specific location in the flow, but not from the experiment or from another location in the flow.

The colour of a routine indicates whether or not it has a fixed length. If yes, it is displayed in green. If not (e.g., if the trial only ends when a response key is pressed), it is displayed in blue. Sometimes you might need to close and re-open PsychoPy for the colours to be displayed correctly.

21.7 The toolbar

The toolbar is located above the routines panel:

If you hover your mouse pointer above the icons, they will tell you what they do. There are four groups of icons. The functions of the left-most group (such as Save and Undo) are common to most desktop applications and we will therefore not discuss them in detail. The right-most group of icons is relevant for running experiments online. We won’t need this group of icons. We are going to have a look at the remaining two groups below.

21.7.1 Monitor and experiment settings

The monitor and the experiment settings are represented by icons of a monitor and a cogwheel, respectively:

You shouldn’t have to change anything about the monitor settings. However, the experiment settings are important. Most relevant in the experiment settings are the Basic tab and the Screen tab. The Basic tab is where you can alter the experiment information that is part of the start-up dialogue that is presented at the beginning of an experiment. The default setup for “Experiment info” asks about participant and session:

f"{randint(0, 999999):06.0f}" means that a random six-digit participant number between 000000 and 999999 will be created (this is not there for the flanker experiment, but you will come across this when you create a new experiment).

Here, you could for example add a field asking about age and gender by clicking on a plus sign. You could also remove information about the session if you don’t need it by clicking on the minus sign next to this field. Note that you should leave the participant field untouched. PsychoPy expects to find this as is (i.e., including the lower case first letter)!

The Screen tab gives you access to settings such as the background colour. The default background colour is grey:

The three numbers correspond to, in this order, the intensity of red, green and blue (RGB) channels ranging from -1 to 1. Thus, other background colours can be defined in this way:

  • black: $[-1, -1, -1]
  • white: $[1, 1, 1]
  • red: $[1, -1, -1]
  • green: $[-1, 1, -1]

It is also possible to use named colours. Thus, black or skyblue will also work. Note that in this case you need to leave out the $ sign.

21.7.2 Compile and run experiments

The next group of icons compiles and runs the experiment:

Clicking on the “Compile to Python/JS script” icons will turn the Builder experiment into Python/JavaScript code, respectively. You won’t need these.

The other two icons are important though: They run experiments. The “Send the experiment to Runner” icon on the left sends the experiment to a separate Runner window first, where you have to click on another “Run” button. The Runner window allows you to easily run multiple experiments in a row. The “Run experiment” icon on the right directly runs the experiment.

  1. Note that PsychoPy also has a Coder view for those who would like to write Python code. We will not need the Coder view.↩︎

  2. A loop has a specific number of repetitions associated with it. If the number of repetitions is set to 0, this can be used to stop a routine or multiple routines from running. This is useful for debugging experiments.↩︎