Beginner’s tutorial to get started with Expyriment

How to get started with Expyriment?

To start programming a new experiment you can take any text editor. Preferably one with syntax highlighting for Python of course. (If you are on Windows you might want to use IDLE which is part of the Python installation).

Let’s start right away with a very basic example!

Write the following code into an empty text file and save the file as first_experiment.py:

import expyriment

exp = expyriment.design.Experiment(name="First Experiment")
expyriment.control.initialize(exp)

expyriment.control.start(exp)

expyriment.control.end()

Now run the file by either double clicking on it (if you are on Windows) or by typing the following into a command line:

python first_experiment.py

The following should happen:

  • Expyriment will start up, showing the startup screen and a countdown of 10 seconds
  • “Preparing experiment...” will be presented on the screen (very briefly)
  • You will be asked to enter the subject number
  • “Ready” will be presented on the screen
  • After pressing ENTER “Quitting experiment...” will be presented on the screen

Let’s see what we just did in more detail:

import expyriment

We imported the Expyriment package into Python, such that we can use it there.

exp = expyriment.design.Experiment(name="First Experiment")

expyriment.control.initialize(exp)

We created a new Experiment object by calling the Experiment class in the submodule design and named it “First Experiment”. Immediately after we initialized this experiment to be the active one. This does the following:

  • Present the startup screen with the countdown (which is there to ensure that the Python interpreter has enough time to start up properly and will be time accurate afterwards)
  • Start an experimental clock (which thereafter will be available as _exp.clock_)
  • Create the screen (which thereafter will be available as _exp.screen_)
  • Create an event file (which thereafter will be available as _exp.events_)
  • Present the “Preparing experiment...” screen

expyriment.control.start(exp)

We started running the experiment we just created. This does the following:

  • Present a screen to ask for the subject number (which thereafter will be available as _exp.subject_) and wait for the RETURN key to be pressed
  • Create a data file (which thereafter will be available as _exp.data_)
  • Present the “Ready” screen

expyriment.control.end()

We finished our experiment, so we quit Expyriment. This will automatically save the data as well as the event file and show the “Ending experiment...” screen.

Okay great, now let’s actually do something in this experiment. Let’s say we want to present a stimulus. Change the code to look like this:

import expyriment

exp = expyriment.design.Experiment(name="First Experiment")
expyriment.control.initialize(exp)

stim = expyriment.stimuli.TextLine(text="Hello World")
stim.preload()

expyriment.control.start(exp)

stim.present()
exp.clock.wait(1000)

expyriment.control.end()

If you run the programme now the following should happen:

  • Expyriment will start up, showing the startup screen and a countdown of 10 seconds
  • “Preparing experiment...” will be presented on the screen (very briefly)
  • You will be asked to enter the subject number
  • “Ready” will be presented on the screen
  • After pressing ENTER, “Hello World” will be presented on the screen for 1000 ms
  • “Ending experiment...” will be presented on the screen

Again, let’s look into the new things we added in more detail:

stim = expyriment.stimuli.TextLine(text="Hello World")

We created a text stimulus with the text “Hello World”.

stim.preload()

We preloaded the stimulus into memory (to ensure that this does not happen when presenting it later, since this may take some time).

stim.present()

We presented the stimulus on the screen.

exp.clock.wait(1000)

We waited for 1000 ms, while the stimulus is still on the screen (since we did not present something else afterwards).

Let’s add some common experimental design structures to get a bit more organized. Modify the code to look like this:

import expyriment

exp = expyriment.design.Experiment(name="First Experiment")
expyriment.control.initialize(exp)

block = expyriment.design.Block(name="A name for the block")
trial = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="Hello World")
stim.preload()
trial.add_stimulus(stim)
block.add_trial(trial)
exp.add_block(block)

expyriment.control.start(exp)

stim.present()
exp.clock.wait(1000)

expyriment.control.end()

Running this will show you the same as before. This is, because we only made changes in the experimental design, but not in the experiment conduction!

Here is what we added in detail:

