experiment-design

Experiment Design

Design and implement neuroscience experiments with PsychoPy, including stimulus presentation, timing validation, event markers, and Lab Streaming Layer (LSL) integration.

When to Use

• Designing a new behavioral or neuroimaging experiment
• Creating PsychoPy scripts for stimulus presentation
• Setting up event markers via LSL or parallel port
• Validating timing accuracy
• Converting an experiment protocol to code

Experiment Design Principles

Trial Structure

Every trial consists of:

[Fixation] -> [Stimulus] -> [Response Window] -> [Inter-trial Interval]
   |              |               |                    |
  marker       marker          marker              marker

Design Types

Design	Best For	Example
Block	fMRI, sustained attention	30s blocks of condition A, B
Event-related	ERP/EEG, rapid events	Randomized single trials
Mixed	Both sustained and transient	Blocks with jittered events
Resting state	Baseline/connectivity	Eyes open/closed periods

Timing Considerations

• Frame-based timing (preferred): Specify durations in frames, not seconds
• Monitor refresh rate: 60 Hz = 16.67 ms/frame; 120 Hz = 8.33 ms/frame
• Stimulus onset: Sync to vertical blank for precise timing
• Jitter: Add random ITI variation for event-related designs (avoid expectation effects)
• Minimum stimulus duration: 1 frame (16.67 ms at 60 Hz)

PsychoPy Experiment Template

Basic Structure

from psychopy import visual, core, event, data, gui
import numpy as np

# Experiment parameters
exp_info = {
    "participant": "",
    "session": "01",
    "task": "experiment_name",
}

# GUI dialog
dlg = gui.DlgFromDict(exp_info, title="Experiment")
if not dlg.OK:
    core.quit()

# Window setup
win = visual.Window(
    size=[1920, 1080],
    fullscr=True,
    monitor="testMonitor",
    units="deg",
    color=[0, 0, 0],
)

# Stimuli
fixation = visual.TextStim(win, text="+", height=2)
stimulus = visual.ImageStim(win, image=None, size=[10, 10])
feedback = visual.TextStim(win, text="", height=1.5)

# Trial handler
conditions = data.importConditions("conditions.xlsx")
trials = data.TrialHandler(
    conditions,
    nReps=1,
    method="random",
)

# Clock
clock = core.Clock()

# Main experiment loop
for trial in trials:
    # Fixation
    fixation.draw()
    win.flip()
    core.wait(0.5)  # 500 ms fixation

    # Stimulus
    stimulus.image = trial["stimulus_file"]
    stimulus.draw()
    win.flip()
    # Send marker here

    # Response
    clock.reset()
    keys = event.waitKeys(
        maxWait=2.0,
        keyList=["left", "right", "escape"],
        timeStamped=clock,
    )

    if keys:
        if keys[0][0] == "escape":
            core.quit()
        trials.addData("response", keys[0][0])
        trials.addData("rt", keys[0][1])

    # ITI (jittered)
    iti = np.random.uniform(0.8, 1.2)
    core.wait(iti)

# Save data
import os
os.makedirs("data", exist_ok=True)
trials.saveAsWideText(f"data/sub-{exp_info['participant']}_task-{exp_info['task']}.csv")
win.close()
core.quit()