Experiment Designer Quick Start

v0.9 | 2026-04-10 16:37 ET — Learn the interface and create your first protocol in minutes.

Interface overview

Top bar: ← Back | Experiment Designer  [Undo] [Redo] [Quick Start] [Import YAML] [Export YAML]
─────────────────────────────────────────────────────────────
Left panel        │  Right panel: [COMMANDS] [TABLE]          [Reset]
                  │
  Experiment      │    Commands: Command card editor
  Arena + Rig     │    Table:    Editable spreadsheet view
  Structure       │
  Phases          │    (select a block on the timeline
  Plugins         │     to populate the editor)
─────────────────────────────────────────────────────────────
Timeline: [+ Add] | summary          [−] [+] [Fit]
  PRE │ Cond 1 │ ITI │ Cond 2 │ ITI │ Cond 3 │ POST
  ────────────────────────────────────────────────
  Lane view: controller ███   ███   ███
              plugins   ●  ●  ●  ●  ●  ●
              waits     ▄▄ ▄▄ ▄▄ ▄▄ ▄▄ ▄▄

The page has three zones:

Left panel — experiment settings, arena + rig path, repetitions, phase toggles, plugin checkboxes
Right panel — two tabs for editing the selected condition or phase: Commands (command cards), Table (editable spreadsheet)
Bottom timeline — your experiment sequence. Green = conditions, gray = phases (PRE/POST), dark = inter-trial intervals (ITI). Click any block to edit it. Below the blocks, a lane view shows controller, plugin, and wait commands across the full experiment.

Walkthrough: create an optomotor protocol

We will build an experiment with 3 stimulus conditions, backlight and camera plugins, 3 repetitions, randomized, with inter-trial intervals.

Set experiment metadata (left panel, top section)

Name: Optomotor Response Test

Author: your name

Pattern Library: the directory where your .pat files live, e.g. /Users/you/patterns/

Choose arena and set rig path (left panel, Arena section)

Select G4.1 (2×12) - 360° from the dropdown.

Rig Path: ./configs/rigs/my_rig.yaml

The arena dropdown sets the visual preview. The rig path is written to the v2 YAML for MATLAB to resolve the full hardware configuration.

Set repetitions and randomization (left panel, Structure section)

Repetitions: 3

Check Randomize order

Enable phases (left panel, Phases section)

Check Pretrial — a gray PRE block appears at the start of the timeline

Check Intertrial — dark ITI blocks appear between conditions

Enable plugins (left panel, Plugins section — scroll down)

Check LED Backlight — config card expands with optional override fields

Check BIAS Camera — config card expands with optional override fields (IP, Port, Video Format, Frame Rate)

Enabling plugins makes their commands available in the "Add Command" dropdown. Config fields like IP, port, and serial port are already set in the rig YAML — leave them empty to use the rig values. Only fill them in if you need to override the rig for this experiment.

Edit the first condition (right panel, Commands tab)

Click the first green condition block on the bottom timeline. The Commands tab shows command cards.

Set the Condition ID: rightward_grating

In the trialParams card: Pattern: pat0002_rightward_grating.pat, Duration: 5, Mode: Constant Rate, Frame Rate: 60

The timeline block updates in real time as you type.

Add plugin commands to the condition

Use the + Add Command... dropdown at the bottom of the card list:

Select Get Timestamp from the BIAS Camera group — a blue plugin card appears

Select Wait — a gray wait card appears (set duration to 3)

Select Set IR LED Power from the LED Backlight group — a blue card appears with a Power field pre-filled with the default value. Set it to 50.

Commands execute sequentially. trialParams fires the arena controller autonomously; plugin and wait commands run during the display period. Plugin commands that accept parameters show editable fields automatically.

Add more conditions

Click + Add Condition in the timeline toolbar. Repeat for a third.

Set IDs like leftward_grating and dark_control. For the dark control, leave Pattern empty to generate an allOff command.

Configure phases

Click the gray PRE block. The phase editor shows command cards just like conditions.

The default is allOff + wait 0.5s. Use the Add Command dropdown to add plugin commands (e.g., Start Recording from BIAS Camera).

Review in Table view

Click the TABLE tab to see all commands across all sections as a spreadsheet.

Collapsible sections show Pretrial, each Condition, Intertrial, and Posttrial with their command lists.

Type badges are color-coded: green = controller, gray = wait, blue = plugin.

Check the lane view

Below the filmstrip blocks, the lane view shows the full experiment as concurrent lanes: controller bars (green), plugin markers (blue dots), and wait bars (gray). The selected block is highlighted.

