25  The Builder

We will use the PsychoPy Builder to create experiments. The Builder window has four main divisions: Toolbar, Routines, Components and Flow.

25.1 Open the Builder

If you launch PsychoPy, the Builder will be one of the windows opened by default.

If you accidentally close the Builder, you can re-open it by clicking on View → “Show builder” in the menu bar:

25.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 individual dishes.
• 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.

25.3 Components

To make a dish, you need some ingredients. Analogously, you need components to make a routine. To add a component to a routine, simply click on the component (drag and drop does not work here!).

Under “Favorites”, you can find the most frequently used components:

Additional components can be found by clicking on the appropriate component groups:

The trial routine in this example has two components: a Text component and a Keyboard component:

You can identify the type of component based on the icon. Note that the name of component is chosen by the user (e.g., the Keyboard component in the example is called “response”). 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 represent information about timing:

• Both components start 0.6 s into the trial. That means that the stimulus presentation will begin 0.6 s into the trial and, at the same time, the Keyboard component will start measuring respone time. The first 0.6 s of the trial will simply consist of an empty screen.
  • That both components start at the same time is important to ensure that the time measured by the Keyboard component will correspond to the response time (i.e., the time since stimulus onset).
  • It is important that the onset of the Keyboard component coincides with the onset of the imperative stimulus (i.e., the stimulus to which participants should respond).
  • That fact that the two components only start 0.6 s into the trial also introduces a short gap between trials and thus avoids that a new stimulus is presented immediately after a response.
• Both components extend beyond the “t (sec)” label. This means that their duration is infinite (however, as experiments lasting infinitely long 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 and the blue bar now has a length corresponding to 0.5 s:

The colour of the components refers to the type of component used:

• Blue is typically used for components that present stimuli or collect data continuously (e.g., camera or microphone).
• Orange is used for components that expect active, discrete responses from participants.

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 26.

25.4 Routines

Our flanker experiment 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:

After clicking on “Insert Routine”, you can add a routine 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!

25.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.

Note that 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 rather unclear what its role is.

25.6 The flow

In keeping with our analogy, the flow describes the order in which the dishes are served. In our flanker task, 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 usually¹ 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, the loops update 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. That is, routines can be re-used. In our task, we use the routine trial twice. 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 it has a fixed length, 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.

25.7 The toolbar

The toolbar is located at the top of the Builder window:

There are seven groups of icons:

• File: New, Open, Save, Save as.
• Edit: Undo and redo.
• Experiment: Monitor center, Experiment settings, Pilot vs. Run, Send experiment to runner.
• Desktop: Write Python code, Run.
• Browser and Pavlovia: Only relevant for running experiments online. We can safely ignore these for now.
• Views: Switch between Builder, Coder and Runner.

If you hover your mouse pointer over the icons, they will tell you what they do. For us, the most relevant of these icons are “Experiment Settings”, “Pilot vs. Run” and “Run”. “Pilot vs. Run” and “Run” have already been covered in Section 24.4. We will therefore focus on the “Experiment settings” below.

Experiment settings

The icon for the experiment settings is a cogwheel:

Most relevant in the experiment settings are the Basic tab and the Screen tab. The Basic tab is where you can change 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 can add fields by clicking on a plus sign (e.g., to add fields for age and gender). You can also remove fields by clicking on the minus sign next to a 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]

The easiest way to change the background colour though is to click on the colour picker:

You can then choose a named colour (such as “black” or “cornflowerblue”) simply by clicking on the colour name.

---

1. 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.