block = expyriment.design.Block("A name for the block")

We created an experimental block by calling the Block class in the design submodule and gave the block then name “Block One”

trial = expyriment.design.Trial()

We created an experimental trial by calling the Trial class in the design submodule.

trial.add_stimulus(stim)

We added our stimulus to the trial.

block.add_trial(trial)

We added our trial to the block.

exp.add_block(block)

We added our block to the experiment.

We now have a nice hierarchical structure:

  • The experiment with one block
  • The block has one trial
  • The trial includes one stimulus

Of course this is only makes sense when more blocks and trials are used. Let’s now create two blocks with 2 Trials each. Each of those trials will have exactly one stimulus. Change the code to look like this:

import expyriment

exp = expyriment.design.Experiment(name="First Experiment")
expyriment.control.initialize(exp)

block_one = expyriment.design.Block(name="A name for the first block")
trial_one = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 1, Trial 1")
stim.preload()
trial_one.add_stimulus(stim)
trial_two = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 1, Trial 2")
stim.preload()
trial_two.add_stimulus(stim)
block_one.add_trial(trial_one)
block_one.add_trial(trial_two)
exp.add_block(block_one)

block_two = expyriment.design.Block(name="A name for the second block")
trial_one = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 2, Trial 1")
stim.preload()
trial_one.add_stimulus(stim)
trial_two = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 2, Trial 2")
stim.preload()
trial_two.add_stimulus(stim)
block_two.add_trial(trial_one)
block_two.add_trial(trial_two)
exp.add_block(block_two)


expyriment.control.start(exp)

for block in exp.blocks:
    for trial in block.trials:
        trial.stimuli[0].present()
        exp.clock.wait(1000)

expyriment.control.end()

When running this the following happens:

  • Expyriment will start up, showing the startup screen and a countdown of 10 seconds
  • “Preparing experiment...” will be presented on the screen
  • You will be asked to enter the subject number
  • “Ready” will be presented on the screen
  • After pressing ENTER, the stimuli are presented in the order: stimuli in trial_one and trial_two of block_one followed by the stimuli in trial_one and trial_two of block_two. All four are presented for 1000 ms
  • “Ending experiment...” will be presented on the screen

Let’s see what we did exactly:

block_one = expyriment.design.Block(name="A name for the first block")

trial_one = expyriment.design.Trial()

sim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 1, Trial 1")

stim.preload()

trial_one.add_stimulus(stim)

trial_two = expyriment.design.Trial()

stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 1, Trial 2)

trial_two.add_stimulus(stim)

block_one.add_trial(trial_one)

block_one.add_trial(trial_two)

We created a block, two trials and two stimuli. We put one of the stimuli in each of the trials, the trials into the block and the block into the experiment.

block_two = expyriment.design.Block(name="A name for the second block")

trial_one = expyriment.design.Trial()

stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 2, Trial 1

stim.preload()

trial_one.add_stimulus(stim)

trial_two = expyriment.design.Trial()

stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 2, Trial 2")

trial_two.add_stimulus(stim)

block_two.add_trial(trial_one)

block_two.add_trial(trial_two)

exp.add_block(block_two)

We created another block with again two trials and two stimuli and connected them like the first one.

for block in exp.blocks:

for trial in block.trials:

trial.stimuli[0].present()

exp.clock.wait(1000)

We loop over all blocks in the experiment (two in our case). For each of the blocks, we loop again over all trials in that block (again two in our case). For each trial we present the first stimulus (because we only added one to each trial). After each stimulus presentation we wait for 1000 ms.

We now want to measure some reaction times after each stimulus presentation. Modify the code to look like this:

import expyriment

exp = expyriment.design.Experiment(name="Text Experiment")
expyriment.control.initialize(exp)

block_one = expyriment.design.Block(name="A name for the first block")
trial_one = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 1, Trial 1")
stim.preload()
trial_one.add_stimulus(stim)
trial_two = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 1, Trial 2")
trial_two.add_stimulus(stim)
block_one.add_trial(trial_one)
block_one.add_trial(trial_two)
exp.add_block(block_one)