This shows how trialParams runs autonomously while plugin commands execute at their sequential time positions. Hover over elements for tooltips. The lane view scrolls and zooms in sync with the block strip above.

Export your protocol

Click Export YAML (or press Ctrl+E). A .yaml file downloads.

The file is a valid protocol v2 YAML with rig reference, plugins, and multi-command conditions — ready for MATLAB execution.

Importing an existing protocol

Click Import YAML in the top bar and select any v2 protocol .yaml file. The editor populates with all settings, conditions, plugins, and phases. You can modify and re-export. Import is undoable — press Ctrl+Z to restore your previous experiment.

Try it: Import one of the example protocols from the maDisplayTools repository, such as full_experiment_test.yaml (9 conditions with camera + backlight plugins) to see a fully populated experiment.

Editor tabs

Commands tab

The default editor. Each command is a color-coded card with inline editable fields. Cards have colored left borders: green = controller, gray = wait, blue = plugin. Use the + Add Command... dropdown to add new commands. Click × to delete a command. Use the ▲/▼ arrows to reorder commands within a condition or phase.

Table tab

Shows the entire experiment as an editable spreadsheet with collapsible sections. Each row is one command with columns for Type, Target, Command, Duration, Mode, Frame Rate, and Pattern/Params. Use Expand All / Collapse All buttons to toggle all sections. Within each section you can:

Edit fields inline — click any Duration, Mode, Frame Rate, Pattern, or plugin parameter to edit it directly
Use ▲/▼ arrows to reorder commands
Click × to delete a command or remove a condition
Use the + Add Command... dropdown to add new commands
Use section header arrows to reorder conditions

Timeline controls

+ Add Condition adds a new condition block and selects it
Remove conditions from the Table tab using the × button in the section header
Drag a green condition block onto another to reorder
− / + zoom the timeline in and out
Fit scales the timeline to fit the window

Undo, redo, and reset

Every edit is tracked in an undo history (up to 50 steps). Use Undo / Redo in the top bar, or the keyboard shortcuts below.

Undo / Redo buttons — in the top bar, disabled when the stack is empty
Reset button — red button in the tab bar (right of Commands / Table). Clears all conditions, phases, and plugins back to defaults. Settings (name, author, arena, rig path) are kept. A confirmation dialog appears first. Reset also clears the undo/redo history.

Keyboard shortcuts

Ctrl+Z / Cmd+Z Undo last edit (when not typing in a field)
Ctrl+Y / Ctrl+Shift+Z Redo
Ctrl+E Export YAML
Delete Remove selected condition (when not typing in a field)

Inside a text input, Ctrl+Z uses the browser's native undo (reverts the last keystroke within that field).

Key concepts

Protocol v2

The designer exports YAML protocol v2. Key differences from v1: a rig: reference replaces inline arena_info:, a plugins: section defines hardware plugins, and conditions use command arrays (multiple commands per condition, not just one trialParams).

Conditions vs. Trials

You define conditions (unique stimulus + plugin configurations). The experiment runs each condition × repetitions, optionally in random order. The actual sequence of trials is shown in the summary bar.

Commands

Each condition and phase contains a sequence of commands:

controller — arena commands: trialParams (display pattern), allOn, allOff, stopDisplay
wait — pause execution for a specified duration
plugin — send a command to an enabled plugin (e.g., camera.getTimestamp, backlight.setRedLEDPower)

Plugins

LED Backlight (LEDControllerPlugin): control IR and visible LEDs behind arena panels. Commands: setIRLEDPower, setRedLEDPower, setGreenLEDPower, setBlueLEDPower, turnOnLED, turnOffLED, setVisibleBacklightsOff.

BIAS Camera (BiasPlugin): video recording and timestamps. Commands: connect (manual connection with optional ip/port/config_file), startRecording, stopRecording, startPreview, stopCapture, getTimestamp, disconnect.

Enable plugins in the left panel to make their commands available in the Add Command dropdown.

Phases

Pretrial runs once before all trials. Intertrial runs between every trial. Posttrial runs once after all trials complete. Each phase can contain any combination of controller, wait, and plugin commands.

Modes

Constant Rate (mode 2): pattern plays at a fixed frame rate. Set Frame Rate in fps.

Closed-Loop (mode 4): pattern responds to analog input. Set Gain value.

The irrelevant parameter is automatically dimmed and disabled.

Empty pattern = allOff

If you leave the Pattern File field empty for a trialParams command, the condition exports with an allOff controller command. This is useful for dark control conditions.