-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathexperiment_designer_quickstart.html
More file actions
432 lines (363 loc) · 22.2 KB
/
experiment_designer_quickstart.html
File metadata and controls
432 lines (363 loc) · 22.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Experiment Designer Quick Start - PanelDisplayTools</title>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&family=IBM+Plex+Mono:wght@400;600&display=swap" rel="stylesheet">
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
:root {
--bg: #0f1419;
--surface: #1a1f26;
--border: #2d3640;
--text: #e6edf3;
--text-dim: #8b949e;
--accent: #00e676;
--hover: #00c853;
}
body {
font-family: 'IBM Plex Mono', monospace;
background: var(--bg);
color: var(--text);
padding: 2rem;
line-height: 1.7;
}
.container {
max-width: 820px;
margin: 0 auto;
}
.nav-link {
display: inline-block;
color: var(--text-dim);
text-decoration: none;
margin-bottom: 1.5rem;
font-size: 0.85rem;
transition: color 0.2s;
}
.nav-link:hover { color: var(--accent); }
h1 {
font-family: 'JetBrains Mono', monospace;
font-size: 1.8rem;
font-weight: 700;
color: var(--accent);
margin-bottom: 0.5rem;
}
.subtitle {
color: var(--text-dim);
font-size: 0.85rem;
margin-bottom: 2rem;
padding-bottom: 1.5rem;
border-bottom: 2px solid var(--border);
}
h2 {
font-family: 'JetBrains Mono', monospace;
font-size: 1.1rem;
font-weight: 700;
color: var(--accent);
margin-top: 2.5rem;
margin-bottom: 1rem;
}
h3 {
font-family: 'JetBrains Mono', monospace;
font-size: 0.9rem;
font-weight: 700;
color: var(--text);
margin-top: 1.5rem;
margin-bottom: 0.5rem;
}
p {
margin-bottom: 0.75rem;
font-size: 0.88rem;
}
.step {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 6px;
padding: 1rem 1.25rem;
margin-bottom: 1rem;
position: relative;
padding-left: 3.5rem;
}
.step-number {
position: absolute;
left: 1rem;
top: 1rem;
font-family: 'JetBrains Mono', monospace;
font-weight: 700;
font-size: 1rem;
color: var(--accent);
}
.step strong {
color: var(--accent);
}
.step p {
margin-bottom: 0.4rem;
}
.step p:last-child {
margin-bottom: 0;
}
code {
background: rgba(0, 230, 118, 0.1);
color: var(--accent);
padding: 0.15rem 0.4rem;
border-radius: 3px;
font-family: 'JetBrains Mono', monospace;
font-size: 0.82rem;
}
.hint {
color: var(--text-dim);
font-size: 0.8rem;
font-style: italic;
}
.layout-diagram {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 6px;
padding: 1.25rem;
margin: 1.25rem 0;
font-family: 'JetBrains Mono', monospace;
font-size: 0.72rem;
line-height: 1.5;
white-space: pre;
overflow-x: auto;
color: var(--text-dim);
}
.layout-diagram .hl {
color: var(--accent);
}
.key-list {
list-style: none;
margin: 0.5rem 0 1rem;
}
.key-list li {
padding: 0.3rem 0;
font-size: 0.85rem;
}
.key-list li code {
min-width: 100px;
display: inline-block;
}
.tip-box {
background: rgba(255, 152, 0, 0.08);
border: 1px solid rgba(255, 152, 0, 0.3);
border-radius: 6px;
padding: 0.75rem 1rem;
margin: 1rem 0;
font-size: 0.82rem;
color: #ff9800;
}
.tip-box strong { color: #ffb74d; }
.example-box {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 6px;
padding: 1rem 1.25rem;
margin: 1rem 0;
}
.example-box h4 {
font-family: 'JetBrains Mono', monospace;
font-size: 0.8rem;
color: var(--text-dim);
text-transform: uppercase;
letter-spacing: 0.5px;
margin-bottom: 0.75rem;
}
a {
color: var(--accent);
text-decoration: none;
}
a:hover { color: var(--hover); }
footer {
text-align: center;
margin-top: 3rem;
padding-top: 2rem;
border-top: 2px solid var(--border);
color: var(--text-dim);
font-size: 0.8rem;
}
footer a { color: var(--accent); text-decoration: none; }
footer a:hover { color: var(--hover); }
</style>
</head>
<body>
<div class="container">
<a href="experiment_designer.html" class="nav-link">← Back to Experiment Designer</a>
<h1>Experiment Designer Quick Start</h1>
<p class="subtitle">v0.9 | 2026-04-10 16:37 ET — Learn the interface and create your first protocol in minutes.</p>
<h2>Interface overview</h2>
<div class="layout-diagram"><span class="hl">Top bar</span>: ← Back | Experiment Designer [Undo] [Redo] [Quick Start] [Import YAML] [<span class="hl">Export YAML</span>]
─────────────────────────────────────────────────────────────
<span class="hl">Left panel</span> │ <span class="hl">Right panel</span>: [COMMANDS] [TABLE] [<span class="hl">Reset</span>]
│
Experiment │ Commands: Command card editor
Arena + Rig │ Table: Editable spreadsheet view
Structure │
Phases │ (select a block on the timeline
Plugins │ to populate the editor)
─────────────────────────────────────────────────────────────
<span class="hl">Timeline</span>: [+ Add] | summary [−] [+] [Fit]
<span class="hl">PRE</span> │ <span class="hl">Cond 1</span> │ <span class="hl">ITI</span> │ <span class="hl">Cond 2</span> │ <span class="hl">ITI</span> │ <span class="hl">Cond 3</span> │ <span class="hl">POST</span>
────────────────────────────────────────────────
<span class="hl">Lane view</span>: controller ███ ███ ███
plugins ● ● ● ● ● ●
waits ▄▄ ▄▄ ▄▄ ▄▄ ▄▄ ▄▄</div>
<p>The page has three zones:</p>
<ul class="key-list">
<li><strong>Left panel</strong> — experiment settings, arena + rig path, repetitions, phase toggles, plugin checkboxes</li>
<li><strong>Right panel</strong> — two tabs for editing the selected condition or phase:
<strong>Commands</strong> (command cards), <strong>Table</strong> (editable spreadsheet)</li>
<li><strong>Bottom timeline</strong> — your experiment sequence. Green = conditions, gray = phases (PRE/POST), dark = inter-trial intervals (ITI). Click any block to edit it. Below the blocks, a <strong>lane view</strong> shows controller, plugin, and wait commands across the full experiment.</li>
</ul>
<h2>Walkthrough: create an optomotor protocol</h2>
<p>We will build an experiment with 3 stimulus conditions, backlight and camera plugins, 3 repetitions, randomized, with inter-trial intervals.</p>
<div class="step">
<span class="step-number">1</span>
<p><strong>Set experiment metadata</strong> (left panel, top section)</p>
<p>Name: <code>Optomotor Response Test</code></p>
<p>Author: your name</p>
<p>Pattern Library: the directory where your <code>.pat</code> files live, e.g. <code>/Users/you/patterns/</code></p>
</div>
<div class="step">
<span class="step-number">2</span>
<p><strong>Choose arena and set rig path</strong> (left panel, Arena section)</p>
<p>Select <code>G4.1 (2×12) - 360°</code> from the dropdown.</p>
<p>Rig Path: <code>./configs/rigs/my_rig.yaml</code></p>
<p class="hint">The arena dropdown sets the visual preview. The rig path is written to the v2 YAML for MATLAB to resolve the full hardware configuration.</p>
</div>
<div class="step">
<span class="step-number">3</span>
<p><strong>Set repetitions and randomization</strong> (left panel, Structure section)</p>
<p>Repetitions: <code>3</code></p>
<p>Check <strong>Randomize order</strong></p>
</div>
<div class="step">
<span class="step-number">4</span>
<p><strong>Enable phases</strong> (left panel, Phases section)</p>
<p>Check <strong>Pretrial</strong> — a gray PRE block appears at the start of the timeline</p>
<p>Check <strong>Intertrial</strong> — dark ITI blocks appear between conditions</p>
</div>
<div class="step">
<span class="step-number">5</span>
<p><strong>Enable plugins</strong> (left panel, Plugins section — scroll down)</p>
<p>Check <strong>LED Backlight</strong> — config card expands with optional override fields</p>
<p>Check <strong>BIAS Camera</strong> — config card expands with optional override fields (IP, Port, Video Format, Frame Rate)</p>
<p class="hint">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.</p>
</div>
<div class="step">
<span class="step-number">6</span>
<p><strong>Edit the first condition</strong> (right panel, Commands tab)</p>
<p>Click the first green condition block on the bottom timeline. The Commands tab shows command cards.</p>
<p>Set the Condition ID: <code>rightward_grating</code></p>
<p>In the <strong>trialParams</strong> card: Pattern: <code>pat0002_rightward_grating.pat</code>, Duration: <code>5</code>, Mode: <code>Constant Rate</code>, Frame Rate: <code>60</code></p>
<p class="hint">The timeline block updates in real time as you type.</p>
</div>
<div class="step">
<span class="step-number">7</span>
<p><strong>Add plugin commands to the condition</strong></p>
<p>Use the <strong>+ Add Command...</strong> dropdown at the bottom of the card list:</p>
<p>Select <code>Get Timestamp</code> from the BIAS Camera group — a blue plugin card appears</p>
<p>Select <code>Wait</code> — a gray wait card appears (set duration to <code>3</code>)</p>
<p>Select <code>Set IR LED Power</code> from the LED Backlight group — a blue card appears with a <strong>Power</strong> field pre-filled with the default value. Set it to <code>50</code>.</p>
<p class="hint">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.</p>
</div>
<div class="step">
<span class="step-number">8</span>
<p><strong>Add more conditions</strong></p>
<p>Click <strong>+ Add Condition</strong> in the timeline toolbar. Repeat for a third.</p>
<p>Set IDs like <code>leftward_grating</code> and <code>dark_control</code>. For the dark control, leave Pattern empty to generate an <code>allOff</code> command.</p>
</div>
<div class="step">
<span class="step-number">9</span>
<p><strong>Configure phases</strong></p>
<p>Click the gray <strong>PRE</strong> block. The phase editor shows command cards just like conditions.</p>
<p>The default is <code>allOff</code> + <code>wait 0.5s</code>. Use the Add Command dropdown to add plugin commands (e.g., <code>Start Recording</code> from BIAS Camera).</p>
</div>
<div class="step">
<span class="step-number">10</span>
<p><strong>Review in Table view</strong></p>
<p>Click the <strong>TABLE</strong> tab to see all commands across all sections as a spreadsheet.</p>
<p>Collapsible sections show Pretrial, each Condition, Intertrial, and Posttrial with their command lists.</p>
<p class="hint">Type badges are color-coded: green = controller, gray = wait, blue = plugin.</p>
</div>
<div class="step">
<span class="step-number">11</span>
<p><strong>Check the lane view</strong></p>
<p>Below the filmstrip blocks, the <strong>lane view</strong> shows the full experiment as concurrent lanes: controller bars (green), plugin markers (blue dots), and wait bars (gray). The selected block is highlighted.</p>
<p class="hint">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.</p>
</div>
<div class="step">
<span class="step-number">12</span>
<p><strong>Export your protocol</strong></p>
<p>Click <strong>Export YAML</strong> (or press <code>Ctrl+E</code>). A <code>.yaml</code> file downloads.</p>
<p class="hint">The file is a valid protocol v2 YAML with rig reference, plugins, and multi-command conditions — ready for MATLAB execution.</p>
</div>
<h2>Importing an existing protocol</h2>
<p>Click <strong>Import YAML</strong> in the top bar and select any v2 protocol <code>.yaml</code> file. The editor populates with all settings, conditions, plugins, and phases. You can modify and re-export. <strong>Import is undoable</strong> — press <code>Ctrl+Z</code> to restore your previous experiment.</p>
<div class="tip-box">
<strong>Try it:</strong> Import one of the example protocols from the maDisplayTools repository, such as <code>full_experiment_test.yaml</code> (9 conditions with camera + backlight plugins) to see a fully populated experiment.
</div>
<h2>Editor tabs</h2>
<h3>Commands tab</h3>
<p>The default editor. Each command is a color-coded card with inline editable fields. Cards have colored left borders: <strong style="color: #00e676;">green</strong> = controller, <strong style="color: #8b949e;">gray</strong> = wait, <strong style="color: #4dabf7;">blue</strong> = plugin. Use the <code>+ Add Command...</code> dropdown to add new commands. Click <strong>×</strong> to delete a command. Use the <strong>▲</strong>/<strong>▼</strong> arrows to reorder commands within a condition or phase.</p>
<h3>Table tab</h3>
<p>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 <strong>Expand All</strong> / <strong>Collapse All</strong> buttons to toggle all sections. Within each section you can:</p>
<ul class="key-list">
<li><strong>Edit fields inline</strong> — click any Duration, Mode, Frame Rate, Pattern, or plugin parameter to edit it directly</li>
<li>Use <strong>▲</strong>/<strong>▼</strong> arrows to reorder commands</li>
<li>Click <strong>×</strong> to delete a command or remove a condition</li>
<li>Use the <strong>+ Add Command...</strong> dropdown to add new commands</li>
<li>Use section header arrows to reorder conditions</li>
</ul>
<h2>Timeline controls</h2>
<ul class="key-list">
<li><code>+ Add Condition</code> adds a new condition block and selects it</li>
<li>Remove conditions from the <strong>Table</strong> tab using the <strong>×</strong> button in the section header</li>
<li><strong>Drag</strong> a green condition block onto another to reorder</li>
<li><code>−</code> / <code>+</code> zoom the timeline in and out</li>
<li><code>Fit</code> scales the timeline to fit the window</li>
</ul>
<h2>Undo, redo, and reset</h2>
<p>Every edit is tracked in an undo history (up to 50 steps). Use <strong>Undo</strong> / <strong>Redo</strong> in the top bar, or the keyboard shortcuts below.</p>
<ul class="key-list">
<li><strong>Undo / Redo buttons</strong> — in the top bar, disabled when the stack is empty</li>
<li><strong>Reset button</strong> — red button in the tab bar (right of Commands / Table). Clears all conditions, phases, and plugins back to defaults. <em>Settings</em> (name, author, arena, rig path) are kept. A confirmation dialog appears first. Reset also clears the undo/redo history.</li>
</ul>
<h2>Keyboard shortcuts</h2>
<ul class="key-list">
<li><code>Ctrl+Z</code> / <code>Cmd+Z</code> Undo last edit (when not typing in a field)</li>
<li><code>Ctrl+Y</code> / <code>Ctrl+Shift+Z</code> Redo</li>
<li><code>Ctrl+E</code> Export YAML</li>
<li><code>Delete</code> Remove selected condition (when not typing in a field)</li>
</ul>
<p class="hint">Inside a text input, Ctrl+Z uses the browser's native undo (reverts the last keystroke within that field).</p>
<h2>Key concepts</h2>
<h3>Protocol v2</h3>
<p>The designer exports <strong>YAML protocol v2</strong>. Key differences from v1: a <code>rig:</code> reference replaces inline <code>arena_info:</code>, a <code>plugins:</code> section defines hardware plugins, and conditions use <strong>command arrays</strong> (multiple commands per condition, not just one trialParams).</p>
<h3>Conditions vs. Trials</h3>
<p>You define <strong>conditions</strong> (unique stimulus + plugin configurations). The experiment runs each condition × repetitions, optionally in random order. The actual sequence of <strong>trials</strong> is shown in the summary bar.</p>
<h3>Commands</h3>
<p>Each condition and phase contains a sequence of <strong>commands</strong>:</p>
<ul class="key-list">
<li><strong>controller</strong> — arena commands: <code>trialParams</code> (display pattern), <code>allOn</code>, <code>allOff</code>, <code>stopDisplay</code></li>
<li><strong>wait</strong> — pause execution for a specified duration</li>
<li><strong>plugin</strong> — send a command to an enabled plugin (e.g., <code>camera.getTimestamp</code>, <code>backlight.setRedLEDPower</code>)</li>
</ul>
<h3>Plugins</h3>
<p><strong>LED Backlight</strong> (LEDControllerPlugin): control IR and visible LEDs behind arena panels. Commands: setIRLEDPower, setRedLEDPower, setGreenLEDPower, setBlueLEDPower, turnOnLED, turnOffLED, setVisibleBacklightsOff.</p>
<p><strong>BIAS Camera</strong> (BiasPlugin): video recording and timestamps. Commands: connect (manual connection with optional ip/port/config_file), startRecording, stopRecording, startPreview, stopCapture, getTimestamp, disconnect.</p>
<p class="hint">Enable plugins in the left panel to make their commands available in the Add Command dropdown.</p>
<h3>Phases</h3>
<p><strong>Pretrial</strong> runs once before all trials. <strong>Intertrial</strong> runs between every trial. <strong>Posttrial</strong> runs once after all trials complete. Each phase can contain any combination of controller, wait, and plugin commands.</p>
<h3>Modes</h3>
<p><strong>Constant Rate</strong> (mode 2): pattern plays at a fixed frame rate. Set <code>Frame Rate</code> in fps.</p>
<p><strong>Closed-Loop</strong> (mode 4): pattern responds to analog input. Set <code>Gain</code> value.</p>
<p>The irrelevant parameter is automatically dimmed and disabled.</p>
<h3>Empty pattern = allOff</h3>
<p>If you leave the Pattern File field empty for a trialParams command, the condition exports with an <code>allOff</code> controller command. This is useful for dark control conditions.</p>
<footer>
<p><a href="experiment_designer.html">Experiment Designer</a> | <a href="index.html">PanelDisplayTools</a> | <a href="https://github.com/reiserlab/webDisplayTools" target="_blank">GitHub</a></p>
</footer>
</div>
</body>
</html>