block_two = expyriment.design.Block(name="A name for the second block")
trial_one = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 2, Trial 1")
stim.preload()
trial_one.add_stimulus(stim)
trial_two = expyriment.design.Trial()
stim = expyriment.stimuli.TextLine(text="I am a stimulus in Block 2, Trial 2")
trial_two.add_stimulus(stim)
block_two.add_trial(trial_one)
block_two.add_trial(trial_two)
exp.add_block(block_two)

expyriment.control.start(exp)

for block in exp.blocks:
    for trial in block.trials:
        trial.stimuli[0].present()
        key, rt = exp.keyboard.wait([expyriment.misc.constants.K_LEFT,
                                     expyriment.misc.constants.K_RIGHT])
        exp.data.add([block.name, trial.id, key, rt])

expyriment.control.end()

When you run this code, the following happens:

  • Expyriment will start up, showing the startup screen and a countdown of 10 seconds
  • “Preparing experiment...” will be presented on the screen
  • You will be asked to enter the subject numtrial_one.add_stimulusber
  • “Ready” will be presented on the screen
  • After pressing ENTER the stimuli are presented in the order: stimuli in trial_one and trial_two of block_one followed by the stimuli in trial_one and trial_two of block_two. After each presentation the programme waits for the LEFT or RIGHT arrow key to be pressed until it proceeds.
  • “Ending experiment...” will be presented on the screen

Let’s see why this is:

key, rt = exp.keyboard.wait([expyriment.misc.constants.K_LEFT,

expyriment.misc.constants.K_RIGHT])

We waited for a keyboards response which is either the LEFT or the RIGHT arrow key (as defined by a list with those two keys as elements). This function returns the key that was pressed as well as the reaction time.

exp.data.add([block.name, trial.id, key, rt])

We added the name of the block, the id of the trial, the pressed key and the reaction time to the data file (by adding a list with those two as elements). The id of a trial is automatically set when the trial is added to a block.

Now have a look at the “data” and “events” directories (in the same directory where your first_example.py is located). The “data” directory contains data log files, named according to the experiment name, the subject number and a timestamp. The file ending is .xpd. The event directory contains event log files with the ending .xpe. Open the latest data file to see the data we just logged. Notice that the first rows are a header with some information about the file. However, it would be nice to also have the variable names of what is logged in there. To do this, add the following lines above where you start the experiment:

exp.data_variable_names = ["Block", "Trial", "Key", "RT"]

What this does is to add the given names into the data file header, separated by commas.

The last thing to mention in this brief tutorial are the default settings. Each module (control, design, io, stimuli, misc) has its own defaults. Changing these defaults will only have an effect before the corresponding object is created. Thus, a safe place is right at the beginning of your file, just above creating an experiment. Note also that it is handy to overwrite other default settings in the beginning as well, to have one central place for important settings. It might also shorten calls to the classes later on. For instance, the _experiment_name_ can also be set as _mysettings.experiment_name_ and the _name=”Test Experiment”_ parameter is not needed anymore. However, using explicit parameters in the call to classes will overwrite any previous default settings! One of the most common things to do, while developing is to change the default presentation mode from fullscreen to a window:

expyriment.control.window_mode = True

expyriment.control.window_size = (800,600)

Also, when using older machines with very old video cards, you might want to run in fullscreen, but without using OpenGL:

expyriment.control.open_gl = False

That’s it so far. We are at the end of the getting started tutorial. As a summary, have a look at the following code, which again show the overall structure of an Expyriment file with the 3 main parts:

import expyriment

# Any global settings go here

exp = expyriment.control.initialize()

# Create design (blocks and trials)
# Create stimuli (and put them into trials)
# Create input/output devices (like button boxes etc.)

expyriment.control.start(exp)

# Experiment conduction
# Loop over blocks and trials, present stimuli and get user input

expyriment.control.end()

Table Of Contents

Previous topic

Platform-specific instructions: Mac OS X

Next topic

Example Experiments

This Page