Experiment Builder User Manual

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 408

Download
Open PDF In Browser	View PDF

SR Research Experiment Builder
User Manual
Version 2.1.140

Please report all functionality comments and bugs to:
support@sr-research.com

An HTML version of this document, which contains extra sections
on example projects and frequently asked questions, can be
accessed by pressing F1 or clicking “Help → Content” from the
Experiment Builder application, or can be downloaded from
https://www.sr-support.com/forums/showthread.php?t=99.

Table of Contents
Introduction ................................................................................................................... 1
1.1 Features .................................................................................................................. 1
1.2 How to Use This Manual ....................................................................................... 2
1.3 Citing Experiment Builder ..................................................................................... 3
Experiment Builder Experiment Life Cycle ................................................................. 4
2.1 Experiment Design................................................................................................. 4
2.2 Building and Test-running Experiment ................................................................. 5
2.3 Experiment Deployment ........................................................................................ 5
2.4 Participant Data Set Randomization ...................................................................... 6
2.5 Data Collection ...................................................................................................... 6
2.6 Data Analysis ......................................................................................................... 6
Installation..................................................................................................................... 8
3.1 Windows PC System Requirements ...................................................................... 8
3.1.1 Computer Configuration ................................................................................. 8
3.1.2 Maximizing the Real-time Performance of the Display PC ........................... 9
3.1.3 Host Computer and Display Computer Software Requirements .................. 11
3.2 Software Installation and Licensing on Windows ............................................... 11
3.2.1 For Standard Installation (Applicable to Most Users) .................................. 12
3.2.2 For Installation Using Network Licensing .................................................... 12
3.3 Software Installation and Licensing on Mac OS X ............................................. 14
3.3.1 Experiment Builder Installation .................................................................... 14
3.3.2 Other Software Installation ........................................................................... 15
3.3.3 HASP Driver Installation and Licensing ...................................................... 16
Working with Files ..................................................................................................... 18
4.1 Creating a New Project ........................................................................................ 18
4.2 Saving a Project ................................................................................................... 20
4.3 Saving an Existing Project to a Different Directory ............................................ 21
4.4 Opening an Existing Project ................................................................................ 21
4.5 Reopening a Recent Experiment Project ............................................................. 23
4.6 Lock/Unlock a Project ......................................................................................... 24
4.7 Packaging an Experiment .................................................................................... 24
4.8 Unpacking an Experiment.................................................................................... 25
4.9 Building an Experiment ....................................................................................... 25
4.10 Cleaning an Experiment ..................................................................................... 26
4.11 Test-running an Experiment from EB Application ............................................ 26
4.12 Deploying an Experiment .................................................................................. 26
4.13 Running an Experiment for Data Collection ..................................................... 27
4.14 Converting Projects Between Windows and Mac OS X ................................... 29
Experiment Builder Graphical User Interface ............................................................ 30
5.1 Project Explorer Window .................................................................................... 30
5.2 Graph Editor Window .......................................................................................... 34
5.3 Application Menu Bar and Toolbar ..................................................................... 35
5.3.1 File Menu and Tool Buttons ......................................................................... 35
5.3.2 Edit Menu and Tool Buttons ......................................................................... 36
5.3.3 View Menu.................................................................................................... 37

SR Research Experiment Builder User Manual

5.3.4 Experiment Menu and Tool Buttons ............................................................. 37
5.3.5 Help Menu .................................................................................................... 37
6 Designing an Experiment in Experiment Builder ....................................................... 39
6.1 Hierarchical Organization of Experiments .......................................................... 39
6.2 Experiment Graph: Flow Diagram....................................................................... 40
6.2.1 Adding Components to an Experiment ......................................................... 41
6.2.2 Linking Experiment Components ................................................................. 42
6.2.3 Linking Rules ................................................................................................ 42
6.3 Actions ................................................................................................................. 43
6.4 Triggers ................................................................................................................ 44
6.5 Other Node Types ................................................................................................ 45
6.6 Sequence .............................................................................................................. 45
6.7 References and Equations .................................................................................... 46
7 Experiment Graph and Components ........................................................................... 49
7.1 Graph Editing Operations .................................................................................... 49
7.2 Node Connection ................................................................................................. 50
7.2.1 Connection: Create, Cancel, and Delete ....................................................... 50
7.2.2 Connection Order .......................................................................................... 50
7.2.3 Node Exporting and Importing ..................................................................... 51
7.2.3.1 Exporting................................................................................................ 51
7.2.3.2 Importing................................................................................................ 52
7.3 Layout of Nodes in Work Space .......................................................................... 53
7.4 Editing Properties of a Node ................................................................................ 54
7.5 Experiment Node ................................................................................................. 55
7.6 Sequence .............................................................................................................. 57
7.6.1 Typical Use of Sequences in an Experiment ................................................ 60
7.6.2 EyeLink Recording Status Message ............................................................. 63
7.7 Start Node ............................................................................................................ 64
7.8 Actions ................................................................................................................. 64
7.8.1 Display Screen .............................................................................................. 65
7.8.1.1 Reading Display Time ........................................................................... 68
7.8.1.2 Using Display Screen Actions ............................................................... 69
7.8.2 Performing Drift Correction ......................................................................... 70
7.8.3 Performing Camera Setup and Calibration ................................................... 75
7.8.4 Sending EyeLink Message............................................................................ 81
7.8.5 Sending EyeLink Command ......................................................................... 83
7.8.6 Sending TTL Signals .................................................................................... 86
7.8.7 Adding to Experiment Log ........................................................................... 89
7.8.8 Updating Attribute ........................................................................................ 91
7.8.9 Adding to Accumulator................................................................................. 93
7.8.10 Adding to Results File ................................................................................ 93
7.8.11 Prepare Sequence ........................................................................................ 94
7.8.12 Reset Node .................................................................................................. 98
7.8.13 Playing Sound ............................................................................................. 98
7.8.14 Play Sound Control ................................................................................... 105
7.8.15 Record Sound ............................................................................................ 107

SR Research Experiment Builder User Manual

7.8.16 Record Sound Control............................................................................... 109
7.8.17 Terminating an Experiment ...................................................................... 111
7.8.18 Recycle Data Line ..................................................................................... 112
7.8.19 Execute Action .......................................................................................... 114
7.8.20 Null Action................................................................................................ 115
7.8.21 ResponsePixx LED Control ...................................................................... 117
7.9 Triggers .............................................................................................................. 119
7.9.1 Timer Trigger .............................................................................................. 119
7.9.2 Invisible Boundary Trigger ......................................................................... 122
7.9.2.1 The Location Type of the Invisible Boundary Trigger ........................ 126
7.9.2.2 How to Show the Triggering Region on the Host PC? ........................ 128
7.9.3 Conditional Trigger..................................................................................... 129
7.9.4 EyeLink Button Trigger .............................................................................. 133
7.9.4.1 Calculating Response Time of a Button Press ..................................... 135
7.9.4.2 Collecting Inputs from the EyeLink Button Box Without Ending the
Trial
136
7.9.4.3 Knowing the ID of a Specific Button on the EyeLink Button Box ..... 137
7.9.5 Cedrus Button Trigger ................................................................................ 138
7.9.5.1 Calculating Response Time of a Button Press ..................................... 141
7.9.5.2 Collecting Inputs from the Cedrus Button Box Without Ending the Trial
142
7.9.6 Keyboard Trigger ........................................................................................ 143
7.9.6.1 Calculating Response Time from a Keyboard Input............................ 146
7.9.6.2 Collecting Inputs from the Keyboard Without Ending the Trial ......... 148
7.9.6.3 Enabling Multiple Keyboards .............................................................. 149
7.9.6.4 Disabling / Re-enabling the Windows Logo Keys .............................. 150
7.9.7 Mouse Trigger............................................................................................. 150
7.9.7.1 Mouse Press, Release, Scroll, and Mouse Over................................... 154
7.9.7.2 Center Location Type vs. Top-left Location Type. ............................. 156
7.9.7.3 Calculating Response Time of a Mouse Click ..................................... 158
7.9.7.4 Collecting Inputs from the Mouse Without Ending the Trial .............. 159
7.9.7.5 Resetting the Initial Position of the Mouse Device ............................. 160
7.9.7.6 Enabling Multiple Mice ....................................................................... 160
7.9.7.7 Recording Mouse Traces in a Data File ............................................... 161
7.9.8 TTL Input Trigger ....................................................................................... 162
7.9.8.1 Setting the Pin Values .......................................................................... 165
7.9.8.2 TTL Trigger and the Type of Cable Used ........................................... 166
7.9.9 Fixation Trigger .......................................................................................... 167
7.9.9.1 Optimal Triggering Duration ............................................................... 171
7.9.9.2 Top-left vs. Center Triggering Location Type ..................................... 172
7.9.9.3 How to Show the Triggering Region on the Host PC.......................... 173
7.9.10 Saccade Trigger ........................................................................................ 174
7.9.10.1 Top-left vs. Center Triggering Location Type ................................... 177
7.9.10.2 Online RT Calculation ....................................................................... 179
7.9.10.3 How to Show the Triggering Region on the Host PC........................ 179
7.9.11 Sample Velocity Trigger ........................................................................... 180

SR Research Experiment Builder User Manual

iii

7.9.11.1 Top-left vs. Center Triggering Location Type ................................... 185
7.9.11.2 How to Show the Triggering Region on the Host PC........................ 186
7.9.12 Voice Key Trigger .................................................................................... 187
7.9.12.1 How to Calculate the Voice Key RT Online ..................................... 189
7.9.12.2 How to Align the Recordings in the Audio File and Eye Tracker Event
Time
190
7.10 Other Building Components ............................................................................ 192
7.10.1 Variable ..................................................................................................... 192
7.10.2 Results File ............................................................................................... 195
7.10.3 Accumulator.............................................................................................. 198
7.10.4 Custom Class Instance .............................................................................. 201
8 Screen Builder........................................................................................................... 203
8.1 Resources ........................................................................................................... 204
8.1.1 Image Resource ........................................................................................... 204
8.1.1.1 Image Displaying Modes ..................................................................... 210
8.1.1.2 Gaze-Contingent Window Manipulations ........................................... 210
8.1.1.3 Transparency Manipulation ................................................................. 211
8.1.2 Video Resource ........................................................................................... 212
8.1.2.1 Reading Frame Time............................................................................ 217
8.1.2.2 Video Frame Timing ............................................................................ 217
8.1.2.3 Video Frame Rate and Display Retrace Rate ...................................... 218
8.1.2.4 Pausing, Unpausing, and the Status of Video Playing ......................... 219
8.1.2.5 Dropping Frames ................................................................................. 220
8.1.2.6 Frame Caching ..................................................................................... 221
8.1.2.7 Video Codec......................................................................................... 221
8.1.2.8 Playing Video Clips with Audio .......................................................... 223
8.1.3 Text Resource ............................................................................................. 223
8.1.3.1 Non-ASCII Characters ......................................................................... 226
8.1.3.2 Anti-aliasing and Transparency ........................................................... 226
8.1.4 Multiline Text Resource ............................................................................. 228
8.1.5 Line Resource ............................................................................................. 232
8.1.6 Rectangle Resource ..................................................................................... 234
8.1.7 Ellipse Resource.......................................................................................... 236
8.1.8 Triangle Resource ....................................................................................... 239
8.1.9 Freeform Resource ...................................................................................... 241
8.2 Movement Patterns ............................................................................................ 244
8.2.1 Sinusoidal Movement Pattern ..................................................................... 244
8.2.2 Custom Movement Pattern ......................................................................... 246
8.2.2.1 Option 1: Adding Resource Postions ................................................... 247
8.2.2.2 Option 2: Movement Pattern File ........................................................ 249
8.3 Interest Areas ..................................................................................................... 251
8.3.1 Manually Creating an Interest Area ............................................................ 252
8.3.1.1 Rectangular/Elliptic Interest Area........................................................ 252
8.3.1.2 Freeform Interest Area ......................................................................... 253
8.3.2 Automatic Segmentation ............................................................................. 253
8.3.3 Using Interest Area Set Files ...................................................................... 255

SR Research Experiment Builder User Manual

8.4 Resource Operations .......................................................................................... 257
8.4.1 Resource Editing ......................................................................................... 257
8.4.2 Resource Alignment.................................................................................... 257
8.4.3 Resource Locking ....................................................................................... 259
8.4.4 Resource Grouping ..................................................................................... 260
8.4.5 Composite Resource ................................................................................... 261
8.4.6 Resource Order ........................................................................................... 263
8.4.7 Others .......................................................................................................... 264
9 Data Source ............................................................................................................... 266
9.1 Creating Data Source ......................................................................................... 267
9.2 Editing Data Source ........................................................................................... 267
9.3 Importing Existing Files as Data Source ........................................................... 271
9.4 Using Data Source File ...................................................................................... 272
9.5 Data Source Splitby ........................................................................................... 273
9.6 Data Source Randomization .............................................................................. 273
9.6.1 Internal Randomization ............................................................................... 274
9.6.1.1 Randomization Seed ............................................................................ 274
9.6.1.2 Blocking ............................................................................................... 275
9.6.1.3 Trial randomization and Run Length Control ...................................... 276
9.6.1.4 Randomize on Roll-Over ..................................................................... 276
9.6.1.5 Splitting Column .................................................................................. 276
9.6.1.6 Running Experiment with Internal Randomizer .................................. 277
9.6.2 External Randomization.............................................................................. 277
10 References ............................................................................................................... 280
10.1 Using References ............................................................................................. 280
10.2 Entering in Values............................................................................................ 281
10.3 Entering in References ..................................................................................... 281
10.4 Entering in Equations....................................................................................... 282
10.4.1 Creating a Complex String: Formatting and Concatenating ..................... 283
10.4.2 Examples ................................................................................................... 284
10.5 Reference Manager .......................................................................................... 285
11 EyeLink Data Viewer Integration ........................................................................... 287
11.1 Trial Condition Variables ................................................................................ 287
11.2 Images and Interest Areas ................................................................................ 288
12 Custom Class .......................................................................................................... 290
12.1 Enabling the Custom Class Option .................................................................. 290
12.2 Creating a New Custom Class ......................................................................... 290
12.3 Syntax of Custom Class ................................................................................... 291
12.3.1 Example .................................................................................................... 292
12.3.2 Class Definition ........................................................................................ 294
12.3.3 Class Initialization .................................................................................... 294
12.3.4 Class Attributes ......................................................................................... 294
12.3.5 Class Methods ........................................................................................... 295
12.3.6 'setX' and 'getX' Methods .......................................................................... 296
12.4 Instantiating Custom Class .............................................................................. 297
12.5 Using Custom Class ......................................................................................... 299

SR Research Experiment Builder User Manual

12.6 Using the Custom Class Editor ........................................................................ 300
13 Creating Experiments: Overview ............................................................................ 303
14 Creating EyeLink Experiments: The First Example ............................................... 304
14.1 Creating the Experiment .................................................................................. 304
14.1.1 Creating a New Experiment Project ......................................................... 304
14.1.2 Configuring Experiment Preference Settings ........................................... 305
14.1.3 Creating the Experiment Block Sequence ................................................ 308
14.1.4 Editing the Block Sequence ...................................................................... 309
14.1.5 Creating the Instructions Screen ............................................................... 311
14.1.6 Editing the Trial Sequence: Data Source .................................................. 313
14.1.7 Editing the Trial Sequence: Preparing Sequence and Drift Correction .... 315
14.1.8 Editing the Recording Sequence ............................................................... 316
14.1.9 Modifying the Properties of a Display Screen .......................................... 317
14.1.10 Creating the Display Screen.................................................................... 318
14.1.11 Writing Trial Condition Variables to EDF file ....................................... 320
14.1.12 Showing Experiment Progress Message on Tracker Screen................... 321
14.2 Building the Experiment .................................................................................. 321
14.3 Deploying the Experiment ............................................................................... 322
14.4 Running the Experiment .................................................................................. 322
14.4.1 Error in Initializing Graphics .................................................................... 322
14.4.2 Error in Tracker Version ........................................................................... 323
15 Creating Non-EyeLink Experiments: Stroop Effect .............................................. 324
15.1 Creating a New Experiment Project ................................................................ 324
15.2 Configuring Experiment Preference Settings .................................................. 325
15.3 Creating the Experiment Block Sequence ....................................................... 327
15.4 Editing the Block Sequence ............................................................................. 328
15.5 Creating the Instruction Screen ........................................................................ 330
15.6 Editing the Trial Sequence: Data Source ......................................................... 332
15.7 Editing the Trial Sequence: Setting Initial Values and Preparing Sequence ... 335
15.8 Editing the Trial Event Sequence – Part 1 ....................................................... 339
15.8.1 Creating the Fixation Screen ..................................................................... 341
15.8.2 Creating the Stroop Display Screen. ......................................................... 342
15.9 Editing the Trial Event Sequence – Part 2 ....................................................... 344
15.10 Outputting Data to the Results File................................................................ 350
15.11 Running the Experiment ................................................................................ 351
16 Experiment Builder Project Check List (version 2.1) ............................................. 352
17 Preference Settings.................................................................................................. 356
17.1 Experiment ....................................................................................................... 356
17.1.1 EyeLink ..................................................................................................... 358
17.1.2 Display ...................................................................................................... 365
17.1.3 Audio......................................................................................................... 367
17.1.4 Mouse........................................................................................................ 368
17.1.5 Keyboard ................................................................................................... 370
17.1.6 Cedrus ....................................................................................................... 372
17.1.7 EyeLink Button Box Device ..................................................................... 373
17.1.8 Parallel Port............................................................................................... 374

SR Research Experiment Builder User Manual

17.1.9 USB-1208HS Box..................................................................................... 375
17.1.10 Timer ....................................................................................................... 376
17.1.11 Invisible Boundary .................................................................................. 376
17.1.12 Conditional.............................................................................................. 377
17.1.13 EyeLink Button ....................................................................................... 377
17.1.14 Cedrus Input ............................................................................................ 377
17.1.15 Keyboard ................................................................................................. 377
17.1.16 Mouse...................................................................................................... 377
17.1.17 TTL Trigger ............................................................................................ 377
17.1.18 Fixation ................................................................................................... 377
17.1.19 Saccade ................................................................................................... 377
17.1.20 Sample Velocity ...................................................................................... 377
17.1.21 Voice Key ............................................................................................... 377
17.1.22 Display Screen ........................................................................................ 377
17.1.23 Drift Correct ............................................................................................ 377
17.1.24 Camera Setup .......................................................................................... 377
17.1.25 Send EyeLink Message ........................................................................... 377
17.1.26 Send Command ....................................................................................... 377
17.1.27 Set TTL ................................................................................................... 378
17.1.28 Add to Experiment Log .......................................................................... 378
17.1.29 Update Attribute...................................................................................... 378
17.1.30 Add to Accumulator ................................................................................ 378
17.1.31 Add to Results File ................................................................................. 378
17.1.32 Prepare Sequence .................................................................................... 378
17.1.33 Sequence ................................................................................................. 378
17.1.34 Reset Node .............................................................................................. 378
17.1.35 Play Sound .............................................................................................. 378
17.1.36 Play Sound Control ................................................................................. 378
17.1.37 Record Sound .......................................................................................... 378
17.1.38 Record Sound Control............................................................................. 378
17.1.39 Terminate Experiment ............................................................................ 378
17.1.40 Recycle Data Line ................................................................................... 378
17.1.41 Execute.................................................................................................... 378
17.1.42 Null Action.............................................................................................. 379
17.1.43 ResponsePixx LED Control .................................................................... 379
17.1.44 Accumulator............................................................................................ 379
17.1.45 Results File ............................................................................................. 379
17.2 Screen............................................................................................................... 379
17.2.1 Screen........................................................................................................ 379
17.2.2 Image Resource ......................................................................................... 380
17.2.3 Video Resource ......................................................................................... 380
17.2.4 Text Resource ........................................................................................... 380
17.2.5 Multiline Text Resource ........................................................................... 380
17.2.6 Line Resource ........................................................................................... 380
17.2.7 Rectangle Resource ................................................................................... 380
17.2.8 Ellipse Resource........................................................................................ 380

SR Research Experiment Builder User Manual

17.2.9 Triangle Resource ..................................................................................... 380
17.2.10 Freeform Resource .................................................................................. 380
17.2.11 Sine Pattern ............................................................................................. 380
17.2.12 Grid Segmentation .................................................................................. 381
17.2.13 Auto Segmentation.................................................................................. 381
17.2.14 Word Segmentation ................................................................................ 382
17.3 Build/Deploy .................................................................................................... 385
17.4 GUI .................................................................................................................. 386
17.4.1 Graph_Layout ........................................................................................... 387
17.4.2 CustomClass_Editor ................................................................................. 388
18 Revision History ..................................................................................................... 389

SR Research Experiment Builder User Manual

List of Figures
Figure 3-1. Driver Installation for USB-1208 HS DAQ. .................................................. 12
Figure 3-2. Choosing “Custom” Setup Type. .................................................................. 13
Figure 3-3. Enabling HaspHL Driver Option for Network License. ............................... 13
Figure 3-4. Installing Experiment Builder on Mac OS X. ............................................... 15
Figure 3-5. Updating Experiment Builder License on Mac OS X. .................................. 17
Figure 4-1. File Menu. ..................................................................................................... 18
Figure 4-2. Dialog for Creating a New Project. ............................................................... 19
Figure 4-3. Warning Messages after Experiment Creation. ............................................ 20
Figure 4-4. Open an Experiment Builder Project. ........................................................... 22
Figure 4-5. Save Confirmation When Opening a New Project. ...................................... 22
Figure 4-6. Change in Video Environment When Opening a New Project. .................... 23
Figure 4-7. Reopening Recent Experiment Projects. ....................................................... 23
Figure 4-8. Unlock a Locked Project. .............................................................................. 24
Figure 4-9. Unpacking an Experiment Project. ............................................................... 25
Figure 4-10. Experiment Menu. ....................................................................................... 26
Figure 5-1. Sample Experiment Builder Interface. .......................................................... 30
Figure 5-2. The View Menu............................................................................................. 31
Figure 5-3. Components of the Project Explorer Window. ............................................. 32
Figure 5-4. Different Tabs of the Structure Panel............................................................ 33
Figure 5-5. Components of the Graph Editor Window.................................................... 35
Figure 6-1. Hierarchical Organization of Events in an Experiment. ............................... 40
Figure 6-2. Sample Experiment Sequence. ...................................................................... 41
Figure 6-3. Connecting Between Source and Target Components. .................................. 42
Figure 6-4. Nested Sequences in an Experiment. ............................................................ 46
Figure 6-5. Using a Reference to Update Text to Be Displayed. .................................... 48
Figure 7-1. Connection Order. ......................................................................................... 50
Figure 7-2. Exporting Node. ............................................................................................ 52
Figure 7-3. Reference Maintenance. ................................................................................ 52
Figure 7-4. Export Library Files. ..................................................................................... 52
Figure 7-5. Importing Node. ............................................................................................ 53
Figure 7-6. Choosing Layout of Components in Work Space. ........................................ 54
Figure 7-7. Property Field Editable with Attribute Reference Editor. ............................. 55
Figure 7-8. Properties of the Experiment Node. .............................................................. 57
Figure 7-9. Using Sequences in an Experiment. .............................................................. 62
Figure 7-10. Creating Recording Status Message............................................................ 63
Figure 7-11. Sending the Recording Status Message to the Tracker. .............................. 64
Figure 7-12. Action Tab of the Component Toolbox. ..................................................... 65
Figure 7-13. Using Display Screen. ................................................................................. 70
Figure 7-14. Using Drift Correction Action. ................................................................... 75
Figure 7-15. Using Camera Setup Action. ....................................................................... 81
Figure 7-16. Using Sending Message Action. ................................................................. 83
Figure 7-17. Using Sending EyeLink Command Action. ................................................ 86
Figure 7-18. Configuring the Direction of Data Flow on USB-1208HS ......................... 89
Figure 7-19. Using Add to Experiment Log Action. ....................................................... 90
Figure 7-20. Using Update Attribute Action. .................................................................. 92

SR Research Experiment Builder User Manual

Figure 7-21. Using Prepare Sequence Action. ................................................................. 97
Figure 7-22. Adding Audio Files to the Library Manager. .............................................. 99
Figure 7-23. Choose Audio Driver. ............................................................................... 100
Figure 7-24. Setting ASIO Buffer Latency. ................................................................... 102
Figure 7-25. Using Play Sound Action. ......................................................................... 105
Figure 7-26. Using Play Sound Control Action. ............................................................ 107
Figure 7-27. Using Record Sound Action...................................................................... 109
Figure 7-28. Using Terminate Experiment Action. ....................................................... 112
Figure 7-29. Using Recycle Dataline Action. ................................................................ 114
Figure 7-30. Using a NULL_ACTION node. ................................................................ 117
Figure 7-31. Using a ResponsePixx LED Control Action. ............................................ 119
Figure 7-32. Triggers Implemented in Experiment Builder. ......................................... 119
Figure 7-33. Using Timer Trigger. ................................................................................ 122
Figure 7-34. Using an Invisible Boundary Trigger. ....................................................... 126
Figure 7-35. Using Invisible_Boundary Trigger with Top-left and Center Location
Types. ...................................................................................................................... 127
Figure 7-36. Drawing the Trigger Region on Host PC. ................................................. 129
Figure 7-37. Using Conditional Trigger. ....................................................................... 131
Figure 7-38. Displaying different instruction screens at the beginning of each block. . 132
Figure 7-39. Using EyeLink Button Trigger.................................................................. 135
Figure 7-40. Collecting EyeLink Button Response Data............................................... 136
Figure 7-41. Checking EyeLink Button Response Accuracy. ....................................... 136
Figure 7-42. Using EyeLink Button Trigger Without Ending a Trial. .......................... 137
Figure 7-43. Using Cedrus Button Trigger. ................................................................... 141
Figure 7-44. Collecting Cedrus Button Response Data. ................................................ 142
Figure 7-45. Checking Cedrus Button Response Accuracy........................................... 142
Figure 7-46. Using Cedrus Button Trigger Without Ending a Trial. ............................. 143
Figure 7-47. Using Keyboard Trigger. .......................................................................... 146
Figure 7-48. Collecting Keyboard Response Data. ....................................................... 147
Figure 7-49. Checking Keyboard Response Accuracy. ................................................. 148
Figure 7-50. Using Keyboard Without Ending a Trial. ................................................. 149
Figure 7-51. Using the Mouse Trigger. ......................................................................... 155
Figure 7-52. Setting the Mouse Triggering Region. ...................................................... 156
Figure 7-53. Using Mouse Trigger with Top-left and Center Location Types. ............. 158
Figure 7-54. Collecting Mouse Response Data. ............................................................ 159
Figure 7-55. Checking Mouse Response Accuracy. ...................................................... 159
Figure 7-56. Using Mouse Trigger Without Ending a Trial. ......................................... 160
Figure 7-57. Viewing Mouse Traces in the Data Viewer Temporal Graph View. ........ 162
Figure 7-58. Using TTL Trigger. ................................................................................... 166
Figure 7-59. Using Fixation Trigger. ............................................................................. 171
Figure 7-60. Using Fixation Trigger with Top-left and Center Location Types. .......... 173
Figure 7-61. Using the Saccade Trigger. ....................................................................... 177
Figure 7-62. Using Saccade Trigger with Top-left and Center Location Types. .......... 179
Figure 7-63. Using Sample Velocity Trigger. ............................................................... 184
Figure 7-64. Using Sample Velocity Trigger with Top-left and Center Location Types.
................................................................................................................................. 186

SR Research Experiment Builder User Manual

Figure 7-65. Collecting the Voicekey Response Data. .................................................. 190
Figure 7-66. Aligning Audio Recording Times. ............................................................ 191
Figure 7-67. Other Components Implemented in Experiment Builder.......................... 192
Figure 7-68. Using a Variable. ....................................................................................... 193
Figure 7-69. Property Settings for Variables. ................................................................ 194
Figure 7-70. Dynamic Data Type Casting. .................................................................... 195
Figure 7-71. Using Results File. .................................................................................... 196
Figure 7-72. Setting Properties of the Results File Node. ............................................. 197
Figure 7-73. Using Accumulator. .................................................................................. 199
Figure 7-74. Setting the Properties of Accumulator. ..................................................... 200
Figure 7-75. Adding Data to and Retrieving Data from the Accumulator. ................... 201
Figure 8-1. Sample View of the Screen Builder Interface. ............................................ 204
Figure 8-2. Resources Implemented in Screen Builder. ................................................ 204
Figure 8-3. Loading Images into Image Library. ........................................................... 205
Figure 8-4. Setting Different Location Types for Images Used in a Gaze-Contingent
Window Application. .............................................................................................. 211
Figure 8-5. Loading Video Clips into Video Library. ................................................... 213
Figure 8-6. Video Frame Rate and Display Retrace Rate. ............................................. 219
Figure 8-7. Pausing and Unpausing Video Play ............................................................. 220
Figure 8-8. Xvid Configuration. .................................................................................... 222
Figure 8-9. Setting UTF-8 Encoding. ............................................................................ 226
Figure 8-10. Aliased and Anti-aliased Texts. ................................................................ 227
Figure 8-11. Antialiasing Drawing Preference Setting. ................................................. 227
Figure 8-12. Setting the Transparency Color for the Experiment. ................................ 228
Figure 8-13. Multiline Text Resource Editor. ................................................................ 229
Figure 8-14. Creating a Movement Pattern.................................................................... 244
Figure 8-15. Adding Resource Positions to a Custom Movement Pattern. ................... 247
Figure 8-16. Creating a Custom Movement Pattern. ..................................................... 248
Figure 8-17. Creating a File-based Custom Movement Pattern. ................................... 250
Figure 8-18. Toggling Interest Area Visibility. ............................................................. 252
Figure 8-19. Creating an Interest Area. ......................................................................... 252
Figure 8-20. Creating Interest Area with Auto Segmentation. ...................................... 254
Figure 8-21. Creating Interest Area with Grid Segmentation. ....................................... 255
Figure 8-22. Resource Alignment (Left) and Toggling Grid Visibility......................... 258
Figure 8-23. Snap to Grid. ............................................................................................. 259
Figure 8-24. Error When Trying to Modify a Locked Resource. .................................. 259
Figure 8-25. Resource Grouping.................................................................................... 260
Figure 8-26. Creating a Composite Resource. ............................................................... 261
Figure 8-27. Two Resources with Different Resource Order. ....................................... 263
Figure 8-28. Changing the Order of Resources. ............................................................ 264
Figure 8-29. Choosing "Fit to Screen" Option............................................................... 264
Figure 8-30. Save Screen as Image. ............................................................................... 265
Figure 9-1. Using Data Source in Experiment Builder. ................................................. 266
Figure 9-2. Change the Type of Variables. .................................................................... 267
Figure 9-3. Adding New Rows to the Data Source. ...................................................... 268
Figure 9-4. Data Types Used in Experiment Builder. ................................................... 269

SR Research Experiment Builder User Manual

Figure 9-5. Editing Operations for Data Source Columns and Rows. ........................... 269
Figure 9-6. Editing Data Source Cells. .......................................................................... 270
Figure 9-7. Importing an Existing File as Data Source. ................................................ 270
Figure 9-8. Importing an Existing File as Data Source. ................................................ 271
Figure 9-9. Append or Overwrite Confirmation. ........................................................... 271
Figure 9-10. Choosing a Data Set File during Run-Time. ............................................. 272
Figure 9-11. Using "Split by" Option to Customize the Number of Iterations to Run in a
Sequence. ................................................................................................................ 273
Figure 9-12. Using Internal Randomization. ................................................................. 274
Figure 9-13. Setting Randomization Seed. .................................................................... 274
Figure 9-14. Configuring Randomization Blocking. ..................................................... 275
Figure 9-15. Enabling Trial Randomization and Configuring Run-Length Control. .... 276
Figure 9-16. Configuring Splitting Column. ................................................................. 276
Figure 9-17. Selecting Condition Value to Run............................................................. 277
Figure 9-18. Using External Randomization. ................................................................ 278
Figure 10-1. Using Attribute References. ...................................................................... 281
Figure 10-2. Creating Equations in the Attribute Editor................................................ 283
Figure 10-3. Using the Reference Manager. .................................................................. 286
Figure 11-1. Editing Trial ID Message. ......................................................................... 288
Figure 12-1. Creating a New Custom Class................................................................... 291
Figure 12-2. Attributes and Properties of a Custom Class Instance. ............................. 298
Figure 12-3. Assigning Attribute Values through Custom Class Instance. ................... 299
Figure 12-4. Data Exchange through Execute Action. .................................................. 300
Figure 12-5. Custom Class Code Editor. ....................................................................... 301
Figure 12-6. Custom Class Find/Replace Dialog Box. .................................................. 302
Figure 14-1. Creating a New Experiment Builder Project. ............................................ 305
Figure 14-2. Configuring Preference Settings. .............................................................. 306
Figure 14-3. Setting the Screen Preferences. ................................................................. 307
Figure 14-4. Setting the Tracker Version for the Experiment. ...................................... 307
Figure 14-5. Setting the File Encoding for the Project. ................................................. 308
Figure 14-6. Creating Experiment Block Sequence. ..................................................... 309
Figure 14-7. Editing Block Sequence. ........................................................................... 310
Figure 14-8. Adding Instruction to Block Sequence. .................................................... 311
Figure 14-9. Adding Multiline Text Resource onto a Display Screen. ......................... 312
Figure 14-10. Create Instruction Screen. ....................................................................... 313
Figure 14-11. Creating Data Source. ............................................................................. 314
Figure 14-12. Editing Trial Sequence. ........................................................................... 315
Figure 14-13. Editing Recording Sequence. .................................................................. 316
Figure 14-14. Modifying the Properties of DISPLAY_SCREEN Action. .................... 318
Figure 14-15. Adding Text to Display Screen. .............................................................. 318
Figure 14-16. Showing Text by Referring to Data Source. ........................................... 319
Figure 14-17. Configuring the EyeLink DV Variables. ................................................ 320
Figure 14-18. Creating Trial Recording Status Message. .............................................. 321
Figure 14-19. Error in Initializing Graphics. ................................................................. 323
Figure 14-20. Error in Tracker Version. ........................................................................ 323
Figure 15-1. Creating a New Experiment Builder Session. ........................................... 324

SR Research Experiment Builder User Manual

Figure 15-2. Editing Project Display Preferences.......................................................... 325
Figure 15-3. Setting the Screen Preferences. ................................................................. 326
Figure 15-4. Editing Project Build/Deploy Preferences. ............................................... 327
Figure 15-5. Creating Experiment Block Sequence. ..................................................... 327
Figure 15-6. Editing Block Sequence. ........................................................................... 328
Figure 15-7. Adding Instruction to Block Sequence. .................................................... 330
Figure 15-8. Adding Multiline Text Resource onto a Display Screen. ......................... 331
Figure 15-9. Create Instruction Screen. ......................................................................... 332
Figure 15-10. Creating Data Source. ............................................................................. 333
Figure 15-11. Adding a New Data Source Column. ...................................................... 334
Figure 15-12. Data Source Randomization. ................................................................... 335
Figure 15-13. Editing Trial Sequence. ........................................................................... 336
Figure 15-14. Updating Trial Index. .............................................................................. 337
Figure 15-15. Update Trial Iteration. ............................................................................. 338
Figure 15-16. Updating the Attribute of RT. ................................................................. 338
Figure 15-17. Editing Recording Sequence. .................................................................. 339
Figure 15-18. Setting Response Keys. ........................................................................... 340
Figure 15-19. Loading Resources to Image Library. ..................................................... 341
Figure 15-20. Loading Resources to Image Library. ..................................................... 342
Figure 15-21. Adding Text to Display Screen. .............................................................. 343
Figure 15-22. Showing Text by Referring to Data Source. ........................................... 344
Figure 15-23. Editing the Trial Event Sequence. ........................................................... 345
Figure 15-24. Add Attribute-Value Pairs to the UPDATE_ATTRIBUTE Node. .......... 346
Figure 15-25. Accessing the TriggeredData Attribute. .................................................. 346
Figure 15-26. Evaluating the Accuracy of the Response Using a Conditional Trigger 347
Figure 15-27. Loading Feedback Audio Clips. .............................................................. 348
Figure 15-28. Send Results to a Results File. ................................................................ 349
Figure 15-29. Adding Variables to Results File. ........................................................... 350
Figure 17-1. Accessing the Experiment Builder Preference Settings. ........................... 356

SR Research Experiment Builder User Manual

1 Introduction
The SR Research Experiment Builder (SREB) is a visual experiment creation tool for use
by Psychologists and Neuroscientists on Windows and Mac OS X. Experiment Builder is
designed to be easy to use while maintaining a high degree of flexibility. This unique
design combination allows for a wide range of experimental paradigms to be created by
someone with little or no programming or scripting expertise. When used in combination
with an SR Research EyeLink® eye tracking system, Experiment Builder provides
seamless integration into the EyeLink hardware and software platform.

1.1 Features
Experiment Builder provides a comprehensive graphical experiment creation
environment and contains functionality that addresses a wide variety of research needs
encountered by eye tracking researchers. This functionality allows users to create
everything from simple experiments in which each trial shows a static screen of text or
picture and then waits for a response from the participant, to highly sophisticated
experiments in which complex gaze-contingent event sequences can be scheduled with
excellent timing precision.
Experiments are created in the Experiment Builder by dragging and dropping experiment
components into a workspace and configuring the properties of the added components.
There are two main classes of experiment components in the Experiment Builder: actions
and triggers. Actions tell the computer to do something, like displaying a set of graphics
on the screen or playing a sound. Triggers define the conditions that must be met before
an action can be performed. Examples of triggers are keyboard events and eye (Fixation,
Saccade, and Invisible Boundary) events.
The flow of the experiment is achieved by connecting sequentially related components in
the workspace in a flow diagram-like fashion. For example, a Display Screen action may
be connected to a Keyboard trigger, which is in turn connected to another Display Screen
action. This simple Action → Trigger → Action sequence would result in a given set of
graphics being displayed until users press a button, at which time a second set of graphics
would be displayed. Detailed discussion on the experiment component connection or
linking process, including a set of "rules" for linking experiment components together,
can be found in Section 6.2 “Experiment Graph: Flow Diagram”.
As a convenient tool for creating eye-tracking experiments, Experiment Builder is fully
integrated with EyeLink eye trackers. Performing camera setup, calibration, validation,
and drift correction can be achieved by simply inserting the appropriate action in the
experiment. A single check box can be enabled to record eye movements for a period of
time. Online eye position data (e.g., fixation, saccade, or instantaneous eye sample) can
be used to drive display changes in gaze-contingent or gaze-control applications. In
addition, users can set eye-tracker preferences and send commands and messages to the
EyeLink tracker.
SR Research Experiment Builder User Manual

With these capabilities, Experiment Builder allows users to focus on stimulus
presentation and data analysis. Recording data collected from experiments created by
Experiment Builder is fully integrated with EyeLink Data Viewer. For example,
Experiment Builder automatically sends messages to the EDF file when a screen is
displayed so that images and/or simple drawings can be used as overlay background in
Data Viewer for visualizing gaze data relative to onscreen stimuli. Experiment Builder
also allows users to specify condition variables for a trial and to add interest areas to
display screens, which may be used in Data Viewer’s analysis tools. Finally, the users
can send custom messages to the EDF file so that time critical or important events can be
marked in the data file and used to guide future analyses.
Experiment Builder also contains a built-in Screen Builder utility that makes the creation
of 2D visual displays easier. The Screen Builder is a what-you-see-is-what-you-get
("WYSIWYG") tool, allowing users to create and view 2D visual stimuli right within the
Experiment Builder application. The Screen Builder allows various types of graphic
resources (movies, images, text, or simple line drawings) to be added to a Display Screen
action. The exact properties of the resources can be further modified from a property
panel. In addition, Screen Builder supports creation of both static and dynamic displays.
In a dynamic display, users can have some resources on the screen move along a prespecified movement pattern, or make the position of the resources contingent on the
current eye or mouse position.
Experiment Builder is highly configurable. Nearly all of the properties of experiment
components can be modified. This can be done either by directly entering the parameter
values or, more flexibly, by attribute reference and equations (i.e., setting the value of
one parameter to the value of another parameter, variable, or data source column). With
this dynamic reference capability, a typical experiment requires the users to create a
prototype of experiment conditions while leaving all parameter settings (e.g., experiment
trial condition labeling, images to be used, text to be shown, positions of the resources) to
be handled by a data source. This makes the randomization of trials across participants
easier. In addition, attribute reference allows users to access some run-time data so that
useful experiment manipulations such as conditional branching, displaying appropriate
feedback, and creating new variables can be made.

1.2 How to Use This Manual
This manual is intended for users who are using version 2.0 or later of SR Research
Experiment Builder. If you are still using an earlier version of the software, please
download the latest version from https://www.srsupport.com/forums/showthread.php?t=9. The latest version of this document can be
obtained from https://www.sr-support.com/forums/showthread.php?t=99. (Note: you
must be a registered user of https://www.sr-support.com to access these updates and the
Experiment Builder usage discussion forum.) If you have feature requests or bug reports,
please send an e-mail to support@sr-research.com. If you have questions on using the
software, please check out the "Frequently Asked Questions" and "Experiment Builder

SR Research Experiment Builder User Manual

Project Checklist" sections of the user manual (html version), the Experiment Builder
usage discussion forum, or send us an e-mail.
To use Experiment Builder effectively, it might help if you follow Chapter 14 "Creating
EyeLink Experiments: The First Example" to re-create the "SIMPLE" example by
yourself and get a sense of the life cycle of experiment creation and data collection with
Experiment Builder. The present section can be used as a "Getting Started" guide. You
should also read the following sections of the document very carefully as they discuss the
basic concepts of Experiment Builder software: Chapter 2 "Experiment Builder Life
Cycle", Chapter 6 "Designing an Experiment in Experiment Builder", Chapter 9 "Data
Source", and Chapter 10 "References". Following this, you can then take a look at other
examples we provided (see the .html version of this document for detailed explanations
of the examples) and start reading other sections. Chapter 16 “Experiment Builder Project
Checklist” may be used to make sure common problems can be avoided when creating
your experiments. Users who are new to the Experiment Builder software are
recommended to check out the series of brief instructional videos at our support forums https://www.sr-support.com/showthread.php?4682 - as they are an excellent introduction
to the basics of how the software works.

1.3 Citing Experiment Builder
Please use the following to cite the Experiment Builder software in your manuscript:
SR Research Experiment Builder 2.1.140 [Computer software]. (2017). Mississauga,
Ontario, Canada: SR Research Ltd.

SR Research Experiment Builder User Manual

2 Experiment Builder Experiment Life Cycle
The following sequence of steps is required in order to create an experiment with
Experiment Builder:
• Experiment Design
• Building and Test-running Experiment
• Deploying Experiment
• Participant Data Set Randomization (optional)
• Data Collection
• Data Analysis

2.1 Experiment Design
Whilst Experiment Builder simplifies many of the tasks required for creating an
experiment, a good understanding of experiment design (e.g., blocking, counterbalancing,
factorial design, etc.) and experience with the EyeLink system makes the initial use of
Experiment Builder easier. In the stage of experiment design, users need to do the
following:
1) Conceptualizing the Experiment. Users should have a clear concept of the
experiment before creating it. Which variables will be manipulated in the
experiment? Within each trial, how is the display presented: a static display or a
dynamic display? Can the same display presentation routine be used across all
conditions or should a different routine be created for each of the experiment
conditions? This allows users to contemplate all of the possible trial types in the
experiment, design conditional branching if necessary, and create a data source
for providing parameters which change from trial to trial (e.g. image filenames /
trial durations etc). Once this is done, study one or more of the sample
experiments supplied with Experiment Builder before creating your own project.
2) Creating a New Experiment Session. Start the Experiment Builder application
and create a new experiment session. Please read Chapter 4 “Working with Files”
for details on experiment creation and file/folder management.
3) Adding Experiment Building Blocks to the Graph. To schedule an array of
events in an experiment, users need to add individual building blocks (triggers,
actions, sequences, and other components) to the workspace in the Graph Editor
Window. Connecting components by arrowed lines, which represent sequence
and dependency relationships, forms the experiment flow. Please read Chapter 6
on experimental flow and Chapter 7 on the components of Experiment Builder.
4) Modifying Properties of Experiment Components. Users will need to change the
default settings for the actions, triggers, and sequences so that the experiment can
be run as intended. For example, if a timer trigger is used, users may change the
Duration property of the trigger. If an invisible-boundary trigger is used, the
desired triggering location needs to be specified. Similarly, users need to supply
data for all actions. For example, if a display screen action is used, users need to
add different resources into the screen builder and adjust the layout of the
resources in the screen. To change the default settings for triggers, actions, and

SR Research Experiment Builder User Manual

subsequences, and make the new values available for future uses, users may make
the modification through the preference settings of the Experiment Builder
application (see Chapter 17).
5) Creating a Data Source. Experiment Builder allows users to create prototypical
trials for the experiment and to supply actual parameters for individual trials from
a data source. A data source can be created within Experiment Builder or by
loading a text file. The use of a data source makes the creation of experiments
more efficient and less error-prone. It also makes the randomization of trial order
across participants easier (see Chapter 9 “Data Source” for details).
6) Saving the Experiment Session. After the experiment is generated, don’t forget
to save the experiment session so that it can be re-opened later on. If you are
creating an experiment by modifying one of the example scripts, don't forget to
uncheck the Read Only property of the script before saving.

2.2 Building and Test-running Experiment
After the experiment is created, the next step is to see whether there are any errors in the
experiment graph (for example, failing to make a connection between items, incomplete
data source, wrong data type used, etc). Users can compile the experiment by clicking on
"Experiment → Build" menu to build the experiment. Build time errors (in red) or
warnings (in orange) will be displayed in the "Output" tab of the Graph Editor Window.
In most cases, clicking on the error or warning message will select the experiment
component at issue and thus enable users to quickly identify and fix the problem.
Please note that the above build process just checks whether there are obvious mistakes in
the experiment graph but does not check for the content and validity of the experiment
itself. Therefore, users should test-run the experiment on a couple of participants to see
whether the experiment behaves exactly as intended. By clicking on "Experiment → Test
Run", the experiment will be executed from within the Experiment Builder application.
For an EyeLink experiment, a connection to the tracker PC will be made and users may
record some data using mouse simulation, or with an actual participant. The EDF data file
should be carefully examined to see whether all of the trial condition variables are
properly recorded, whether interest areas and images are shown correctly, whether timecritical and other important messages are recorded for analysis, and so on. For a nonEyeLink experiment, users may rely on a message-log file or results file to debug the
experiment.
Important Note: Every time "Experiment → Test Run" is performed, the experiment is
rebuilt and all of previous data files in the experiment directory are deleted. Do not use
"Experiment → Test Run" for collecting real experiment data; "Experiment → Test Run"
is intended for testing purposes only.

2.3 Experiment Deployment
After fixing errors in the experiment graph and checking that the experiment is working
as intended, users can then deploy the experiment to a new directory. This will generate a
set of folders and files in the intended directory. Please note that the "Experiment → Test
Run" step mentioned in the previous section must be used only for the purpose of testing
SR Research Experiment Builder User Manual

and debugging the experiment graph. To collect experiment data, users must use a
deployed version of the experiment as this does not rely on the Experiment Builder
application (and also does not require the license key to run). In addition, running the
deployed version of an experiment generally has a better timing performance than
running it directly from the Experiment Builder application because the computer is not
running the Experiment Builder interface at the same time as the experiment. To run an
experiment on a different computer, users should copy the entire directory of the
deployed version of the experiment to the new experiment computer, assuming the latter
is running on the same operating system as the original computer and has the required
hardware (e.g., monitor, sound card, response device) for the proper execution of the
experiment. If a different operating system is used, the user will need to deploy the
original Experiment Builder project again on the new computer. The experiment should
be run at least once and results validated on the new computer before starting full data
collection from multiple participants.

2.4 Participant Data Set Randomization
As mentioned earlier, users typically first create prototypical trials for the experiment in
the software and then supply the actual parameters of individual trials from a data source.
In many experiments, users will want to randomize trial order so that the experiment
materials are not presented in the same sequence across participants. Randomization of
data source can be done with either an internal randomizer or an external randomizer.
These two randomization methods are almost identical and therefore users may use the
internal randomizer to perform randomization unless complicated counterbalancing or
Latin-square designs are needed.
Please note that configuration of the internal randomization settings should be done
before deploying the experiment project whereas the external randomization can be done
after deploying the experiment project (see Chapter 9 “Data Source”).

2.5 Data Collection
Data can now be collected from the deployed version of the experiment. Double click the
executable file in the deployed experiment directory or type in the .exe file name from the
command-line prompt. If the experiment uses a data source, and the “Prompt for Dataset
File” property of the relevant sequence has been checked, a dialog will be displayed,
allowing users to choose the appropriate data source file. In an EyeLink Experiment,
users will also be asked to enter an EDF file name. At the End of experiment, an EDF
file will be generated for EyeLink recording session and saved in the experiment
directory. Optional results file(s) will be created if users have specified them in EyeLink
and non-EyeLink experiments.

2.6 Data Analysis
EyeLink Data Files can be conveniently analyzed with EyeLink Data Viewer as
experiments created with Experiment Builder are fully integrated with this analysis tool.
Experiment Builder sends messages to the data file so that images or simple drawing can
be added as overlay background by Data Viewer. Users can also specify trial variables,
SR Research Experiment Builder User Manual

create interest areas, and send messages for the ease of data analysis. Experiment Builder
can also create results files, which contain columnar outputs for selected variables in the
experiment. This file can be easily loaded by common statistics packages. This can be
useful for non-EyeLink experiments.

SR Research Experiment Builder User Manual

3 Installation
Version 2.0 of Experiment Builder runs on both Windows (32-bit and 64-bit of Windows
XP, Vista, Windows 7, Windows 8, and Windows 10) and Mac OS X (Intel CPU, OS
v10.6 or later). The current section covers system requirements for computers used to
create and run experiments with Experiment Builder as well as installation and licensing
issues.

3.1 Windows PC System Requirements
The computer recommendations for SR Research Experiment Builder are in a large part
dependent on the experimental paradigm being run. For example, an experiment that
simply displays a single screen of text and waits for a manual response can run on a
computer with much lower specifications than an experiment where video presentation is
occurring during the trial. We recommend that you buy the best computer you can for
running your experiments, even if you do not immediately plan on using all the features
of the computer. The following computer specifications are guidelines only. SR Research
can be contacted for input on what computer specifications would best match your actual
experiment designs.
IMPORTANT: Regardless of the computer used and the experimental design, it is
critical to evaluate the timing of the experiment to ensure it operates as expected.

3.1.1 Computer Configuration
This recommended PC configuration should handle any experiment that can be created
by SR Research Experiment Builder, including video presentation, saccade-contingent
display changes, accurately timed audio presentation, audio recording, and ASIO-based
voice key support.
•
•
•
•
•
•
•
•
•
•

Recent Intel CPUs with duo-core/multi-core processor
Windows 7 (32-bit or 64-bit), or Windows 10 (32-bit or 64-bit)
At least 4 GB of memory
250 GB or larger hard disk with 7,200 or higher rpm, or solid-state hard drive
A recent video card with at least 1.0 GB of memory and OpenGL 2.0 support
Monitor that supports high refresh rate
ASIO-Compatible Sound Device ***
Keyboard and Mouse
Free USB ports (for Experiment Builder key)
A dedicated Ethernet port to connect the Display PC to the EyeLink Host PC.

*** Any DirectX compatible sound card can be used for hearing calibration and drift
correction feedback tones and playing audio files where exact audio timing is not
important to the experiment. In cases where accurate audio timing is important, or if the
audio recording and/or computer-base voice key features of the software will be used,
then a supported ASIO-compliant audio card or USB device must be available in the PC.
The following cards have been tested and the results of the ASIO driver tests are listed

SR Research Experiment Builder User Manual

below. SR Research strongly recommends that you use a card from the table that supports
the features required for your experiment.
ASIO-compatible Sound
Card

Windows
XP

64-bit
Windows
7
Supported

32-bit
Windows
10
Supported

64-bit
Windows
10
Supported

Format

32-bit
Windows
7
Supported

Creative Labs Sound
Blaster Audigy 5/ RX
(SB1550)
Asus Xonar DS
Asus Xonar DGX

No
No

Supported
Supported

PCI
PCIExpress
PCIExpress

PCIExpress

Asus Xonar DX
No
Supported Supported Supported Supported
(Please note this card
requires one available 4pin power cable from PC's
power supply unit.)
M-Audio M-Track 2x2M
No
Supported Supported Supported Supported USB *
M-Audio M-Track Plus II
No
Supported Supported Supported Supported USB *
*
Steinberg UR22MKII
No
Supported Supported Supported Supported USB *
* It's our understanding that performance of a USB-based sound card can be influenced by the presence of
other USB and wireless devices etc, in addition to the buffer latency settings on the card. So if your
display computer can use PCI or PCI-Express sound cards, please use those sound cards instead of the
USB one.

For details on the currently supported and legacy sound card selection and installation,
please see section “Installation → System Requirements → ASIO Card Installation” in
the html version of this document. This can be accessed by pressing F1 or clicking “Help
→ Content” when running Experiment Builder software, or downloaded from
(https://www.sr-support.com/forums/showthread.php?t=99).

3.1.2 Maximizing the Real-time Performance of the Display PC
If you have options to tweak/reconfigure computer hardware, the following
enhancements in particular will improve performance:
• Install more and/or faster RAM
• Upgrade to a better video card
• Use a SSD (Solid State Drive) instead of HDD (Hard Disk Drive)
To maximize the real-time performance of the Display PC, users should do the following:
• Shut down all other applications (browser windows, chat clients, email programs,
etc.) prior to running an EyeLink experiment. These applications are listed in the
taskbar at the bottom of the screen.
• Shut down any programs (volume controller, Windows Messenger, Google
Desktop, etc.) running in the notification area of the taskbar where you usually
see the current time displayed (lower-right corner of the screen). In Windows 10,

SR Research Experiment Builder User Manual

•

•
•
•
•

•

click “Settings → System → Notifications & Actions”. Set “Notifications – Get
notifications from apps and other senders” to “Off”.
Remove live tiles from the Start menu of Windows 10. Open the Start menu,
right-click a tile and select “Unpin from Start”. Now do that for every single tile
on the right side of the Start menu.
Make sure no scheduled tasks (e.g., data backup, virus checking, Windows
Update) are active.
Remove unnecessary devices (e.g., flash drive, external hard drive) connected to
the computer.
Scan the computer for virus, spyware, and malware. However, turn off the
antivirus program when you run experiments.
Shut down screen-saver management. On Windows 7, click the right mouse
button at a blank space on the Display PC desktop and choose “Personalize” from
the popup menu. Click the "Screen Saver" icon at the bottom-right corner of the
window, and set the screen saver to “None” in the following dialog box. On
Windows 10, click “Settings → Personalization → Lock Screen”. Click the
“Screen Saver Settings” at the bottom of the “Lock Screen” page.
Choose a high performance power setting. On Windows 7, click “Control Panel
→ Power options”. Choose the “High Performance” option in the “Select a
power plan” page. On Windows 10, click “Settings → System → Power and
Sleep”. Choose “Never” for both the Screen and Sleep dropdown lists. Click the
“Additional Power Settings” button. Choose the “High Performance” option in
the “Choose or Customize a power plan” page.
For a computer with multiple Ethernet cards installed, use the Windows Control
Panel to temporarily disable all network connections except for the one dedicated
for EyeLink connection. Disable wi-fi and Bluetooth when they are not in use.
Uninstall any unneeded programs on the PC (e.g., the bloatware and trial software
supplied by the manufacturer of the computer). If you are using an NVIDIA video
card, make sure the “NVIDIA GeForce Experience” program is not installed.
Stop some of the unnecessary services running at the background. For example
you can stop the Index “Windows Search” process. Press Ctrl + Alt + Del three
keys together to start the Task Manager. Click the “Services” tab. Find the
“WSearch” by name, select the service and click the right mouse button, and
choose “Stop”. Now click the “Processes” tab and review the applications and
processes listed. On Windows 10, you can pretty much kill all processes listed in
the “Background processes” section except for Cortana and a few Windows
processes. If you are using an NVidia video card, make sure the “NVIDIA
Backend” or “NvBackend.exe” process is disabled in the Processed list.
WARNING: Disabling the wrong service could hurt performance, or even
cripple Windows. If you do not truly know what you are doing, then it's highly
recommended not to do this.
If you are using a recent NVidia graphics card, please make sure NVIDIA
Streamer Service, NVIDIA Streamer Network Service and NVIDIA Streamer
User Agent are disabled. Type services.msc in the Windows search box to start
the Services Window. If you find these services listed in the Services Window,

SR Research Experiment Builder User Manual

•

select the process, click the Stop button to disable it for the session, and set the
“Start type” to “Disabled”.
Stop all virtual machines if you have them running (e.g., virtual box, hyper-v
services, vmware, etc). Make sure that the idling CPU usage of the computer is
very low.
To run the experiment project, go to the deployed folder, and double click the file
.exe file in the folder. Click “Yes” in the following “User Account Control”
dialog box. Please don’t collect data by using the “Test Run” option from the
Experiment Builder software. Please make sure the Experiment Builder
application window(s) is closed before you collect data with your experiment.

3.1.3 Host Computer and Display Computer Software Requirements
SR Research Experiment Builder works with EyeLink I, II, 1000, 1000 Plus, and Portable
Duo eye trackers.
• EyeLink I users should make sure that version 2.11 of the eyelink.exe file
(https://www.sr-support.com/forums/showthread.php?t=45) is installed on the
Host PC.
• EyeLink II users should use a recent version (2.0 or later) of eyelink2.exe
(https://www.sr-support.com/forums/showthread.php?t=11).
• Any version of EyeLink 1000 host software will be fine, although version 4.56 or
later is recommended (https://www.srsupport.com/forums/showthread.php?t=179).
• Any version of EyeLink 1000 Plus host software will be fine, although the latest
version is recommended (https://www.sr-support.com/showthread.php?4256).
• If using EyeLink Data Viewer for data analysis, users should make sure to install
the most recent version of the software (https://www.srsupport.com/showthread.php?4434).

3.2 Software Installation and Licensing on Windows
The latest version of Experiment Builder installer can be downloaded from
https://www.sr-support.com/forums/showthread.php?t=9. If you have a previous version
of Experiment Builder installed on the computer, please choose the “Clean Install” option
to remove the existing version of the software and install the new version. By default,
Experiment Builder will be installed at "{Windows Drive}:\Program Files (x86)\SR
Research\Experiment Builder" for 64-bit Windows or "{Windows Drive}:\Program
Files\SR Research\Experiment Builder" for 32-bit Windows. Click
ExperimentBuilderW.exe (or “Start → All Programs → SR Research → Experiment
Builder”) to run the software.
Users can run the Experiment Builder software in demo mode immediately. All of the
functionality of the licensed copy of Experiment Builder is available in the demo mode
except that experiments created with a demo version of the software will not re-open
using a fully-licensed version of the software. An "UNLICENSED DEMO VERSION"

SR Research Experiment Builder User Manual

watermark will be drawn on every display screen in an experiment that is created with the
demo version of the software.
To run Experiment Builder in a fully licensed mode, users need to purchase a license key
for the software and have a USB license key connected to the computer on which the
Experiment Builder software is installed. If this is the first time that the USB license key
has been used on the Display PC, you will need to install the HASP key driver.

3.2.1 For Standard Installation (Applicable to Most Users)
The following installation instructions are applicable to users who use a standalone USB
license key that supports a single-PC license.
1. Install the Experiment Builder software. Double click the sreb_2.*.exe installer
and proceed, keeping all the default settings. You may see the following dialog
box (Figure 3-1) if this is the first time Experiment Builder is installed on the PC.
This is a confirmation whether you want to install device driver for USB-1208HS
DAQ box. You may choose either “Install” or “Don’t Install” to proceed.

Figure 3-1. Driver Installation for USB-1208 HS DAQ.
2. If this is the first time that the USB license key has been used on the computer,
install the standalone HASP key driver. First plug the license key into the Display
PC. Then install the driver by clicking "Start → All Programs → SR Research →
Install HASP Driver", or by double clicking on "hdd32.exe" in the "C:\Program
Files (x86)\SR Research\Common" folder.
3. Open the License Manager utility (Start → All Programs → SR Research →
License Manager) to check the licensing status for the Experiment Builder
software.

3.2.2 For Installation Using Network Licensing
The following instructions are applicable to users who have purchased a network license
(i.e., a shared license for several computers on a network that are running Experiment
Builder at the same time) for Experiment Builder.
1. Install the Experiment Builder software. Double click the sreb_2.*.exe installer
and proceed, keeping the default settings on InstallShield Wizard screens except
for the following two:

SR Research Experiment Builder User Manual

•

On the "Setup Type" dialog box, select "Custom" (See Figure 3-2).

Figure 3-2. Choosing “Custom” Setup Type.
• On the "Select Feature" screen, make sure that both "HASP4" and "HASPHL"
driver options are selected (see Figure 3-3).

Figure 3-3. Enabling HaspHL Driver Option for Network License.
2. Install the network HASP key driver by clicking "Start → All Programs → SR
Research → HASP HL Driver", or by double clicking on "hdd32.exe" in
"C:\Program Files (x86)\SR Research\Common" folder.
3. Install the network HASP License Manager by clicking "Start → All Programs →
SR Research → Networked HASP License Manager, or by double clicking on
SR Research Experiment Builder User Manual

"lmsetup.exe" in "C:\Program Files (x86)\SR Research\Common" folder. Failing
to install this will report a "NO HASP Key Found" error in the SR License
Manager dialog box.
• When installing the License Manager, set the "Installation Type" to Service
(nhsrvice.exe).
• On the "HASP License Manager" dialog box, check either Yes or No to
continue.
4. If this is the server computer, you may install the optional Aladdin Monitor
software by clicking "Start → All Programs → SR Research → Aladdin Monitor"
from your computer desktop or double clicking on "aksmon32.exe" in
"C:\Program Files (x86)\SR Research\Common" folder.
5. Test the license status.
• Please make sure the server and client computers are running and visible to
each other in the same network group (check this out from "My Network Places
→ View Network computers"). Contact your system administrator if the
computers cannot see each other in the same network group.
• Please make sure the network license key is plugged into the server computer
and that the drivers are already installed. Remove any other HASP keys from the
server computer.
• Then click "Start → All Programs → SR Research → License Manager" to
check the licensing status for each of the client computers in the network.
Note: If you are using Experiment Builder for developing EyeLink experiments,
test running experiments must be done using a secondary network card unless the
EyeLink Host PC also stays on the same network as the other computers.

3.3 Software Installation and Licensing on Mac OS X
SR Research Experiment Builder runs on most recent Intel-based Macs (software version
Mac OS X 10.6 and higher). The computer recommendations are in a large part
dependent on the experimental paradigm being run; it is always suggested to get the best
computer you can for running your experiments, even if you do not immediately plan on
using all the features of the computer.

3.3.1 Experiment Builder Installation
The latest version of Experiment Builder installer can be downloaded from
https://www.sr-support.com/forums/showthread.php?t=9. If you have a previous version
of Experiment Builder installed on the computer, please uninstall it first by removing the
"/Applications/ExperimentBuilder" folder to Trash. Now click the dmg installer of the
software. Select the "ExperimentBuilder" folder in the package, and drag and drop it into
the "Applications" folder (see Figure 3-4). The software is now installed at
"/Applications/ExperimentBuilder". Click "ExperimentBuilder.app" to run the software.
The examples can be found in the "~/Documents/ExperimentBuilder Examples" folder.

SR Research Experiment Builder User Manual

Figure 3-4. Installing Experiment Builder on Mac OS X.

If you see the error message “ExperimentBuilder is damaged and can’t be opened” when
you try installing the software, please click the Apple logo in the top-left corner and
select “System Preferences”, then go to “Security & Privacy” and under the General tab
make sure “Allow apps downloaded from:" is set to “Anywhere” (you may need to click
the padlock to make changes).
If you are using the recent Mac OS X, you may be prompted to download legacy Java 6
from this link: https://support.apple.com/kb/DL1572?locale=en_GB and install it.

3.3.2 Other Software Installation
SR Research Experiment Builder works with EyeLink I, II, 1000, 1000 Plus, and Portable
Duo eye trackers.
• EyeLink I users should make sure that version 2.11 of the eyelink.exe file
(https://www.sr-support.com/forums/showthread.php?t=45) runs on the Host PC.
• EyeLink II users should use a recent version (2.0 or later) of eyelink2.exe
(https://www.sr-support.com/forums/showthread.php?t=11).
• Any version of EyeLink 1000 host software will be fine, although version 4.56 or
later is recommended (https://www.srsupport.com/forums/showthread.php?t=179).
• Any version of EyeLink 1000 Plus host software will be fine, although the latest
version is recommended (https://www.sr-support.com/showthread.php?4256).
• If using EyeLink Data Viewer for data analysis, you should get the most recent
version of the software (https://www.sr-support.com/showthread.php?4434).

SR Research Experiment Builder User Manual

3.3.3 HASP Driver Installation and Licensing
Users can run Experiment Builder in demo mode immediately for 30 days from the first
installation of the software on the computer. All of the functionality of the licensed copy
of Experiment Builder is available in the demo mode except that Experiments created
with a demo version of the software will not re-open using a fully-licensed version of the
software. An "UNLICENSED DEMO VERSION" watermark will be drawn on every
display screen in an experiment that is created with the demo version of the software.
To run Experiment Builder in a fully licensed mode, users need to purchase a license
code for the software and have a USB license key connected to the computer on which
the Experiment Builder software is installed. If this is the first time that the USB license
key has been used on your Mac, you will need to install the driver for the HASP key. The
driver installer can be found in the "Hasp" folder after unpacking the Experiment Builder
installer .dmg (see Figure 3-4). Double click the "Sentinel_HASP_RTE_Installer.dmg"
file and then run the "Install HASP SRM Runtime Environment" application with the
default settings. If the driver installation is successful and the USB license key is attached
to the computer, the licene key should glow.
If your key is not licensed for the Experiment Builder software, you will need to contact
sales@sr-research.com to purchase a license for the software. If your key is already
licensed for the Windows version of the software, you may update the license for the Mac
version remotely by following the steps below; please contact support@sr-research.com
if you have trouble updating the key.
• Make sure you have an internet connection on your Mac.
• Start the LicenseManager application, which is located at
"/Applications/ExperimentBuilder".
• From the "File" menu at the top-left corner of the desktop, click "Get
ExperimentBuilder Mac License". In the following dialog box, click “Update”
(see Figure 3-5).

SR Research Experiment Builder User Manual

Figure 3-5. Updating Experiment Builder License on Mac OS X.

SR Research Experiment Builder User Manual

4 Working with Files
Experiment Builder can be used to create, build/test run, and deploy experiments on
either Windows (XP, Vista, Windows 7, 8, or 10) or Mac OS X (10.6.8 or later). Each
experiment creation session generates a binary file (graph.ebd), which contains the
graphic layout of the experiment, and a set of supporting files and directories for
preference settings, image loading, etc. With these files, the experiment creation session
can be reopened later for review or modification. After the experiment is built, users can
deploy the experiment to a new directory. This will generate a set of files so that the
experiment can be run on a different computer without relying on the Experiment Builder
application.

4.1 Creating a New Project
To create a new experiment project, from the application menu bar, choose (see Figure 41):
File → New
Tip: A new experiment project can also be created by clicking on the "New Experiment"
button ( ) on the application toolbar, or by pressing the shortcut keys Ctrl+N on
Windows or Command ⌘+N on Mac OS X.

Figure 4-1. File Menu.
This will bring up a “New Project” dialog (see Figure 4-2), prompting for the experiment
project name and a directory in which the experiment project should be saved. Enter the
name for the experiment in the “Project Name” edit box. Click the “…” button to the
right of the "Project Location" field to browse to the directory where the experiment files
should be saved; if you are manually entering the "Project Location" field, please make
SR Research Experiment Builder User Manual

sure that the intended directory already exists. In both cases, please make sure you have
writing permission for the selected directory. If your intended project is an EyeLink
experiment, make sure to check the "EyeLink Experiment" box and choose the
appropriate tracker version from the dropdown list.
Note: Please avoid using non-ASCII characters in the project name or directory path as
this may cause runtime problems. The experiment project name must start with a letter
between ‘a’ and ‘z’ or ‘A’ and ‘Z’ and may contain letters, digits, and the underscore
character. If there is any space in the filename, this will be replaced by an underscore.
An “Invalid Value” or “invalid label format” error dialog box will be displayed if the
format of session label is invalid.

SR Research Experiment Builder User Manual

•
•
•
•
•
•

graph.ebd: This file contains the experiment graph. Double-click this file to open
the experiment project.
Preferences.properties: This file contains the preference settings for the current
experiment project.
datasets: This is the directory where the data source file is located.
library: This is the folder where the image, audio, interest area set, and video files
are stored.
runtime: This folder contains all of the runtime image and Data Viewer
integration files (image drawing list and interest area set files).
myfiles: This directory (and all files and subdirectories within it) will not be
deleted or cleaned by the build process, so this is where users may store any
additional files related to the project (randomized data sets, test EDF files, etc).
Files in this directory will be included in the packed project and copied to the
deployed folder.

Note: If you are running Experiment Builder from a non-Administrative account of
Windows XP, you should create the new projects to the user account directory (i.e., the
project location should be "{Windows Drive}:\Documents and Settings\{User
Account}\My Documents"). In Windows Vista, 7, 8, or 10, a new project should be
created at a directory with user read/write permission (e.g., at "C:\Users\{User Name}").
Similarly, you should deploy your experiments to the user account directory.
Note: The above files and folders are created and maintained by Experiment Builder.
Users should not attempt to modify these files and folders or store important files in
the experiment project folder except within the "myfiles" directory. Experiment
Builder will overwrite any manual changes made to the experiment project directory
(except "myfiles").

Figure 4-3. Warning Messages after Experiment Creation.

4.2 Saving a Project
An experiment project can be saved by choosing from the application menu bar:
File → Save

SR Research Experiment Builder User Manual

Tip: The experiment creation session can also be saved by clicking on the Save button
on the application tool bar, or by pressing the shortcut keys Ctrl+S on Windows or
Command ⌘+S on Mac OS X.
If there is any change to the experiment project, the previous experiment graph is saved
as “graph.ebd.bak” in the experiment directory.

4.3 Saving an Existing Project to a Different Directory
To save an experiment project with a different project name and/or in a different
directory,
1) From the application menu bar, choose:
File → Save As
2) In the Save As dialog box, click the “…” button to the right of “Project Location”
to browse to the directory where the project should be saved.
3) Enter the new project name in the Project Name edit box.
4) Click the OK button.
Tip: The project can also be saved by clicking the “Save As” button
application tool bar.

on the

4.4 Opening an Existing Project
To open an existing experiment project from the Experiment Builder application,
1) From the application menu bar, choose:
File → Open
2) In the “Open” dialog box, browse to the directory of experiment and select the
“graph.ebd” file (see Figure 4-4).

SR Research Experiment Builder User Manual

Figure 4-4. Open an Experiment Builder Project.
3) Click the “Open” button.
Note: If an experiment is already open in the current project, the “Open” operation will
first bring up a “Save Confirmation” dialog box so that users can either save the current
session (“YES”), abandon the current session (“NO”), or stay in the current session
(“CANCEL”; see Figure 4-5).

Figure 4-5. Save Confirmation When Opening a New Project.
Tip: A saved experiment project can also be opened by clicking the Open button
on
the application toolbar, or pressing the shortcut keys Ctrl+O on Windows or Command
⌘+O on Mac OS X.
Note: Users can also open an existing experiment project with Windows Explorer, or
Finder in Mac, by going to the directory where the experiment project is contained and
double clicking on the graph.ebd file.

SR Research Experiment Builder User Manual

Note: If you are opening a project created with version 1.x of Experiment Builder on a
Windows 8 or 10 computer, you will see the following warning message (see Figure 4-6).
This is the expected behavior as the OpenGL graphics provide better display timing on
the recent operating systems whereas on Windows 7 or earlier operating systems either
OpenGL or DirectDraw graphics will be fine.

Figure 4-6. Change in Video Environment When Opening a New Project.

4.5 Reopening a Recent Experiment Project
Experiment Builder keeps a history of five recently opened experiment projects. To
reopen a recent experiment project:
1) From the application menu bar, choose:
File → Reopen
2) Choose the project to open from the list of recent experiment projects. (see Figure
4-7).

Figure 4-7. Reopening Recent Experiment Projects.

SR Research Experiment Builder User Manual

A “File Not Found” error will be displayed if the intended experiment project has been
moved, renamed, or deleted. To clear the list of recent projects, click the “Clear History”
menu.

4.6 Lock/Unlock a Project
If you open a locked Experiment Builder project, you will notice that there is a “(ReadOnly)” string in the titlebar of the experiment project. With a locked project, the “Save”
button in the application toolbar is grayed out when you try to save modifications to the
experiment graph. The Add, Delete, and Rename buttons in the Library Manager are also
disabled. To unlock a locked project, click the “File → Unlock Project” option on the
application menu, or click the ( ) button on the application toolbar (see Figure 4-8). To
lock a project, click the “File → Lock Project” option on the application menu, or click
the ( ) button on the application toolbar.

Figure 4-8. Unlock a Locked Project.

4.7 Packaging an Experiment
Experiment packaging is very useful if you want to send another Experiment Builder user
an experiment you have created so they can modify the experiment in Experiment
Builder. Users can pack up the current experiment project by clicking
File → Package
from the application File menu.
SR Research Experiment Builder User Manual

This will zip up the experiment directory and save the zip file at a selected location. The
created .ebz file contains only the files necessary to rebuild and run the experiment
(graph.ebd, Preferences.properties, the library directory, and the myfiles directory if it
has any contents). The packed project can be unpacked by Experiment Builder.
Tip: The experiment can also be packaged up by clicking the “Package” button
on
the application tool bar or pressing F5 on Windows or Ctrl+Shift+P on Mac OS X.

4.8 Unpacking an Experiment
The packed experiment project can be unpacked by clicking "File → Unpack" from the
application File menu. In the following dialog, users should select the packed project
(source) and specify a directory to which the project should be unpacked (Destination;
see Figure 4-9). By default, the destination directory will be the folder where the .ebz file
is located.

Figure 4-9. Unpacking an Experiment Project.
Tip: A packed project can also be unpacked by pressing F3 on Windows or Ctrl+Shift+U
on Mac OS X.
Note: Users can also unpack a project by simply double-clicking on the .ebz file.

4.9 Building an Experiment
After creating the experiment, users need to compile the experiment to make sure there
are no errors in the experiment graph. To do that, from the application menu bar, choose
(see Figure 4-10):
Experiment → Build
Tip: Building an experiment can also be performed by clicking on the “Build” button
on the application tool bar or pressing F9 on Windows or Ctrl+Shift+B on Mac OS X.

SR Research Experiment Builder User Manual

Figure 4-10. Experiment Menu.

4.10 Cleaning an Experiment
Sometimes users may want to clean up the experiment projects. This is especially
important when users have changed the images or other screen resources used for the
experiment. To clean the project, from the application menu bar, choose:
Experiment → Clean
Tip: Cleaning an experiment can also be performed by clicking on the “Clean” button (
) on the application tool bar or by pressing shortcut key F7 on Windows or
Ctrl+Shift+C on Mac OS X.

4.11 Test-running an Experiment from EB Application
To check whether the experiment works, users may test run the experiment from the
Experiment Builder application. To perform a Test Run, from the application menu bar,
choose:
Experiment → Test Run
This will create a “Results” directory containing the data collected from the test run
session. Note that the test run is not intended for real data collection and should only be
used when you are testing your experiment. Each time you test run, the results folder is
created again, and existing results will be lost.
Tip: Test running an experiment can also be performed by clicking on the “Test Run”
button on the application tool bar or pressing the shortcut key F11 on Windows or
Ctrl+Shift+R on Mac OS X.
Note: If the experiment is tested under dummy mode, a warning dialog box "You are
running in dummy mode! Some eye tracking functionality will not be available" will be
displayed at the beginning of the experiment, and a warning dialog "No EDF file is
created for dummy mode session" will be displayed at the end.

4.12 Deploying an Experiment
To deploy a built experiment so that it can be run for data collection without relying on
the Experiment Builder application, choose from the application menu bar:

SR Research Experiment Builder User Manual

Experiment → Deploy
In the Deploy dialog box, click the “…” button to the right of “Project Location” to
browse to the directory where the deployed project should be saved. The project will be
saved into a new subdirectory named for the entered File Name. This experiment
subdirectory contains all of the required files generated. Please note that non-ASCII
characters are not allowed in a deployment path (e.g., deploying a project to a folder that
contains Chinese characters will fail). Users can cancel the deploy process by pressing
the “Cancel” button.
Tip: Deploying an experiment can also be performed by clicking on the “Deploy” button
on the application tool bar or pressing shortcut key F12 on Windows or Ctrl+Shift+D
on Mac OS X.
Tip: For the ease of reconstructing the original experiment project, a "source" folder will
also be created in the deployed project. Depending on the Build/Deploy preference
settings, this folder contains either the packed experiment project or only the graph.ebd
and Preferences.properties files.
Note: Users may deploy the experiment on one computer and then copy and execute the
project on a different computer. Please make sure the deploy computer and the test
computer have the same operating system installed and the test computer has the required
hardware (e.g., monitor, sound card, response device) for the proper execution of the
experiment. For example, an experiment deployed on a Windows XP computer will not
run on a display computer with Windows 7 installed, as the dependency files are different
between two operating systems. Similarly, experiment deployed on Mac OS X will not
run on the Windows computers and vice versa. Other runtime errors can occur if the two
computers have different settings in the Cedrus driver, I/O driver, video card driver,
audio device, etc.

4.13 Running an Experiment for Data Collection
To run the experiment for data collection from the deployed folder, simply double click
the executable file in the deployed directory, or from your computer desktop, click "Start
→ All Programs → Accessories → Command Prompt". Go to the deployed experiment
directory by typing "cd {experiment path}" on the command prompt and type the
{experiment}.exe file name to start the experiment. Running the experiment from the
command line prompt also allows users to pass additional parameters to the program.
Some of the useful command line options are:
• -session=
If the "-session" option is used, the software will not prompt for a session name
via a dialog box at the beginning of the experiment. The session name pass along
the "-session=" option must be within eight characters (consisting only of letters,
numbers, and the underscore character).
SR Research Experiment Builder User Manual

•

-ui=[GUI|CONSOLE|NONE]
The "-ui" option allows to disable the file transferring dialog box at the end of the
session. If -ui=GUI the graphical progress bar is popped up (default); if ui=CONSOLE, progress updates of the file transfer are printed to the console; if ui=NONE no progress messages are brought to the users. For example, for an
experiment named "simple_deployed", you can pass the "-ui=NONE" to disable
the files transfer progress bar.
simple_deployed -session=myTest -ui=NONE
The actual parameters passed along the command line can be retrieved through
the "Command Line Arguments" property of the Experiment node.

Running the deployed version of the experiment doesn't require a license key plugged to
the computer. If the experiment needs to be run on a different machine with similar or
better computer specifications, users should first copy the entire directory of the deployed
version of the experiment to that computer. To make the experiment transfer easier (given
the large number of files involved), users may first zip up the {Experiment Name} folder
(keeping the directory structure) and then unzip the file on the target computer.
Users should also pay attention to the following details:
• For accurate display drawing, the dots-per-inch (DPI) resolution of the display PC
that is used to run the experiment must match that of the development PC which
is used to create the experiments. To check the DPI settings, click the right mouse
button at a blank space on the Display PC desktop to open a dialog box for
display properties settings. Click the "Advanced display settings" link at the
bottom of the page, and then the “Advanced sizing of text and other items” link
on the following page. On Windows 10, users should use the default 100%
display scaling. Click “Start menu -> Settings -> System -> Display”. Set the
“Scale and Layout” to 100% (if you don’t see this option on your version of
Windows, search for other similar options like “Change the size of text, apps and
other items" in Display Settings).
•

If the deployed experiment shows video clips, please make sure that codec used
to test run the video experiment is also installed on the deployment computer as
well; otherwise, the deployed experiment will not run.

Important: Please check out section 3.1.2 on steps that should be taken to maximize the
real-time performance of the deployment computer.
Finally, when an experiment is in progress, please avoid hitting the Windows logo key on
the keyboard so that the experiment will not be aborted for failing to lock the experiment
graphics window. You may check out Section 7.10.6.4 for instructions to disable the
Windows Logo Keys.

SR Research Experiment Builder User Manual

4.14 Converting Projects Between Windows and Mac OS X
Experiment projects saved on the Windows operating systems can be opened with the
same version or a newer version of the software on Mac OS X, and vice versa. There are
some exceptions on the transferability between the two families of operating systems.
• Audio playback and recording is done through the OS X driver on Mac OS X.
When converting a project created on Windows with audio playing (either
through DirectX or ASIO driver) or recording (through the ASIO driver), the
audio device will be reset to OS X. Conversely, the audio device will be reset to
the ASIO driver when converting a Mac version of the experiment project with
audio recording or playing.
• The Mac OS X version of the software uses the OpenGL graphics library for
visual stimulus presentation. The Windows version uses either DirectDraw or
OpenGL, although the latter is preferred on Windows 8 and 10.
• The two versions of the software may exhibit different levels of compatibility
when playing video clips with .avi file extension. Specially, Experiment Builder
uses the ffmpeg video loader by default to play.avi files on Mac OS X, and uses
the vfw (video-for-windows) loader by default on Windows (though users can
choose to use the ffmpeg video loader).
• Sending TTL signals or receiving TTL signals on Mac OS X is only supported
through the USB-1208HS box. So the TTL device of an Experiment Builder
project created in Windows using the parallel port will be reset to USB-1208 HS
when opened in Mac OS X.
• Some of the fonts may be missing when converting from the other operating
system. Single-line texts or multi-line texts of the same font size will look smaller
(by a factor of about 1.33) on Mac OS X than on Windows due to different
default DPI values used across the two operating systems.

SR Research Experiment Builder User Manual

5 Experiment Builder Graphical User Interface
Experiment Builder uses a desktop framework that contains all the windows of the
application. The following figure shows a typical graphical user interface (GUI) users
will see in an experiment creation session. Below the menu and toolbar, the Experiment
Builder desktop is divided into two areas: the Project Explorer Window on the left and
the Graph Editor Window on the right. The Project Explorer Window lists all of the
experiment nodes in a hierarchical fashion and allows users to select the nodes for review
or modification. The Graph Editor Window allows users to create the experiment graph
by dragging individual building blocks and making connections between components to
form experiment flow.

Figure 5-1. Sample Experiment Builder Interface.

5.1 Project Explorer Window
The Project Explorer Window allows users to select experiment nodes to be viewed, to
modify the selected node’s properties, and to configure default devices (e.g., eye tracker,
display, audio driver, parallel port, and Cedrus Input settings). This window has four
individual panels: Overview, Structure, Property, and Connections panels. Each of the
individual sections can either be a docked ( ) panel of the Project Explorer Window or a
free-floating ( ) window. In addition, each of the panels can be hidden or made visible
from the "View" menu (see Figure 5-2).

SR Research Experiment Builder User Manual

Figure 5-2. The View Menu.
The Overview panel (on the top) shows the graph layout of all components in the current
level of experiment and highlights the currently selected node. The part of the graph
within the shaded box is currently visible in the workspace of the Graph Editor Window.
Users can choose to work on a different part of the graph by clicking on the shaded box
and dragging it over to the intended region.

SR Research Experiment Builder User Manual

Figure 5-3. Components of the Project Explorer Window.
The Structure panel (in the middle) lists the nodes used in the experiment. This panel has
three tabs: Experiment, Components, and Devices. The Experiment Tab (left panel,
Figure 5-4) contains a hierarchical representation of the Experiment -- all component
nodes are listed under the sequence in which they are contained. The Components Tab
(middle panel, Figure 5-4) lists the nodes by type (triggers, actions, or other components).
Similar to the interface used by Windows Explorer, if certain types of components are
used, the folder containing those components can be opened ( ) or closed ( ). The
Devices Tab (right panel, Figure 5-4) allows users to configure default settings for the
EyeLink tracker, experiment display and other devices (see section 17 on Preferences
settings).

SR Research Experiment Builder User Manual

Figure 5-4. Different Tabs of the Structure Panel.
The Properties panel (at the bottom) displays properties of the selected item in the
Structure panel. Users can review the current property values and make modifications if
necessary. If a property field is grayed out (e.g., the "Time" property of the
DISPLAY_SCREEN action), the value of the property cannot be directly modified, but
may be referred to. All the other properties may be modified directly (see section 7.5
"Editing Properties of a Node").
The Note section of a properties panel allows users to add comments to the node.
The Connections panel lists all of the nodes that are connected to the current node. The
"Connected From" section lists all of the nodes that target the current node, and the
"Connects To" section lists all of the nodes that receive a connection from the current
node.

SR Research Experiment Builder User Manual

5.2 Graph Editor Window
The Graph Editor Window provides an interface through which the experiment can be
created graphically. This window is divided into four sections: the Component Toolbox,
Work Space, Editor Selection Tabs, and Navigator (see Figure 5-5).
The Component Toolbox contains the basic building blocks of the experiment graph and
allows users to select a desired component to be added into the experiment. The
experiment components are grouped under three categories: Trigger (including timer,
invisible boundary, conditional, EyeLink button, Cedrus Input, TTL, keyboard, mouse,
voice key, fixation, saccade, and sample velocity triggers), Action (display screen,
perform camera setup, perform drift correction, send EyeLink message, log experiment
data, send EyeLink command, update variable attribute, prepare sequence, add to results
file, add to accumulator, send TTL signal, play/record sound, control sound
playing/recording, terminate experiment, recycle data line, reset node, as well as a NULL
action), and Other (variable, results file, accumulator, and custom class).
The Work Space provides the graphical environment in which the experiment is
generated. In an empty sequence, the Work Space area contains a START node to which
actions and triggers can be connected. Users can drag selected experiment elements from
the Component Toolbox and drop them into the work space, then make connections to
and from other components. Users can select individual items in the Work Space to edit
their properties.
The Editor Selection Tabs and Navigator provide convenient shortcuts for selecting a
display screen or an experiment sequence to work on. When an experiment involves
several different layers of sequences (for example Blocks → Trials → Trial Recording),
the Navigator at the bottom of the graph editor window indicates the current layer the
user is working on. Users can switch to work on a higher-level layer by clicking one of
buttons in the Navigator corresponding to the higher-level sequences. All sequences and
display screens opened in the experiment, as well as the project output screen, are listed
as individual Editor Selection Tabs above the Component Toolbox for direct access. To
dismiss Editor Selection Tabs, right-click a tab, then select either “Close” to close just
that tab, or “Close Others” to close all except the clicked tab and the top-level
“Experiment” tab.

SR Research Experiment Builder User Manual

Figure 5-5. Components of the Graph Editor Window.

5.3 Application Menu Bar and Toolbar
The Experiment Builder application menu bar and toolbar contain a list of common
operations. Most of the operations can also be performed by keyboard shortcuts or by
using buttons on the application toolbar.

5.3.1 File Menu and Tool Buttons
Commands that affect creating, opening, saving, packaging, or closing the Experiment
Builder sessions are located here (see Chapter 4 for details). 1
Operation

Shortcut
(Mac OS X)
⌘+N

Function

New

Shortcut
(Windows)
Ctrl + N

Open

Ctrl + O

⌘+O

Opens an existing experiment project.
Reopens a recent Experiment Builder project.

Reopen
Save
Save

Creates a new experiment project.

Ctrl + S

⌘+S

Saves the current experiment project.
Saves the experiment project to a different directory.

SR Research Experiment Builder User Manual

Click the closed icon to lock a currently unlocked
project, or the open icon to unlock a currently locked
project.

Lock
Unlock
Project
F5
Package
Unpack

Ctrl + Shift
+P
Ctrl + Shift
+U

Set Restore
Point
Restore
⌘ Q
(under
"Experiment
Builder"
menu)

Exit

Used to compress the experiment project into an .ebz
file for file sharing, etc.
Used to extract the experiment project from a
compressed .ebz file.
Sets a restore point for the project so that users can
revert the project’s state to that point in time.
Reverts the project's state to that of a previous point
in time.
Closes the Experiment Builder application.

5.3.2 Edit Menu and Tool Buttons
The Edit menu contains commands such as copy, paste, cut, delete, and undo. It also
contains tools for resource library management, node group organization, and preference
settings (see Chapter 17).
Operation

Shortcut
(Mac OS X)
⌘+Z

Function

Undo

Shortcut
(Windows)
Ctrl + Z

Redo

Ctrl + Y

⌘+Y

Redoes or repeats an action.

Cut

Ctrl + X

⌘+X

Copy

Ctrl + C

⌘+C

Removes a selection from the project and places it
into the clipboard.
Puts a copy of a selection to the clipboard.

Paste

Ctrl + V

⌘+V

Paste
Multiple

Ctrl + M

⌘+M

Delete

⌘ + Delete

Delete
Refresh
Custom
Class

Ctrl + H

Removes the selection from the current location.
Refreshes the Custom Class files (i. e., reparses the
contents of the files). This tool is useful to users
who use an external editor to edit the content of
custom classes.
Shows a list of preference settings for Experiment
Builder.
Used to load in image, audio, interest area set, video,
custom class, or movement pattern files.

⌘+,

Ctrl + L

⌘+L

Ctrl + R

⌘+R

Tabulates the source, property, and value of each
reference used in the experiment graph (see section
10.5).

Ctrl + G

⌘+G

Allows users to rearrange the layout of the
components in the component toolbox.

Reference
Manager
Node
Groups

Inserts the previously copied item from the
clipboard to the current position.
Inserts several copies of the previously copied item
from the clipboard to the current position.

F4
Preferences
Library
Manager

Undoes the last action performed.

SR Research Experiment Builder User Manual

Select All

Ctrl+ A

⌘+A

Selects the entire contents of the active window.

5.3.3 View Menu
The View menu contains commands that display or hide panels in the Project Explorer
Window, or change the layout of the experiment graph.
Operation
Overview
Structure
Properties
Connections
Navigator
Restore Default Views
Back
Forward
Zoom Selected
Zoom In
Zoom Out
Fit Content
Layout Options
Arrange Layout
Export Node
Import Node

Function
Display the Overview panel.
Display the Structure panel.
Display the ‘Attributes’ and/or ‘Note’ sections of the Properties
Panel.
Display the ‘Connects To’ and/or ‘Connected From’ sections of the
Connections Panel.
Display the “Navigator" panel in the Graph Editor Window.
Restore the default layout of the windows and panels.
Go back to the previously selected/viewed node.
Move forward to a previously selected/viewed node.
When one or more components in the graph are selected, zoom in
on the selected items.
Zoom in towards the center of the work space.
Zoom out so that more items can be displayed in the work space.
Zoom in or out so all the components in the work space are
displayed.
Configure the layout of components when “Arrange Layout” is
applied.
Rearrange the graph components in an orderly manner.
Export the selected node(s) to an .ebo file so they can be shared.
Import nodes from an .ebo file into the current experiment project.

5.3.4 Experiment Menu and Tool Buttons
The Experiment Menu contains commands that are used to compile and run the
experiment, clean up the experiment project, and to create a deployed version of the
experiment (see Chapter 4 for details).
Operation
Clean

Shortcut
(Windows)
F7

Build

Test
Run
Deploy

F11
F12

Shortcut
(Mac OS X)
Ctrl + Shift +
C
Ctrl + Shift +
B
Ctrl + Shift +
R

Function

Ctrl + Shift +
D

Used to generate deploy code so that the experiment
can be executed as a standalone program.

Used to clean up the experiment project.
Used to compile the experiment.
Used to test run the experiment from the Experiment
Builder application.

5.3.5 Help Menu
The Help menu contains the Experiment Builder Help document as well as licensing and
product release information (see Chapter 3 for details).
Operation

Shortcut
(Windows)

Shortcut
(Mac OS X)

Function

SR Research Experiment Builder User Manual

F1
Contents
About
License

Displays the online help (htlm version of this
document) of the Experiment Builder application.
Displays the release information for this copy of the
software.
Displays license information for this copy of
Experiment Builder

SR Research Experiment Builder User Manual

6 Designing an Experiment in Experiment Builder
This chapter introduces the general concepts of experiment design in Experiment Builder:
hierarchical organization of events in an experiment, flow diagram, and attribute
referencing. It also provides an overview of Experiment Builder components (triggers,
actions, sequences, and other nodes) and linking rules for the experiment graph.

6.1 Hierarchical Organization of Experiments
One of the important concepts in SR Research Experiment Builder is the hierarchical
organization of events in an experiment. A typical experiment can be dissected into
several levels along a hierarchy of Experiment → Blocks → Trials → Trial Runtime /
Recording. All of the events within each level of this hierarchy can be conveniently
wrapped in a loop (called a Sequence in Experiment Builder). This allows the whole
sequence to be connected to other objects as a unit and be repeated several times in a row.
The following figure illustrates a common high-level EyeLink experiment architecture.
To create an experiment, users need to create several nested sequences, add a list of
actions and triggers to each sequence, and make necessary connections between
components to form the experiment flow. In this example, the top-most level of the
experiment (Experiment Sequence) contains a greeting message or instruction screen
followed by a sequence representing blocks of trials (Block Sequence), and then a
goodbye or debriefing message at the end of the experiment. Within each repetition of the
Block Sequence, users first perform camera adjustments, calibration and validation, and
then run several trials (Trial Sequence). Every iteration of the Trial Sequence starts with
pre-recording preparations (e.g., preloading image, audio, video resources, clearing
trigger data, sending some simple drawing graphics to the tracker screen, flushing log
file) and drift correction followed by the trial recording (Recording Sequence), and
finally displaying feedback information if necessary. The Recording Sequence is
responsible for collecting the eye data and is where visual and auditory stimuli are
presented. Response collection from the participant is also performed in the Recording
Sequence.

SR Research Experiment Builder User Manual

Figure 6-1. Hierarchical Organization of Events in an Experiment.

6.2 Experiment Graph: Flow Diagram
Experiment Builder uses an intuitive flow diagram interface for experiment creation - the
whole experiment generated can be called a graph. Users can drag and drop experiment
components into the work space of the Graph Editor Window. These experiment
components include triggers and actions that represent individual events and
preconditions in the experiment. An Action tells the computer to do something (e.g.,
display a screen or play an audio clip), whereas a Trigger represents some preconditions
that must be met for the experiment to continue past that point. Experiment components
are connected to each other using arrowed lines that represent sequence and dependency
relationships (i.e., X must be done before Y can be done). The connection of experiment
components forms the flow of the experiment. The following figure illustrates a very
simple experiment sequence with gaze-contingent manipulation.

SR Research Experiment Builder User Manual

Figure 6-2. Sample Experiment Sequence.
In this example, the experiment sequence starts with a DISPLAY_FIRST_SCREEN
action, which draws graphics to the computer display. Now the sequence constantly
monitors two Triggers until one of the Triggers is satisfied: an
INVISIBLE_BOUNDARY trigger and a TIME_OUT. The INVISIBLE_BOUNDARY is
triggered if the participant’s gaze falls within a pre-specified region of the screen whereas
the TIME_OUT is triggered if a specified amount of time (e.g., 30000 milliseconds) has
passed since DISPLAY_FIRST_SCREEN was drawn.
If TIME_OUT is triggered, the sequence ends since the TIME_OUT Trigger does not
connect to any subsequent experiment components. However if
INVISIBLE_BOUNDARY is triggered, DISPLAY_SECOND_SCREEN action is
performed and new graphics are drawn to the computer screen.
Now the sequence monitors two new Triggers: a TIME_OUT_2 trigger and an
EL_BUTTON trigger. The EL_BUTTON trigger fires if the participant presses a button
on the EyeLink button box. TIME_OUT_2 is triggered if a pre-specified duration has
elapsed since the second display was drawn. The sequence ends when either of the
triggers (EL_BUTTON and TIME_OUT_2) becomes true.
Important: Note that in the above example, once the DISPLAY_SECOND_SCREEN
Action has been performed the TIME_OUT and INVISIBLE_BOUNDARY Triggers are
no longer monitored; only the Triggers connected to the last processed Action are
monitored.

6.2.1 Adding Components to an Experiment
To add individual components to the workspace of the Graph Editor, first choose the
corresponding node group of the Components Toolbox by clicking on the Trigger, Action,
SR Research Experiment Builder User Manual

or Other tab. Left-click on the icon of the desired component and drag the selected item
to the desired location in the work space, then release the mouse button. For a description
of any component, simply hover the mouse cursor over the icon

6.2.2 Linking Experiment Components
The flow of an experiment sequence moves from the default "START" node to one or
several triggers or actions and then to other triggers or actions, and so on. This requires
users to connect two nodes with arrowed line to establish a directional or dependency
relationship between a "Source" node and a "Target" node.

Figure 6-3. Connecting Between Source and Target Components.
To make a connection from a Source node to a Target node, left-click on the Source node
and drag the mouse to the Target node, then release the mouse button. To cancel a
connecting operation in progress, press the "ESC" key. To remove a connection between
two experiment nodes, click the connecting line until it is highlighted in yellow, and then
press the "Delete" key on a Windows keyboard (Command ⌘ + Delete together on Mac
OS X) or select the
button on the application tool bar.

6.2.3 Linking Rules
The connection between a Source node and a Target node is governed by a set of rules:
1) A node cannot be connected to itself.
2) You cannot connect from the source node to the target node more than once.
3) The START node cannot be a Target (i.e., it cannot receive a connection from
other nodes in a graph). The START node can target to an action, trigger, or
sequence.
4) A Source node cannot have more than one Target Action; unless it is a
Conditional Trigger in which case each conditional branch cannot Target more
than one Action node.
5) A Source node can target many Trigger nodes.
6) A Source node cannot target a Trigger node and an Action node at the same time.
7) A Sequence node cannot target a Trigger node.

SR Research Experiment Builder User Manual

8) A Target trigger node cannot receive connections from multiple source trigger
nodes.
9) A Source node cannot target multiple Sequence nodes. That is, the current version
of Experiment Builder does not support parallel processing.
10) A Drift Correct Action or Camera Setup Action cannot target any Trigger.
11) Storage space elements (Accumulator, Variable, and Results File) cannot be
Source or Target Nodes (i.e., never directly connected to other nodes).
12) Certain node types, such as Fixation, Saccade, Invisible Boundary, and Sample
Velocity Triggers, can only be added to a sequence that has the "Record"
checkbox ticked.
13) Drift Correct and Camera Setup Actions cannot be added to a sequence that has
the "Record" checkbox enabled.
14) A Trigger cannot be the target of an action and a trigger at the same time.

6.3 Actions
Action nodes instruct the computer to do something, for example, to display a screen or
play a sound. One or multiple actions can be added to a sequence, depending on the
complexity of the experiment. For example, a recording sequence showing a static page
of text may just require a single display screen action whereas an experiment studying
change detection necessitates several display screen actions to present alternating screens
at a fixed interval. SR Research Experiment Builder supports a set of actions listed in the
following table.
Display Screen
Camera Setup
Drift Correction

EyeLink Command
EyeLink Message
Add to Log File
Prepare Sequence

Used to show a set of 2D graphics on the computer screen. Please
follow Chapter 8 “Screen Builder” to modify the content of the
screen.
Displays the EyeLink camera setup screen for the experimenter to
perform camera setup, calibration, and validation.
Performs an EyeLink drift correction by using a fixation point at a
known position to correct for small drifts in the calculation of
gaze position that can build up over time. This is particularly
useful when using the pupil-only mode of EyeLink. On the recent
versions of eye trackers (e.g., EyeLink 1000, 1000 Plus, Portable
Duo), a drift check will be performed instead, in which no
correction is applied to the gaze data.
Sends a text command to the EyeLink tracker through the
Ethernet link for on-line tracker configuration and control.
Writes a text message to the EyeLink eye tracker. The text is
millisecond time stamped and is inserted into the EyeLink EDF
file.
Allows users to add text to a log file for experiment debugging.

Add to Accumulator

Performs preparatory operations for a sequence (e.g., preloading
image or audio files, drawing feedback graphics on the Host PC,
and re-initializing trigger settings) to ensure real-time
performance and better recording feedback.
Adds a number to an Accumulator object.

Add to Results File

Used to output data to a tab-delimited Results File.

SR Research Experiment Builder User Manual

Update Attribute
Send TTL Signal

Updates the value of a Variable or an attribute of an experiment
component.
Sends a TTL signal via the parallel port or other data ports.

Reset Node

Allows users to pick a node in the experiment and reset its data.

Terminate
Experiment
Recycle Data Line

Used to terminate the experiment project programmatically.

Play Sound

Instructs the experiment sequencer to run the current data source
line again at a later time.
Plays a .WAV audio file.

Play Sound Control

Stops, pauses, or unpauses a specified Play Sound action

Record Sound

Records audio to a .WAV file. Only supported with an ASIOcompatible sound card in Windows or in Mac OS X.
Stop, pause, unpause, or abort the current sound being recorded.
Only supported with an ASIO-compatible sound card in Windows
or in Mac OS X.
Executes a method defined in a Custom Class Resource.

Record Sound
Control
Execute
Null Action
ResponsePixx LED
Control

A dummy action used primarily for the purpose of controlling
experiment flow and cleaning cached trigger data.
An action used to turn on/off the LEDs on the ResponsePixx
Button box.

6.4 Triggers
A Trigger is some condition that must be met for the experiment flow to continue past
that point. Triggers are used by Experiment Builder to control the transition from one
Action to another, or to end a sequence itself. For example, in a simple reaction-time
experiment, following the onset of the stimulus display a speeded response from the
keyboard or a button box can be used as a trigger to end the trial. In a change-detection
experiment, the time delay serves as a trigger to make the transition from one display
screen to another (and therefore controls the exposure duration of a display screen). In a
gaze-control experiment, a trigger for display change can be elicited when the eye enters
or leaves a pre-specified invisible boundary. Experiment Builder supports the following
set of triggers:
Timer
Keyboard
Mouse
TTL
Cedrus Button
EyeLink Button

Fires when a specified amount of time elapses. Timers can be used
to add a delay between actions and/or triggers, and to control the
maximum amount of time a node can last.
Fires when a specified key is pressed.
Fires when a mouse button is pressed and / or when the mouse
cursor falls within a specified region of the screen.
Checks TTL input to the input ports (e.g., parallel port or USB
1208HS box) of the display computer and fires when a specified
TTL signal is received.
Fires when a specified button on the Cedrus response pad is
pressed.
Fires when a specified button on the EyeLink button box is
pressed.

SR Research Experiment Builder User Manual

Boundary

Fixation
Saccade
Sample Velocity

Conditional

Voice Key Trigger

Fires when gaze position falls inside or outside of a pre-specified
invisible boundary, either after a single sample or a minimum
duration. Boundary triggers can be used to implement display
changes based on eye positions.
Fires when a fixation falls inside or outside of a specified region of
the display for a certain amount of time.
Fires when a saccade to a specified region of the display is
detected.
Implements a fast saccade detection algorithm by checking the
velocity and acceleration information on a sample-by-sample
basis. The Sample Velocity Trigger fires when the sample velocity
and acceleration values exceed or fall below their respective
thresholds.
Fires when one or two conditional evaluations are met. The
Conditional trigger may connect to two different target nodes,
depending on whether the condition evaluates to True or False.
This is useful to implement conditional branching in a graph when
several conditions are possible.
Triggers when ASIO input exceeds a pre-specified threshold. Only
supported with an ASIO-compatible sound card or in Mac OS X.

6.5 Other Node Types
Experiment Builder also supports other components: Variable, Results File, and
Accumulator. These components mainly function as a storage of experiment data. Note
that these objects are never connected to other components in an experiment in the Graph
Editor Window. Instead, they are used and updated within the experiment by attribute
referencing (see section 6.7).
Accumulator
Results File

Used to keep numeric values and do statistical analysis on the
accumulated data. The Accumulator is a circular list, so items
added to the list last are kept in case of an overflow.
Provides a columnar output of selected variables.

Variable

Used to store data during run time.

Custom Class
Instance

Used to create a new instance of a custom class

6.6 Sequence
As the experiment loop controller, a Sequence is used to chain together different actions
and triggers and execute them as a group. Therefore, Sequence itself can be considered as
a complex action. To implement the hierarchical organization of events in an experiment,
Experiment Builder allows one graph containing the triggers and actions to be nested
within another graph. In a typical experiment, users need to add a few nested sequences
so that the implementation of blocking, trial, and recording can be done efficiently (see
Figure 6-4 for an example).
Given the repetitive nature of the sequence component, a data source can be attached to a
sequence node to supply different parameters for each sequence iteration. The data source
SR Research Experiment Builder User Manual

is similar to a spreadsheet . Each column of a data source contains a variable label and
each row contains values for the variables. For a typical experiment created in
Experiment Builder, users will create prototypical trials and to supply the actual
parameters for individual trials in a data source attached to the trial sequence. During
experiment runtime, individual lines can be read from the data source, providing the
actual parameters for each trial, by setting relevant node attributes as references to data
source columns (see section 10 “References”).
Sequence

A controller for experiment flow. Used to chain together different
Actions and Triggers and execute them in a group or to simply
modularize a set of experiment components.

Figure 6-4. Nested Sequences in an Experiment.

6.7 References and Equations
Experiment Builder uses "references" to link or bind an attribute of one experiment
component to the attribute of another component. References (see Chapter 10) are a
critical part of Experiment Builder, providing much of the flexibility to the application.
For example, assume a sequence has two nodes, X and Y, and node X has attribute AX
and node Y has attribute AY. If attribute AX is set to reference AY, then the value of AX
will always be equal to the value of AY. In this example it is said that AX is the
"referencing" attribute and AY is the "referenced" attribute. Even if AY changes value
during the experiment, AX will always reflect the current value of AY.

SR Research Experiment Builder User Manual

A reference is represented by a string that starts and ends with an @ symbol in the
attribute editor for an experiment node. For example @X.AX@ is a reference to the AX
attribute of node X. @Y.AY@ is a reference to the AY attribute of node Y. If the
reference is to a node attribute that is not in the same sequence as the referencing node,
the reference will also contain the graph path to the referenced node.
Users can refer a variable or an attribute of one node to an attribute of another node
(trigger, action, or sequence), a variable, or a data source column. Users can also create
more complex equations, which may include a combination of values and/or references.
In most cases the data type of the referring attribute must match that of the referenced
attribute.
As a more concrete example of using references, imagine that a user needs to show some
text on the screen. In the Properties table of the text resource, the user can enter the text
to be displayed directly into the "Text" property field (see left panel of Figure 6-5). This
will result in the same text being presented in each iteration of the sequence. This static
approach is fine for things like presenting a fixation cross, but will be problematic when
the user needs to display different text across trials. An alternative, more flexible
approach, is to have the "Text" attribute refer to a column of a data source. Then on each
iteration of the sequence, the resource will use different text values as defined in the data
source.
In addition to setting values dynamically, references can be used to access the value of
attributes of an action or a trigger. In the above example, the width and height of the text
shown on the screen will change dynamically across trials. To know the exact text
dimension in one trial, the user can refer to the "Width" and "Height" properties of the
text resource.

SR Research Experiment Builder User Manual

Figure 6-5. Using a Reference to Update Text to Be Displayed.

SR Research Experiment Builder User Manual

7 Experiment Graph and Components
The Component Toolbox in the Graph Editor Window contains the basic building blocks
for building experiments. To create an experiment, users need to add necessary
components into different sequences of the experiment and make connections between
those components. Following this, the properties of the individual components should be
reviewed and modified as necessary. The current chapter reviews the use and properties
of the individual components in the toolbox.

7.1 Graph Editing Operations
Experiment Builder is an interactive tool, allowing users to create a new experiment
graph from scratch and to modify an existing graph. With the Graph Editor Window,
users are able to add/remove Experiment Builder component nodes, add/remove the
connection between nodes, modify the attributes of nodes, and so on.
The following lists common operations used in editing a graph in Experiment Builder.
Most of the operations can be performed by keyboard shortcuts, by using buttons on the
application toolbar, or by options in the "Edit" menu.
•

Insert a new node: Find the component to add in the Action, Trigger, or Other tab of
the Component Toolbox. Left-click on the icon of the desired component, then drag it
to the desired location in the work space, and release the mouse button.

•

Cut: To remove a selection from the project and place it into the clipboard, first
select the nodes to be cut, then press the Ctrl + X keys together (Command ⌘ + X in
Mac OS X). Alternatively, select the nodes, then right-click and select "Cut" from the
popup menu.

•

Copy: To copy a selection to the clipboard, select the nodes to be copied, then press
the Ctrl + C keys together (Command ⌘ + C in Mac OS X). "Copy" from the popup
menu.

•

Paste: To paste the previously copied or cut items from the clipboard to the current
location, press the Ctrl + V keys together (Command ⌘ + V in Mac OS X).
Alternatively, right-click in the graph area, and select "Paste" from the popup menu.

•

Paste a selection Multiple times: To paste the contents of the clipboard multiple
times, press Ctrl + M (Command ⌘ + M in Mac OS X). Alternatively, right-click in
the graph area, and select "Paste" from the popup menu. Enter the number of copies
to paste and click “OK”

•

Delete: Select the nodes to be removed and press the "Delete" key (Command ⌘ +
Delete in Mac OS X). Alternatively, select the nodes, then right-click and select
"Delete" from the popup menu.

SR Research Experiment Builder User Manual

•

Undo: To undo the last action performed, press Ctrl + Z (Command ⌘ + Z in Mac
OS X).

7.2 Node Connection
The flow of an experiment sequence moves from the default "START" node to one or
several triggers or actions and then to other triggers or actions, and so on. This requires
users to connect two experiment nodes with an arrowed line to establish a directional or
dependency relationship between a "Source" node and a "Destination" node.

7.2.1 Connection: Create, Cancel, and Delete
To connect a Source node to a Destination node, left-click on the Source node, then drag
the arrow to the Destination node and release the mouse button. (Note that if the Source
node is selected, clicking and dragging from the Source node will move the node rather
than drawing a connection. To de-select a node, simply click an empty space in the graph
area.) To cancel a connecting operation in progress, press the "ESC" key. To remove a
connection between two nodes, click the connecting line so it is highlighted in yellow,
and press the "Delete" key (Command ⌘ + Delete in Mac OS X), or click the “Delete”
button in the application toolbar.

7.2.2 Connection Order

Figure 7-1. Connection Order.
When several triggers are connected to a common source node, a small number is drawn
by each edge in the graph (see Figure 7-1). This number represents the order that triggers
will be evaluated. In the above example (Left Panel), the keyboard trigger will be
evaluated first, then followed by the EyeLink button trigger, and then by the timer trigger.
To change the connection order, delete the connection arrows between the source and
target nodes, and then reconnect the nodes in the desired order. For example, if a user

SR Research Experiment Builder User Manual

deletes the connection between DISPLAY_SCREEN and KEYBOARD, the remaining
connections increase in priority, so the EyeLink button trigger is evaluated first, and then
the Timer trigger. If the user re-connects the keyboard trigger to the display screen, the
keyboard trigger is now the third to be evaluated (see Right Panel).

7.2.3 Node Exporting and Importing
Experiment Builder allows users to share data between several experiment creation
sessions by importing and exporting nodes. Users can select nodes in the graph and
export to a .ebo file. The user can later import the .ebo file into another session. The
following explains in detail how to share data between Experiment Builder sessions by
exporting and importing.

7.2.3.1 Exporting
1) Select the node or sequence to be exported. Please make sure that only one node or
sequence is selected. (To export multiple nodes, place all the nodes into a single
sequence, then export this sequence.)
2) Click the right mouse button to bring up a popup menu, and select "Export Node"
(see Figure 7-2). If the "Export Node" option is grayed out, please make sure that
only one node or sequence is selected. Alternatively, click the Export button ( ) on
the application toolbar.

SR Research Experiment Builder User Manual

Figure 7-2. Exporting Node.
3) In the following "Export" dialog box, select the directory where the node should be
exported, enter the export file name, and then click the "OK" button.
• If the node to be exported contains references to other nodes or data source
columns that are not part of the selection, a "Reference Maintenance" dialog (see
the figure below) will be displayed to enumerate all of the references that will be
removed. Click the "Save" button to save the information to a text file if desired,
then click the "OK" button to continue.

Figure 7-3. Reference Maintenance.
• A dialog box will ask whether to export all necessary library files—any image,
sound, video files, etc., used in the selected node or sequence. Click "Yes" to
include all necessary library files in the exported file. Click "No" to export only the
node or sequence itself, excluding any library files. Click "Cancel" to abort the
export process.

Figure 7-4. Export Library Files.

7.2.3.2 Importing
1) Go to the intended sequence level and click anywhere in the blank area of the
workspace to make sure that no node or sequence is selected.
2) Click the right mouse button and select "Import Node" (see Figure 7-5). If the
"Import Node" option is grayed out, please make sure no node is currently selected.
Alternatively, click the Import button ( ) on the application toolbar.

SR Research Experiment Builder User Manual

3) In the following "Open" dialog box, go to the directory where the exported node file
is located, select the ".ebo" file, and click "Open".

Figure 7-5. Importing Node.

7.3 Layout of Nodes in Work Space
The Work Space in the Graph Editor Window functions like a flow diagram editor which
components are dragged onto and connected. If a large number of items are added, the
work space may get cluttered. The Experiment Builder graphic user interface allows for
automatic node arrangement and zoom-in or zoom-out operations to create high-quality
drawings of a graph for ease of reading.
To rearrange the layout of items in an orderly manner, place the mouse cursor in a blank
area of the Work Space, click the right mouse button to bring up a popup menu, and
choose “Arrange Layout” (see Figure 7-6). From the menu, users can also zoom in or out
the current graph, or to make the current graph fit the screen. The following table lists of
the options available from the popup menu.
Operation
Zoom
Selected

Function
When one or more components in the graph are selected, zoom in on the
selected items.

Zoom In

Zoom in towards the center of the work space.

Zoom Out

Zoom out so that more items can be displayed in the work space.

Fit Content

Zoom in or out so all the components in the work space are displayed.

Layout
Option

Configure the layout of components when “Arrange Layout” is applied.

SR Research Experiment Builder User Manual

Arrange
Layout

Rearrange the graph components in an orderly manner.

Note: To perform “Zoom Selected”, first select the nodes to zoom to, then right-click in
the work space to bring up the menu.To perform the other operations listed in the table,
first click a blank area in the work space to ensure no nodes are selected, then click rightclick in the work space to bring up the menu and select the operation to perform.

Figure 7-6. Choosing Layout of Components in Work Space.

7.4 Editing Properties of a Node
After a component is added into the workspace, some of its default property values can
be modified according to the requirements of the experiment. For example, the
maximum “duration” of a TIMER trigger is set to 4000 milliseconds by default. This
may not be a desired value in an actual experiment and therefore users may need to set a
different value for that field. To edit the properties of a node, first click the node so it is
highlighted by a green border.
When one experiment node is selected, its properties and corresponding values are
displayed in the property panel for review and modification. Depending on the property,
it can be edited in one of the following ways:
• If a properties field (e.g., “Time” and “Start Time” of various actions) is grayed
out then the value of the property is “read-only” and cannot be directly modified.
• If the value field of a property contains a check box (e.g., “Record” property of a
sequence), that property can be either enabled or disabled by clicking the check
box.

SR Research Experiment Builder User Manual

•
•

•

If a dropdown list appears after doubling clicking the property value field (e.g.,
“Duration Type” property of the Timer trigger), make the selection from the list.
For some properties (e.g., “Label” of an action), the value can be modified by
double clicking on the value field, entering the desired value, and then pressing
the ENTER key to register the change.
If a button box appears at the right side of the attribute cell after selecting the field
(see Figure 7-7), the property field may also be edited with Attribute Reference
Editor (see Chapter 10).

Figure 7-7. Property Field Editable with Attribute Reference Editor.
In the following sections of this chapter, a set of symbols are used to indicate the
properties of each attribute of an experiment component:
#
*

Attribute is read-only and is not directly modifiable
Attribute can not reference another attribute (Attribute Reference Editor is not available
for the property)
The attribute cannot be referenced by other component attributes.
Attribute value can be selected from a dropdown list
Attribute is a Boolean value. True if the box is checked; false if unchecked.

NR
¶
†

All other attributes can be modified either by entering the value directly in the edit field
or by setting a reference in an attribute editor dialog box. Those fields can also be
accessed for attribute references.

7.5 Experiment Node
Clicking on the topmost node ( ) of the structure list in the Project Explorer Window
displays the properties of the experiment project in the property panel.
Field

Type

Content

Label *
Type #

Attribute
Reference
.label
NR

String

EyeLink DV

.dataViewerVar

List of

Label of the Experiment
The type of Experiment Builder object
(“Experiment”) the current node belongs to.
Clicking on the value field of this property will

SR Research Experiment Builder User Manual

Variables

iables

Strings

Time Out

.timeout

Integer

Created Date #

.createdDate

String

Last Modified
Date #
Session Name #

.lastModifiedD
ate
.sessionName

String

Test Run
Command Line
Arguments

.cmdargs

List of
String

License ID #

Save Messages †

.saveMessages

Boolea
n

Read-Only †

Boolea
n

String

bring up a dialog box allowing users to select
variables and data source columns to be
recorded in the EDF file as trial condition data
in Data Viewer. This attribute is only available
in an EyeLink experiment (i.e., the “EyeLink
Experiment” setting of the Experiment
Preference is enabled).
The maximum time (in milliseconds) the
experiment should run. If 0, the experiment will
not time out.
Time and Date when the experiment was first
created.
Time and Date when the experiment was last
modified.
Name of the experiment session. This is the
string input in the "Session Name" dialog box
when running the experiment.
Extra parameters that can be passed to the
experiment program. When running the
deployed experiment from the command line
prompt, users may enter an extra string
following the {experiment}.exe command.
Extra parameters can be added to Test Runs
under Preferences → Build/Deploy.
ID of the license key. “Demo” if the
Experiment Builder software is unlicensed.
Whether the messages associated with any
triggers or action should be logged in a text file.
This attribute is available in Non-EyeLink
Experiments only. If enabled, the “Message”
property will be available in most of the triggers
and actions.
Check this box to prevent any changes to the
experiment project from being saved.

SR Research Experiment Builder User Manual

Figure 7-8. Properties of the Experiment Node.
The "EyeLink DV Variables" property is used to send trial condition messages to the
EDF file so that users know exactly under which conditions each trial recording was
performed. The list of possible variables includes columns in the experiment data source
(see Chapter 9 "Data Source") as well as new variables created by the user (see Section
7.11.1 "Variable"). Version 2.0 of Experiment Builder now automatically adds the
variables and data source columns to the EyeLink DV Variables field. To remove some
variables from the list, or to change the order of the variables, click on the value field of
the property. A dialog box will allow the user to choose the variables to be recorded and
to reorder them in the list.
To have the experiment to time out after a certain duration, enter the time out value in
milliseconds into the "Time Out" field.

7.6 Sequence
A sequence (
) object encapsulates different actions and triggers, allowing users to
perform editing operations (cut, copy, delete, paste) on all of the items contained within
the sequence together. It also allows users to execute them in a loop and repeat the
execution several times if required. In a typical experiment, users need to add a couple of
nested sequences so that a blocking-trial-recording hierarchy can be implemented
SR Research Experiment Builder User Manual

efficiently. In an EyeLink experiment, the "Record" attribute should be ticked for one of
the sequences (usually the “innermost” sequence) so eye-tracker data can be collected.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the Sequence node. The default label
is “SEQUENCE”.
The type of Experiment Builder object
("Sequence") the current node belongs to.
The absolute path of the node in the experiment
graph.
Display computer time (in milliseconds from
the start of the experiment) when the sequence
is executed.
Whether EyeLink recording should be done
within the sequence. Recording is done for each
iteration of the sequence, starting at the
beginning of the sequence and ending after
executing the nodes along one of the flow paths.

Type #

Node Path #

.absPath

String

Time #

.time

Float

Record †

.record

Boolea
n

The default setting is “False” (box unchecked).
This attribute is only available in an EyeLink
experiment.
Time (in milliseconds) to wait to execute the
sequence after the recording starts (typically set
as 20). This attribute is only available in an
EyeLink experiment with the “Record” attribute
of the current sequence enabled.
This supplies the title at the bottom of the Host
PC recording screen. This attribute is only
available in an EyeLink experiment with the
“Record” setting of the current sequence
enabled.

Recording Pause
Time

.recordingPauseT
ime

Integer

EyeLink Record
Status Message

.eyeLinkRecordS
tatusMessage

String

Custom Trial
ID Message

.customTrialID
Message

String

This property will only be available when
the "Enable Custom Trial ID Message"
option in "Edit -> Preferences ->
Experiment" is enabled. Instead of the
default value of "TRIALID", users can send
out a customized Trial ID message that can
be used by their analysis software. For
compatibility with EyeLink Data Viewer,
we recommend users starting this message
with a "TRIALID " token, followed by
whatever trial-specific condition data they
wish to send.

Trial Result

.trialResult

Integer

A value used to encode the result of the current
recording trial (e.g., "MSG 1067284
TRIAL_RESULT 12" in the EDF file). It is 0 by

SR Research Experiment Builder User Manual

Is Real Time †

.isRealTime

Boolea
n

Iteration #
Iteration Count

.iteration
.iterationCount

Integer
Integer

Split by

.splitBy

List of
Integer
s

Data Source

Freeze Display
Until First
Display Screen †

.freezeDisplayUn
tilFirstDisplayScr
een

Boolea
n

Prompt for
Dataset File †

.promptForDatas
etFile

Boolea
n

Callback

Result #
Result Data

NR
NR

default but can be referenced to some responses
made in the trial. This attribute is only available
in an EyeLink experiment with the "Record"
setting of the current sequence enabled.
When set to True, sets the application priority to
real-time mode. Real-time mode is only
maintained for the duration of the sequence. The
default setting is “False” (box unchecked).
It may take up to 100 milliseconds, depending
on the operation system, for the real-time mode
to stabilize. Also note that on some (older)
computers, real-time mode locks keyboard and
mouse inputs from occurring. For recent
computers with dual- or multicore processors,
the keyboard and mouse will function properly
in the real-time mode.
The current iteration of the sequence execution.
Total number of times (1 by default) the
sequence should be executed.
Specifies the number of iterations to be
executed each time the sequence is encountered.
If the list is not empty, each number in the list
should be no less than 1.
Double clicking on this field will bring up a data
Source editor (see Chapter 9 “Data Source” for
details). The "Columns: X/Rows: X” reports the
amount of data in the data source.
If checked, the display will not be updated until
the call of the first Display Screen action within
the sequence (to avoid some undesired display
changes). The field should be checked in most
experiments.
If checked, a dialog box will show up at the
beginning of the experiment to allow the user to
choose the intended dataset file. If unchecked, it
will load in the default dataset file.
For an experiment project with custom class
enabled, a method defined in the custom class
can be run for every poll of the sequence.
Similar to the EXECUTE action, a list of
parameters will be displayed if a method is
selected from a custom class instance. Please
note that running this callback function may add
an extra delay to sequence polling and it should
be used with caution (please avoid running any
callback function that takes a significant amount
of time to finish).
Result of the execution method.
Type of the data returned by the execute

SR Research Experiment Builder User Manual

Type #

method.

A recording sequence must be included in an EyeLink experiment. To specify a sequence
as a recording sequence, select the sequence and tick the "Record" checkbox in the
properties panel. This checkbox is only available in an EyeLink experiment, and only in
sequences not already contained within a recording sequence.
If the "Record" box is checked, users will see additional properties: "EyeLink Record
Status Message" allows users to send a text message to be displayed at the bottom of the
tracker screen, for instance, to inform the experimenter of the progress of experiment
testing; and "Recording Pause Time" controls the delay in executing the sequence
following the start of the tracker recording. To maximize real-time performance in data
collection, users should have the "Is Real Time" box checked for the Recording sequence
and include a prepare sequence action before executing the sequence.
The Recording sequence enables on-line access to gaze data, so all the eye-based triggers
can be only used in a recording sequence—i.e., the invisible boundary, fixation, saccade,
and sample velocity triggers. Conversely, the drift correction and camera setup actions
cannot be used in a recording sequence.

7.6.1 Typical Use of Sequences in an Experiment
The following figure illustrates the use of sequences in a typical experiment. In this
example, a RECORDING sequence that performs the actual eye-tracker recording is
nested within a TRIAL sequence, which itself is nested within a BLOCK sequence. The
"Record" field is checked in the RECORDING sequence but not in the BLOCK or
TRIAL sequences. The RECORDING sequence also allows users to send a message
(EyeLink Record Status Message) to the tracker screen so that the experimenter can be
informed of the progress of the experiment.

SR Research Experiment Builder User Manual

Figure 7-9. Using Sequences in an Experiment.
The iteration count of a sequence specifies the maximum number of times the sequence
should be executed, while the "Split by" field allows users to flexibly configure the
number of actual iterations to be executed. By default, the "Split by" field contains an
empty list "[]", which means that all of the iterations should be executed each time the
sequence is called. Users can add values to the split-by list to specify the actual number
of iterations to be executed for each call of the sequence. This allows users to easily
design experiments in which unequal numbers of trials are tested in different blocks. In
the above example, the iteration count of the BLOCK sequence is 3 and the split-by list is
empty. This means that the BLOCK sequence will be executed three times in total (i.e., 3
blocks). The total iteration count of the TRIAL sequence is 12 and its split-by field
contains a list of [2, 5, 5]. This means that the TRIAL sequence will be executed two,
five, and five times during the first, second, and last call of the BLOCK sequence. The
iteration count of the RECORDING sequence is 1 and the split-by list is empty. This
means that the recording sequence will be executed once for each call (in other words,
once per trial). Therefore, the above graph indicates that this experiment has three blocks,
which contains two, five, and five trials, respectively. Each trial will perform one eyetracker recording.

SR Research Experiment Builder User Manual

7.6.2 EyeLink Recording Status Message
During data collection, the EyeLink Record Status Message can be used to display a text
message at the bottom of the tracker screen, e.g., to inform the experimenter of the
progress of the experiment, or to report trial condition information (so that the
experimenter knows immediately which condition is being tested and therefore may be
able to evaluate the performance of the participant). To configure the status message,
select the recording sequence. Make sure that the “Record” property of the sequence is
checked, otherwise the “EyeLink Record Status Message” property will not be displayed.
Click the Value field of the EyeLink Record Status Message property, then click the [ …
] button to bring up the attribute editor. Then enter the message string, making sure the
string is shorter than 80 characters for an EyeLink II, 1000, 1000 Plus, or Portable Duo,
and shorter than 40 characters for an EyeLink I (see Figure 7-10). Make sure to include
only ASCII characters in the message screen, as non-ASCII characters will not be
displayed properly.
For example, if a user has a data source with the variables “Trial” and “Word”, the record
status message can be:
="Trial " + str(@parent.iteration@) + "/" +
str(@parent.iteratonCount@)+ “ “ +str(@TRIAL_SEQ_DataSource.Word@)

Figure 7-10. Creating Recording Status Message.
If the values for “.iteration” and “word” are “1” and “One” for the first trial and
“.iterationCount” is 12, this will display “Trial 1/12 One” on the tracker screen.

SR Research Experiment Builder User Manual

Figure 7-11. Sending the Recording Status Message to the Tracker.

7.7 Start Node
For each sequence in an experiment graph, the flow always begins with the default
"START" node. Each sequence requires a connection made from the "START" node to a
trigger or an action. The START node cannot receive a connection from other nodes.
Field

Type

Type #

Attribute
Reference
NR

Node Path #

.absPath

String

Time #

.time

Float

Content
The type of Experiment Builder object ("Start")
the current node belongs to.
The absolute path of the node in the experiment
graph.
Display computer time (in milliseconds from
the start of the experiment) when the experiment
flow starts.

7.8 Actions
SR Research Experiment Builder supports a list of actions, such as displaying a screen,
performing drift correction, performing camera setup and calibration/validation, sending
a message to an EDF file or to a log file, preparing a sequence, sending a command,
sending a TTL signal, updating variable values, adding to a results file, adding data to an
SR Research Experiment Builder User Manual

accumulator, playing sound, recording sound, recycling a data source line, or terminating
the experiment. Actions can be accessed by clicking on the "Action Tab" of the
Component Toolbox (see Figure 7-12). The following sections describe the usage and
properties of each action type in detail.

Figure 7-12. Action Tab of the Component Toolbox.

7.8.1 Display Screen
The DISPLAY_SCREEN action (
) is used to show visual stimuli on a computer monitor.
Double clicking on the newly added DISPLAY_SCREEN action will show a blank Screen
Builder workspace for creating visual displays. Please follow Chapter 8 “Screen Builder”
to modify the content of the screen.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the Display Screen action. The default
value is “DISPLAY_SCREEN”.
The type of Experiment Builder object
("DisplayScreen") the current node belongs to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with "Save Messages"
attribute of the Experiment node checked) when
display screen action is processed.
Display computer time (in milliseconds from
the start of the experiment) for the start of the
retrace when the screen was actually
drawn/redrawn.

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Important: This is the field you should use to
check for the time when the display is actually
shown.
Display computer time (in milliseconds from
the start of the experiment) when the display
screen action is entered (so that the graphics can
be prepared and shown). Note: the display
screen is not shown yet by this time. Use
the .time field instead to report the time when
the display is actually shown.
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to

SR Research Experiment Builder User Manual

Prepare Time #

.prepareTime

Float

Width #

.width

Integer

Height #

.height

Integer

Background
Color
Bits Per Pixel #

.backgroundColo
r
.bitsPerPixel

Color

Auto Generate
Sync Messages
†

.autoGenerateSyn
cMessages

Boolea
n

Resource Count

.resourceCount

Integer

Grid Rows *

Integer

Grid Columns *

Integer

Force Full
Redraw †

.forceFullRedraw

Boolea
n

Prepare Next
Display Screen
Action

.prepareNextDisp
layScreenAction

Boolea
n

Integer

ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
Actual time (in msec) used to prepare for the
display screen action.
The width of the display screen in pixels (1024
by default)
The height of the display screen in pixels (768
by default)
The background color of the screen. The
default color is white (255, 255, 255).
The number of bits (32 by default) used to
represent the luminance and chroma information
contained in each pixel.
Whether or not to a send a default message
(“SYNCTIME”) when the display changes.
This message will not be generated if the
“Message” field is filled. The default setting is
“false” (box unchecked).
Number of resources included in the display
screen action, not including screen background.
If the “toggle grid visibility” button in the
Screen Builder toolbar is on, several horizontal
lines will be drawn to divide the screen into the
specified number (2 by default) of rows.
If the “toggle grid visibility” button in the
Screen Builder toolbar is on, several vertical
lines will be drawn to divide the screen into the
specified number (3 by default) of columns.
If checked, this will force a full redraw of all
resources on the display screen. If unchecked,
this will just redraw the resources that require
updating (e.g. mouse-contingent resources,
gaze-contingent resources, moving resources,
and resources whose position or visibility has
been modified) as well as other resources drawn
beneath them. Having this option unchecked
will typically decrease the time required to
update the screen. However, if the screen
contains a large number of resources,
performing a full redraw may actually be more
efficient sometimes. The possible values are
“True” and “False” (default value).
If the current display screen action is followed
by one specific display screen action across all
possible flow routes (i.e., resolving to only one
possible display and not looping back to itself),

SR Research Experiment Builder User Manual

Estimated
Prepare Time

.estimatedPrepare
Time

Float

Default
Estimated
Prepare Time #

.defaultEstimated
PrepareTime

Float

Auto Update
Screen

.autoUpdateScree
n

Boolea
n

checking this box will have the next display
screen prepared in advance for a faster display
presentation. If the current screen may lead to
multiple display screens or update attribute
actions, checking this box will not have any
effect (as Experiment Builder does not know
which screen to prepare). Please note that the
current display screen should not contain any
gaze- or mouse-contingent resources, video
resources, or any resources with a movement
pattern.
Time (in milliseconds) required to prepare for
the display screen. This is typically set to the
value of Default Estimated Prepare Time. The
preparation time is influenced by screen
resolution, computer video hardware, and
whether the screen resources have been
preloaded or not. Note that the Estimated
Prepare time is useful only when a timer trigger
is used before the display screen action. This
allows the timer to pre-release for the
preparation of the following display screen
action.
Default time (in milliseconds) set for display
screen preparation. Typically this is set to 1.5
times of a display refresh cycle. Note that the
Estimated Prepare time is useful only when a
timer trigger is used before a display screen.
This allows the timer to pre-release for the
preparation of the following display screen
action.
If true (default), the display screen will be
updated automatically without re-entering the
display screen action again. This applies to
anything that modifies the currently visible
screen (e.g., if there are mouse- or gazecontingent resources on the screen, resources
have movement patterns, or resources
visibility/position is modified by
update_attribute action or custom class code,
etc). If false, the screen is only ever updated
when the display screen action is re-entered (so
no automatic screen updating of any kind is
done). Note: If a static display is used (i.e., none
of the above mentioned manipulations is
applicable), turning off this option might be
advantageous and will improve timing
performance (e.g., faster trigger firing) as the
program does not have to constantly check
whether the display should be updated.

SR Research Experiment Builder User Manual

Send EyeLink
DV Messages†

.sendEyeLinkDV
Messages

Boolea
n

Use for Host
Display †

.useForHostDispl
ay

Boolea
n

Interest Area Set
Name

.interestAreaSetN
ame

String

Synchronize
Audio †

.syncAudio

Boolea
n

Sound Offset

.soundOffset

Integer

Sound Time

.soundTime

Float

If checked, writes messages (“!V
DRAW_LIST” and “!V IAREA”) to the EDF
file for the ease of analysis with EyeLink Data
Viewer. This message will draw images/simple
graphics in Data Viewer as the background for
gaze data and record interest area data for the
screen. This field is only available when the
display screen action is contained in a recording
sequence.
If checked, the current screen will be transferred
to the Host PC as a bitmap or primitive
drawings for online gaze feedback. This field
needs to work together with the “Draw to
EyeLink Host” field of the
PREPARE_SEQUENCE action. This attribute
is only available in an EyeLink experiment.
If users have interest area set files, they can first
add the interest area set files into the library
manager, then set this field to the desired
interest area set file. Please make sure the
interest area file name does not contain a space
or any non-ASCII characters. Returns
“MISSING_DATA” if no value is set in this
field. This attribute is only available in an
EyeLink experiment.
Allows a sound file to be played relative to the
presentation of the screen. When checked, this
will bring up a list of additional properties to
specify the parameters of the sound playback.
This option is available in Mac OS X, and in
Windows when the ASIO driver is used to play
sound clips (see the "Audio Driver" setting in
the Audio Device settings of the Structure
panel).
Intended start time of the audio playing (in
milliseconds) relative to the onset of the display
screen. A 0 offset value means the audio and
visual stimuli are presented at the same time; a
positive offset means that the audio starts after
the visual stimulus; and negative offset means
the audio starts before the visual stimulus.
Display PC Time (in milliseconds from the start
of the experiment) when the sound begins to
play.

7.8.1.1 Reading Display Time
If the "message" property of the display screen action is filled, a message will be written
to the EDF file (for an EyeLink experiment) or messages.txt file (for a non-EyeLink
SR Research Experiment Builder User Manual

experiment) in the "results/{Experiment Session Name}" folder. The following is a
sample output from one experiment session.
5038.401 -2 DISPLAY_SCREEN_EVENTS
22220.512 PREPARE_SEQUENCE
22264.206 -15 DISPLAY_BLANK_INITIAL
23265.601 -14 DISPLAY_RED
23298.943 -14 DISPLAY_BLANK_RED
23398.964 -14 DISPLAY_GREEN
23432.382 -14 DISPLAY_BLANK_GREEN
The messages are written in the following format:
Time [Offset] Message_text
Where,
• "Time" reflects the time (in milliseconds) since the experiment was started for a
non-EyeLink experiment or the Host PC time (EDF file time) since the EyeLink
host program was started.
• "Offset" is an optional integer, which is subtracted from the above "Time" field to
generate the real message time. For example, a message line of "2435806.072 -14
display_screen" means that the event the message was referring to
(display_screen) actually happened at time 2435820.072 (= 2435806.072 - (-14)).
• "Message_text" is the text sent when the action is executed or trigger fires.
This means that in the above sample output file: The DISPLAY_BLANK_INITIAL was
shown at time 22279.206, and DISPLAY_RED was shown at time 23279.601 (1000
following DISPLAY_BLANK_INITIAL). DISPLAY_BLANK_RED was shown at
23312.943 (33 msec following the onset of DISPLAY_RED). DISPLAY_GREEN was
shown at 23412.964 (100 msec following the onset of DISPLAY_BLANK_RED).
Finally, DISPLAY_BLANK_GREEN was shown at 23446.382 (34 msec following the
onset of DISPLAY_GREEN).

7.8.1.2 Using Display Screen Actions
The following figure illustrates a simple experiment trial by displaying a screen and then
waiting either for a button response from the participant, or for the sequence to end after
a pre-specified amount of time set in the TIMER trigger. For the ease of data analysis
(reaction time calculation, for example), users should record an EyeLink message to the
EDF file when the display is presented. This can be done by entering a text message in
the "Message" field.
In a trial with multiple display screens, each of the display-screen actions should send a
unique Data Viewer integration message. In a recording sequence, users may enable the
"Use for Host Display" button only for the primary display of the trial for gaze accuracy
monitoring. Please add a PREPARE_SEQUENCE action before the recording sequence,
SR Research Experiment Builder User Manual

with its "Draw to EyeLink Host" field enabled.

Figure 7-13. Using Display Screen.

7.8.2 Performing Drift Correction
For many experiments it can be beneficial to display a fixation point at the start of each
trial or a set of trials so the participant's gaze can be checked against a known position.
EyeLink I and II eye trackers use this fixation point to correct for small drifts in the
calculation of gaze position that can build up over time. Even when using the EyeLink II
tracker's corneal reflection mode, a fixation target should be presented, and a drift
correction allows the experimenter the opportunity to recalibrate if needed.
For the EyeLink 1000, 1000 Plus, and Portable Duo, a drift check, rather than a drift
correction, will be performed by default. A drift check measures and reports the fixation
error without actually correcting for it, and allows the experimenter to recalibrate if
needed. To enable drift correction on these later trackers, users may add the line
“driftcorrect_cr_disable = OFF” to the Final.ini file in the host directory or by sending an
EyeLink Command at the beginning of the experiment.

SR Research Experiment Builder User Manual

Experiment Builder implements the drift correction/drift check feature using the Drift
Correction action (
). The display coordinate of the fixation target should be supplied.
Usually this is at the center of the display, but can be anywhere that gaze should be
located at the start of trial recording, for instance, in a line of text, the target could be
positioned just before the first word.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the Drift correction action. The default
value is “DRIFT_CORRECT”.
The type of Experiment Builder object
("DriftCorrection") the current node belongs to.
The absolute path of the current node in the
experiment graph.
Message to be sent to the EDF file when the
drift correction action is done.
Display PC time (in milliseconds from the start
of the experiment) when the drift correction
action is done.
Display PC time (in milliseconds from the start
of the experiment) when the drift correction
state is entered (the drift correction is not done
yet by this time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
X coordinate of the drift correction target in
screen pixels. Typically this is center of the
screen, but can be set to any other screen
location.
Y coordinate of the drift correction target in
screen pixels. Typically this is center of the
screen, but can be set to any other screen
location.
If this is checked, the Camera Setup screen on
the host software can be called up by pressing
the ESC key during drift correction so that
calibration problems can be corrected. The
default setting is “True”.
By default (the box is checked), the drift
correction procedure clears the screen, draws

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

X Location

.xLocation

Integer

Y Location

.yLocation

Integer

Allow Setup †

.allowSetup

Boolea
n

Draw Drift
Correction

.drawDefaultTarg
et

Boolea
n

SR Research Experiment Builder User Manual

Target †

Clear Target At
Exit †

.clearTargetAtExi
t

Boolea
n

Foreground
Color
Background
Color

.foregroundColor

Color

.backgroundColo
r

Color

Use Animation
Target †

.useAnimationTa
rget

Boolea
n

Animation
Target ¶

.animationTarget

String

Animation Play
Count

.animationPlayCo
unt

Integer

Apply
Transparency

.applyTransparen
cy

Boolea
n

the fixation target, and clears the screen when
done. However, sometimes it is better for the
user to draw the target themselves, for example
if the drift correction is part of the initial
fixation in a task and the user wants the target to
stay on the screen after drift correction. If this
field is unchecked, the user should draw the
drift correction target in a DISPLAY_SCREEN
action before the drift correct.
If checked, the screen will be cleared to the
background color after the drift correction
finishes; otherwise, the drift correction target
remains on the screen. This option is valid only
if the "Draw Drift Correction Target" option is
enabled; it has no effect if the drift correction
drawing is supplied by the users.
Color in which the drift correction target is
drawn.
The color to which the entire display is cleared
before calibration. The background color should
match the average brightness of your
experimental displays as closely as possible, as
this will prevent rapid changes in the subject's
pupil size at the start of the trial. This will
provide the best eye-tracking accuracy as well.
Using white or gray backgrounds rather than
black helps reduce pupil size and increase eyetracking range, and may reduce retinal
afterimages.
If checked, a video clip can be used as the drift
correction target. Users should preload the
intended video clip into the library manager.
The name of the video clip used as the drift
correction target. The video to be used as the
animation calibration target should be a type 1
.avi file, containing both video frames and audio
stream. This field is only available if the “Use
Animation Target” option is checked.
Total number of times the video clip will be
played before the calibration target is accepted.
If -1, the clip will be played continuously
(looping). This field is only available if the “Use
Animation Target” option is checked.
If checked, transparency manipulation will be
applied to the video resource similar to that
which is done on the image resources (i.e.,
pixels with the same color value as the
transparency color will not be displayed). We
recommend keeping the default setting
(unchecked).

SR Research Experiment Builder User Manual

Use Custom
Target †

.useCustomTarge
t

Boolea
n

Custom Target *

.customTarget

String

Target Outer
Size

.outerSize

Integer

Target Inner
Size

.innerSize

Integer

Use Custom
Background †

.useCustomBack
ground

Boolea
n

Custom
Background *

.customBackgrou
nd

String

Target Beep ¶

.targetBeep

String

Error Beep ¶

.errBeep

String

Good Beep ¶

.goodBeep

String

Enable External
Control

.enableExternalC
ontrol

External Control
Device Config

.externalControl
DeviceConfig

Boolea
n

String

If checked, drift correction will use the custom
target supplied by the users (a small image file,
with the "feature"/interesting part appearing in
the center of the image).
The name of the image file that is used for
drawing the drift correction target. The image
files should be preloaded into the library
manager. This property is only available if "Use
Custom Target" is checked.
Diameter of the outer disk of the default drift
correction target in pixels. This property is only
available if “Use Custom Target” is not
checked.
Diameter of the inner disk of the default drift
correction target in pixels. This property is only
available if “Use Custom Target” is not
checked.
If checked, drift correction will use the custom
background image supplied.
The name of the image file that is used for
drawing the drift correction background. The
image file should ideally be a full-screen image
and must be preloaded into the library manager.
This property is only available if "Use Custom
Background" is checked.
Sets sound to play when the drift correction
target is presented. If set to DEFAULT, the
default sound is played; if set to OFF, no sound
will be played for that event; otherwise a sound
file from the audio library can be played.
Sets sound (DEFAULT, OFF, or sound file) to
play on failure or interruption.
Sound (DEFAULT, OFF, or sound file) to play
on successful operation.
Toggling through different camera views,
adjusting pupil and CR thresholds, and
accepting calibration, validation and drift
correction targets are usually done through key
presses on the Display or Host PC keyboard.
However, the keyboard may not be easily
accessible in some experiments. Enabling this
option allows the use of an external control
device to assist the pupil/CR thresholding and
calibration process.
This specifies a file used to define button
functions to control the pupil/CR thresholding
and to accept calibration, validation, and drift
correction target. If this field is left blank, the
default configuration is used. This property is

SR Research Experiment Builder User Manual

External Control
Device

.externalControl
Device

Button State
Callback
Function

Result #

.result

String

Integer

only available if the "Enable External Control"
option is checked.
The type of external device that is used to
control the camera setup, calibration and
validation processes. This can be "CEDRUS"
(Lumina fMRI Response Pad or RB Series
response pad from Cedrus), "KEYBOARD"
(computer keyboard or keypad), or "CUSTOM"
(a user control device interfaced through a
callback function defined in the custom class
code). This property is only available if the
"Enable External Control" option is checked.
For an experiment project with custom class
enabled, a method defined in the custom class
can be run to check the button status of an
external control device (the HTML version of
this document provides a usage example) and
thus to control the camera image thresholding
and calibration through the "External Control
Device Config" setting. This property is only
available if the "External Control Device"
option is set to "CUSTOM".
0 if successful; 27 if the ESC key is pressed to
enter Setup menu or abort; “None” if this
attribute is accessed before this action is done.

Please note that the Drift Correction action is only available in an EyeLink experiment
and must be placed outside of a recording sequence (see Section 6.2.3 “Linking Rules”).
In addition, this action cannot be connected to another drift correct action or any trigger.
If a prepare sequence action is used, it should be placed before the drift correction action.
The "Allow Setup" field is checked by default, so that when the "ESC" key is pressed, the
host software switches to the camera setup screen. This allows the experimenter to make
adjustments to the camera setup and thresholding, and redo calibration and validation,
then return to the drift correction screen to continue with the experiment.
The "Draw Drift Correction Target" box should be checked if the built-in or custom drift
correction target should be displayed when entering the drift correction mode. In some
(e.g., pursuit or saccade) experiments, users may want to have the drift correction target
be the same as the pursuit target or other display items. If this is the case, users may
uncheck this box and insert a display screen action to pre-draw the drift correction target.
However, a drawback with this approach is that if users have to interrupt the drift
correction process by switching to the camera setup screen and then come back to the
drift correction again, the target will no longer be drawn. Alternatively, users may have
both the "Draw Drift Correction Target" and "Use Custom Target" fields checked and
supply an image for the "Custom Target" field.
The following figure illustrates the use of the drift correction action in a typical trial.

SR Research Experiment Builder User Manual

Figure 7-14. Using Drift Correction Action.

7.8.3 Performing Camera Setup and Calibration
The Camera Setup action (
) will bring up a camera setup screen on the EyeLink Host
PC for the experimenter to perform camera setup, calibration, and validation. Scheduling
this at the start of each block gives the experimenter a chance to fix any setup problems.
Simply pressing the ESC key immediately can skip calibration. This also allows the
participant an opportunity for a break - the entire setup can be repeated when the
participant is reseated. Users can set the calibration type and other calibration
configurations through this action.
Typical operations for the camera setup and calibration can be performed by using either
the Host PC keyboard or the Display PC keyboard. Using the display computer monitor
and peripherals, Camera Setup and Calibration can also be performed through an external
control device for environments in which the Host PC is located far away from the
display (e.g., MEG/MRI environments).
Field

Attribute
Reference

Type

Content

SR Research Experiment Builder User Manual

Label *

.label

String

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Calibration Type
¶

.calibrationType

String

Horizontal
Target Y
Position

.horizontalTarget
Location

Integer

Pacing Interval

.pacingInterval

Integer

Label of the Camera setup action. The default
value is “EL_CAMERA_SETUP”.
The type of Experiment Builder object
("EyeLinkCameraSetup") the current node
belongs to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the "Save Messages"
attribute of the Experiment node checked) when
camera setup action is done.
Display PC time (in milliseconds from the start
of the experiment) when the camera setup action
is done.
Display PC time (in milliseconds from the start
of the experiment) when camera setup action
starts (the calibration is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
This sets the calibration type. One of these
calibration types can be selected from the
dropdown list:
H3: horizontal 3-point calibration
HV3: 3-point calibration, bilinear
HV5: 5-point calibration, biquadratic
HV9: 9-point grid calibration, biquadratic with
corner correction
HV13: 13-point calibration (EyeLink II version
2.0 or later; Any versions of EyeLink 1000,
EyeLink 1000 Plus, EyeLink Portable Duo).
The default calibration type is HV9. When
using the head-free remote mode, the HV13 is
recommended.
This sets the Y position of the automaticallygenerated targets for the H3 calibration type.
This option is only available when the
calibration type is set to H3.
Sets the time delay in milliseconds for
calibration and validation if calibration

SR Research Experiment Builder User Manual

Randomize
Order †
Repeat First
Point †
Force Manual
Accept †
Lock Eye After
Calibration †

.randomizeOrder

.forceManualAcc
ept
.lockEyeAfterCal
ibration

Boolea
n
Boolea
n
Boolea
n
Boolea
n

Select Eye After
Validation †

.selectEyeAfterV
alidation

Boolea
n

Enable
Customized
Calibration
Positions †
Customized
Calibration
Positions

.enableManualCa
librationPositions

Boolea
n

.calibrationPositi
ons

List of
Points

.repeatFirstPoint

triggering is done automatically
If checked, randomizes the presentation
sequence of the calibration and validation
targets.
If checked, redisplays the first calibration or
validation fixation dot.
If checked, users have to manually accept each
calibration and validation fixation point.
If checked, locks the recording eye on the
display computer keyboard if performing a
monocular recording.
Controls whether the best eye is automatically
selected as the default after validation. If
unchecked, binocular tracking is kept by
default.
If checked, user-defined calibration positions
can be used, instead of the default positions.
A list of X/Y pairs to specify the calibration
target positions in the intended display screen
resolution. The number of points included in the
list must match the calibration type. This option
is only available if the "Enable Customized
Calibration Positions" setting is enabled. The
following lists example (default)
calibration/validation point lists under a 1024 *
768 recording resolution. Please be aware that
the points in the list MUST be ordered on
screen.
* Point order for 5, 9, or 13 point calibrations:
6
2
7
10 11
4
1
5
12 13
8
3
9
HV5: [(512,384), (512,65), (512,702),
(61,384), (962,384)]
HV9: [(512,384), (512,65), (512,702),
(61,384), (962,384), (61,65), (962,65), (61,702),
(962,702)]
HV13: [(512,384), (512,65), (512,702),
(61,384), (962,384), (61,65), (962,65), (61,702),
(962,702), (286,224), (737,224), (286,543),
(737,543)]

SR Research Experiment Builder User Manual

* Point order for H3 calibration type:
2
1
3
H3: [(512,384), (61,384), (962,384)]
* Point order for HV3 calibration type:
1
3
Enable
Customized
Validation
Positions †
Customized
Validation
Positions

.enableManualVa
lidationPositions

Boolea
n

.validationPositio
ns

List of
Points

Foreground
Color

.foregroundColor

Color

Background
Color

.backgroundColo
r

Color

Use Animation
Target †

.useAnimationTa
rget

Boolea
n

Animation
Target ¶

.animationTarget

String

Animation Play
Count

.animationPlayCo
unt

Integer

HV3: [(512,65), (962,702), (61,702)]
If checked, user-defined validation positions can
be used, instead of the default positions.
A list of X/Y pairs to specify the validation
target positions in the intended display screen
resolution. These points MUST be ordered on
screen and match the calibration type selected.
See “Customized Calibration Positions” for
examples. This option is only available if the
"Enable Customized Validation Positions"
setting is enabled.
Color used to draw calibration targets, and for
the text on the camera image display. It should
be chosen to supply adequate contrast to the
background color.
The color to which the entire display is cleared
before calibration. This is also the background
for the camera images. The background color
should match the average brightness of your
experimental displays as closely as possible,
as this will prevent large changes in the
participant's pupil size at the start of the trial.
This will provide the best eye-tracking accuracy
as well.
If checked, a video clip can be used as the
calibration target. Users should preload the
intended video clip into the library manager.
The name of the video clip used as the
calibration target. The video to be used as the
animation calibration target should be a type 1
.avi file, containing both video frames and audio
stream. This field is only available if the “Use
Animation Target” option is checked.
Total number of times the video clip will be
played before the calibration target is accepted.
If -1, the clip will be played continuously
(looping). This field is only available if the “Use
Animation Target” option is checked.

SR Research Experiment Builder User Manual

Apply
Transparency

.applyTransparen
cy

Boolea
n

Use Custom
Target †

.useCustomTarge
t

Boolea
n

Custom Target

.customTarget

String

Use Custom
Background †
Custom
Background

.useCustomBack
ground
.customBackgrou
nd

Boolea
n
String

Target Outer
Size

.outerSize

Integer

Target Inner
Size

.innerSize

Integer

Target Beep ¶

.targetBeep

String

If checked, transparency manipulation will be
applied to the video resource similar to that
which is done on the image resources (i.e.,
pixels with the same color value as the
transparency color will not be displayed). We
recommend keeping the default setting
(unchecked).
If checked, calibration will use the custom
target supplied (a small image file, with the
"feature"/interesting part appearing in the center
of the image).
The name of the image file that is used for
drawing the calibration target. The image file
should be preloaded into the library manager.
This property is only available if "Use Custom
Target" is checked.
If checked, calibration will use the custom
background image supplied.
The name of the image file that is used for
drawing the calibration background. The image
file should ideally be a full-screen image and
must be preloaded into the library manager.
This property is only available if "Use Custom
Background" is checked.
The standard calibration and drift correction
target is a filled circle (for peripheral
detectability) with a central "hole" target (for
accurate fixation). The disk is drawn in the
calibration foreground color, and the hole is
drawn in the calibration background color. The
"Target Outer Size" property specifies the
diameter of the outer disk of the default
calibration target in pixels. This property is only
available if "Use Custom Target" is not
checked.
Diameter of the inner disk of the default
calibration target in pixels). If hole size is 0, no
central feature will be drawn. This property is
only available if "Use Custom Target" is not
checked.
Experiment Builder plays alerting sounds during
calibration. These sounds have been found to
improve the speed and stability of calibrations
by cueing the participant, and make the
experimenter's task easier. The "Target Beep"
property specifies the sound to play when the
target moves. If set to DEFAULT, the default
sound will be played; if set to OFF, no sound
will be played; otherwise a sound file from the
audio library can be chosen.

SR Research Experiment Builder User Manual

Error Beep ¶

.errBeep

String

Good Beep ¶

.goodBeep

String

.enableExternalC
ontrol

Boolea
n

External Control
Device Config

.externalControl
DeviceConfig

String

External Control
Device

.externalControl
Device

String

Button State
Callback
Function

Result #

.result

Enable External
Control

Integer

Sound (DEFAULT, OFF, or sound file) to play
on failure or interruption.
Sets sound (DEFAULT, OFF, or sound file) to
play on successful operation.
Toggling through different camera views,
adjusting pupil and CR thresholds, and
accepting calibration, validation and drift
correction targets are usually done through key
presses on the Display or Host PC keyboard.
However, the keyboard may not be easily
accessible in some environments. Enabling this
option allows the use of an external control
device to assist the pupil/CR thresholding and
calibration process.
This specifies a file used to define the button
functions to control the pupil/ CR thresholding
and accept calibration, validation, and drift
correction targets. If this field is left blank, the
default configuration is used. This property is
only available if the "Enable External Control"
option is checked.
The type of external device that is used to
control the camera setup and accept calibration
and validation targets. This can be "CEDRUS"
(Lumina fMRI Response Pad or RB Series
response pad from Cedrus), "KEYBOARD"
(computer keyboard or keypad), or "CUSTOM"
(a user control device interfaced through a
callback function defined in the custom class
code). This property is only available if the
"Enable External Control" option is checked.
For an experiment project with custom class
enabled, a method defined in the custom class
can be run to check the button status of an
external control device and thus to control the
camera image thresholding and calibration/drift
correction through the "External Control Device
Config" setting. This property is only available
if the "External Control Device" option is set to
"CUSTOM".
Always returns “None”.

Please note that the Camera Setup action is only available in an EyeLink experiment and
must be placed outside of a recording sequence. As a linking rule, the camera setup
action cannot be connected to another camera setup action or any triggers. Figure 7-15
illustrates the use of camera setup in a typical experiment.

SR Research Experiment Builder User Manual

Figure 7-15. Using Camera Setup Action.

7.8.4 Sending EyeLink Message
While messages can be sent by filling out the “Message” property of a relevant node, the
SEND_EL_MESSAGE action (
) can be used to send an additional text message to the
EyeLink eye tracker, which timestamps the message and writes it to the EDF data file.
Messages are useful for logging trial conditions, recording responses from participants, or
marking time-critical events for debugging and analysis. The EDF message text can be
created with the attribute editor to include references to node attributes, equations and
other expressions. This action is not available in non-EyeLink experiments.
When using the SEND_EL_MESSAGE action, users should avoid end-of-line characters
(“\n”) in the message text and avoid making reference to strings with quotes (“”).
Message text should be no more than 128 characters in length – the tracker will truncate
text messages longer than that limit. Also be careful not to send messages too quickly: the
eye tracker can handle about 2 messages a millisecond. Above this rate, some messages
may be lost and not written to the EDF file.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the SEND_EL_MSG action. The

SR Research Experiment Builder User Manual

Type #

Node Path #

.absPath

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Message

.message

String

default value is "SEND_EL_MSG”.
The type of Experiment Builder object
("SendEyeLinkMessage") the current node
belongs to.
The absolute path of the node in the experiment
graph.
Display PC time (in milliseconds from the start
of the experiment) when the message is sent.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
Text to be sent to the eye tracker.

The following figure illustrates the use of the SEND_EL_MESSAGE action. In the
EyeLink Message field, users can enter a string directly (see the left panel at the bottom).
In case runtime data accessing is required, users may use references and equations and
create the message text in the attribute editor (see the right panel at the bottom; see
Chapter 10 “References” for details).

SR Research Experiment Builder User Manual

Figure 7-16. Using Sending Message Action.

7.8.5 Sending EyeLink Command
The EyeLink tracker accepts text commands sent through the link. The
SEND_COMMAND action (
) is used for on-line tracker configuration and control.
Please refer to the .ini files in the EyeLink directory of the Host PC (typically “elcl\exe”
for EyeLink 1000 Plus and Portable Duo, “c:\elcl\exe” for EyeLink 1000,
“c:\eyelink2\exe” for EyeLink II and “c:\EyeLink\exe” for EyeLink I) for a list of

SR Research Experiment Builder User Manual

possible commands that can be sent with this action. The send_command action is not
available in non-EyeLink experiments.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the SEND_COMMAND action. The
default value is “EL_COMMAND”.
The type of Experiment Builder object
("EyeLinkCommand") the current node belongs
to.
The absolute path of the node in the experiment
graph.
Display PC time (in milliseconds from the start
of the experiment) when the
SEND_COMMAND action is done.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
The command used to configure or control the
EyeLink tracker. For a complete list of
commands and current tracker configuration,
examine the *.INI files in the EyeLink directory
of the eye-tracker computer.
The parameters to be passed along with the
command.
If enabled, causes the command to be executed
with the highest priority. This priority is even
higher than the output of analog or link sample
data, so please use it carefully. The use of this
prefix should be limited to the “write_ioport”
command. Typical command execution is 1-20
ms after the action is pressed. With priority
enabled, this is reduced to less than 1 ms 99% of
the time—in the worst case, it may be about 10
ms but is rarely higher than 2 ms. The default
setting is “False”. This setting has no effect on
EyeLink I.
If enabled, logs the command and its delay in

Type #

Node Path #

.absPath

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Command

.command

String

Text

.text

String

Priority †

.priority

Boolea
n

Log Time †

.logTime

Boolea

SR Research Experiment Builder User Manual

Wait for Result
†
Result Timeout

.waitForResult

Exit On Fail †

.exitOnFail

Boolea
n

Result #

.result

Integer

Result Message
#

.resultMessage

String

.resultTimeout

Boolea
n
Integer

execution to the EDF file (and link if message
events are enabled). The default setting is
“False”. The message time is when the
command completed execution. The message
syntax is :
!CMD
This setting has no effect on EyeLink I.
Whether the program should wait for a response
from the tracker.
Sets the maximum amount of time to wait for a
response from the tracker. If no result is
returned, then the error code NO_REPLY is
returned.
Whether the experiment should be terminated if
there is an error in the command. Important:
please leave this field unchecked unless it is
absolutely necessary that you should terminate
the experiment if the EyeLink send command
action fails.
Result code for the command:
0: Command successfully sent;
1: Unknown command;
-1: Unexpected end of line;
-2: Syntax error;
1000: No reply from the tracker.
Returns text associated with last command
response: may have error message (see above).

Figure 7-17 illustrates how to draw a white filled box on the top-left quadrant of the
tracker screen using the EyeLink Command action. In the “Command” field, type in
“draw_filled_box” (without quotes) and in the “Text” field, enter “0 0 512 384 15”
(without quotes). Please refer to the .ini files on the Host PC for the syntax of EyeLink
commands.

SR Research Experiment Builder User Manual

Figure 7-17. Using Sending EyeLink Command Action.

7.8.6 Sending TTL Signals
The SET_TTL action (
) sends a TTL signal through the parallel port of a Windows
PC, or through the USB-1208 HS box in either Windows or Mac OS X. Version 1.6.121
or later of this software automatically installs the I/O port driver necessary for interfacing
with the parallel port in Windows (both 32-bit and 64-bit versions).
If using a parallel port, SET_TTL action requires proper identification of the base address
of the port. In version 1.10.1630 or later of the software, users may set the “Parallel Port
Base Address” of the “Parallel Port” Device to 0x0 so that the software will automatically
detect and configure the base address. To set the base address manually, first determine
the parallel port base address through the Device Manager in Windows. In the Device
Manager list, find the entry for the parallel port device under "Ports (COM & LPT)" - if
you use PCI, PCI Express, or PCMCIA version of the parallel port adapter card, you'll
need to install a driver for the port before it is correctly recognized by Windows. Click
the port and select the "Resources" in the properties table. This should list the I/O address
of the card. For the built-in LPT1 on a desktop computer, this is typically "0378-037F"
(hex value). Once you have found out the parallel port address, open the Experiment
Builder project, go to the "Parallel Port" device setting, and enter the hex value for the
port reported by the device manager (e.g., 0x378 for "0378" you see in the device
manager).

SR Research Experiment Builder User Manual

The other supported device is the USB-1208HS box from Measurement Computing,
which can be used on both Windows and Mac OS X. No extra driver installation is
required as long as you have installed the libusb-win32 component when you first run
through the installation procedure in Windows (see Figure 3-1). If for any reason you
have to install the device driver, please first connect the box to the Windows PC. When
asked "Can Windows connect to Windows Update to search for software?", choose "No,
not this time". When asked "What do you want the Wizard to do?", choose "Install from a
list or specific location (Advanced)". On the "Please choose your search and installation
options" screen, select the "Search for the best driver in these locations", check the
"Include this location in the search" option only and browse to "C:\Program Files\SR
Research\3rdparty\usb1208hs" in 32-bit Windows or "C:\Program Files(x86)\SR
Research\3rdparty\usb1208hs" in 64-bit Windows).
Field

Type

Content

Label *
Type #

Attribute
Reference
.label
NR

String

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Device

.device

String

.register

String

Label of the SET_TTL action.
The type of Experiment Builder object
("SetTTL") the current node belongs to.
The absolute path of the node in the experiment
graph.
Message to be written to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the “Save Messages”
attribute of the Experiment node checked) when
sending the TTL signal.
Display PC time (in milliseconds from the start
of the experiment) when the TTL signal is sent.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
Which device (parallel port or USB-1208 HS) is
used to send or receive TTL signals. Note that
this is always set to "USB-1208HS" on Mac OS
X.
Usually set as "DATA" register. Note that this
option is only available when the “Device” is

SR Research Experiment Builder User Manual

Mode *

.mode

String

Data

.data

Integer

Pin0
Pin1
Pin2
Pin3
Pin4
Pin5
Pin6
Pin7

.pin0
.pin1
.pin2
.pin3
.pin4
.pin5
.pin6
.pin7

String

set to a parallel port.
Either "Word" mode (the decimal or
hexadecimal value of the TTL output signal) or
"Pin" mode (status of each individual pin).
The byte value of the current TTL output signal.
It could be a decimal or hexadecimal value. This
field is only available if the "Mode" property is
set to "Word". If a decimal value is entered, it
will be automatically translated into a
hexadecimal value.
The desired status for the corresponding pins.
The pin value can be either "ON" (high) or
"OFF" (low). These fields are only available if
the "Mode" property is set to "Pin". If using a
USB-1208HS box, the available output pins can
be configured through the device preferences.

The TTL communication works by the detection of a change in the pin status in the
receiving end. Typically a clearing signal should be sent (e.g., 0x0) after sending the
intended TTL signal. The clearing signal may be sent using a second SET_TTL action
either at the end of the trial, or some time after the initial TTL signal (at least a 20 msec
gap is recommended). If the same TTL value is sent repeatedly, no change will be
detected on the receiving end.
For most applications involving a parallel port, users will need to use the "DATA"
register in the "Register" property of the SET_TTL action to send out a signal. Users
need to make sure the parallel port of the Display PC is not in a bi-directional mode, in
which the data register is used to read incoming signals, and thus users are not able to
send a signal from this register. Bidirectional mode is set by pin 5 of the control register.
To turn off the bidirectional mode, users may add a SET_TTL action at the beginning of
the experiment, and set the "Register" to "CONTROL", "Mode" to "Word", and "Data"
value to 0x0.
The pins on a USB-1208 HS box can be configured either for sending signals or for
receiving signals. To set which pins are used for sending and receiving, go to the “USB1208HS” device settings and click the "Value" field of the “Pins” property. This will
bring up a USB-1208HS configuration window. The arrows indicate the directions of
data flow that each pin is configured for: if the arrow points towards the box, the pin is
used to receive signals; if the arrow points away from the box, the pin is used to send
signals. To change whether a pin is used for sending or receiving signals, simply click on
the arrow next to the pin to change its direction. The following figure illustrates a
configuration in which pins 0 to 7 are used to send signals and pins 8 to 15 are used to
receive signals.

SR Research Experiment Builder User Manual

Figure 7-18. Configuring the Direction of Data Flow on USB-1208HS

7.8.7 Adding to Experiment Log
For the ease of experiment debugging, messages can be written to a log file so that errors
in the experiment programming can be detected early. The ADD_TO_LOG action (
)
allows users to send one log message per call. While the SEND_EL_MSG action is
available in an EyeLink experiment only, the ADD_TO_LOG action can be used in both
EyeLink and non-EyeLink experiments.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the ADD_TO_LOG action. The
default value is “ADD_TO_LOG”.
The type of Experiment Builder object
("AddToExperimentLog") the current node
belongs to.
The absolute path of the node in the experiment
graph.
Display PC time (in milliseconds from the start
of the experiment) when the action is processed.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,

Type #

Node Path #

.absPath

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

SR Research Experiment Builder User Manual

Log File
Message
Log File *

.logMessage

String

.logFile

String

mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
Message to be written to the log file.
File to which the log message is written. The
default file name is "Logfile". If this field is left
empty, the message will be printed to command
line (or the output tab of Experiment Builder if
test running the project).

In the following example (Figure 7-19), the user added a sample velocity trigger in the
experiment and wants to check out whether the correct values (e.g., left eye gaze position,
eye velocity and acceleration, and trigger time) are reported when the trigger fires. The
user may add an ADD_TO_LOG action following the sample velocity trigger, and set the
“Log File Message” field of the action as:

Figure 7-19. Using Add to Experiment Log Action.
=
+
+
+

"Trigger " + str(@SAMPLE_VELOCITY.triggeredData.EDFTime@)
" LOC "+ str(@SAMPLE_VELOCITY.triggeredData.leftGazeX@)
" " + str(@SAMPLE_VELOCITY.triggeredData.leftGazeY@)
" VEL " + str(@SAMPLE_VELOCITY.triggeredData.leftVelocity@)

SR Research Experiment Builder User Manual

+ " AC1000 " +
str(@SAMPLE_VELOCITY.triggeredData.leftAcceleration@)

The following is one sample output from the LogFile.txt file when the sample-velocity
trigger fires:
Trigger 852012 LOC 500.299987793 403.399993896 VEL 196.741027908
AC1000 98370.5273723

7.8.8 Updating Attribute
The UPDATE_ATTRIBUTE action (
) modifies the value of a variable or an attribute
of an experiment component. For example, in a change-detection experiment (see section
7.11.1 “Variable”), users may want to display two slightly different images for a certain
number of cycles and then stop the presentation after that. To do that, users may create a
new variable to keep track of the current iteration status (behaving as a counter) and use
the UPDATE_ATTRIBUTE action to update the counter’s value following each cycle.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the UPDATE_ATTRIBUTE action.
The default value is “UPDATE_ATTRIBUTE”.
The type of Experiment Builder object
("UpdateAttribute") the current node belongs to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the "Save Messages"
attribute of the Experiment node checked) when
the action is executed.
Display PC time (in milliseconds from the start
of the experiment) when the
UPDATE_ATTRIBUTE action is done.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
Used to set up an attribute-value list; the
number of currently established attribute-value

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Attribute-Value
List

SR Research Experiment Builder User Manual

pairs is displayed in the value field of the
property. To add or edit attribute-value pairs,
click the value field or double click the
UPDATE_ATTRIBUTE node. The "Attribute"
column of the dialog box specifies the variable
or attribute to which the current action is
referring and the "Value" column specifies the
new value assigned to the attribute.

Users can update the value of an attribute by assigning a value directly (e.g., setting the
value of VARIABLE1 to 0), referring to another attribute (e.g., retrieving the time when
the EyeLink button box was pressed and assign this time to VARIABLE2), or using an
equation (e.g., increasing the value of VARIABLE3 by 1).

Figure 7-20. Using Update Attribute Action.

SR Research Experiment Builder User Manual

7.8.9 Adding to Accumulator
The ADD_ACCUMULATOR action (
) is used to add data to an accumulator object
(see Section 7.11.3 “Accumulator” for example) so that statistical analysis can be
performed on the stored data.
Field
Label *

Attribute
Reference
.label

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Accumulator ¶*

Add Value

.addValue

7.8.10

Type

Content

String

Label of the ADD_ACCUMULATOR action.
The default value is
“ADD_ACCUMULATOR”.
The type of Experiment Builder object
("AddAccumulator") the current node belongs
to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the "Save Messages"
attribute of the Experiment node checked) when
the action is executed.
Display PC time (in milliseconds from the start
of the experiment) when the action is done.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
The accumulator the current action is referring
to.
This specifies the value (0.0 by default) to be
added to the accumulator.

Float

Adding to Results File

The ADD_TO_RESULTS_FILE action (
) is used to send data to a results file so that
users will get a columnar data output. Users should first add a RESULTS_FILE object
(see Section 7.11.2 “Results File” for example) into the experiment graph and then
SR Research Experiment Builder User Manual

configure the columns of the data source file and/or the variables to the results file. Note version 2.0 of Experiment Builder now automatically adds the variables and data source
columns to the “Columns” field of the results file node. If necessary, users can double
click on the field and use the dialog box to remove some variables/columns from the list
or to change the order of the variables/columns.
Field
Label *

Attribute
Reference
.label

Type #

Node Path #

.absPath

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Results File ¶*

7.8.11

Type

Content

String

Label of the ADD_TO_RESULTS_FILE action.
The default value is
“ADD_TO_RESULTS_FILE”.
The type of Experiment Builder object
("AddToResultsFile") the current node belongs
to.
The absolute path of the node in the experiment
graph.
Display PC time (in milliseconds from the start
of the experiment) when the action is done.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
The Results file the current action is referring
to.

Prepare Sequence

Before starting the portion of the experiment that contains the important experiment
manipulations and time-critical actions (often this is the sequence in which eye tracker
data is recorded as well), the experiment should be given the opportunity to prepare the
upcoming actions. The Prepare Sequence Action (
) includes the following operations:
a) Preload the image or audio files to memory for real-time image drawing or sound
playing;
b) Draw feedback graphics on the Host PC so that the participants’ gaze accuracy
can be monitored;
c) Re-initialize trigger and action settings;
SR Research Experiment Builder User Manual

d) Synchronize the clocks between the display computer and Cedrus button box;
e) Flush data to the log files.
In a typical experiment, users should call the Prepare Sequence action before entering the
recording sequence of a trial, preferably before performing a drift correction. In most of
the experiments, the “Reinitialize Triggers” box should be checked so that the data for
each trigger are reset for the nodes to function properly.
IMPORTANT: For the proper event timing, it is critical that the Prepare Sequence
Action should be called before the trial run-time for EACH iteration of the sequence.
IMPORTANT: The Prepare Sequence Action loads the image and audio files based on
the state of display screen and Play Sound actions at the time the Prepare Sequence is
called. This means that if an image name or audio file name is changed after the Prepare
Sequence action is called, the new image or audio resource will not be preloaded and
timing may be affected. If an image or audio file has not been preloaded when it is used
in the Display Screen or Play Sound action that references it, a warning message will be
written to the warnings.log file for the experiment session.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the PREPARE_SEQUENCE action.
The default value is “PREPARE_SEQUENCE”.
The type of Experiment Builder object
("PrepareSequence") the current node belongs
to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the "Save Messages"
attribute of the Experiment node checked) when
the PREPARE_SEQUENCE action is done.
Display PC time (in milliseconds from the start
of the experiment) when the
PREPARE_SEQUENCE action is processed.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

SR Research Experiment Builder User Manual

Load Screen
Resources *†

.loadImages

Boolea
n

Load Audio *†

.loadAudio

Boolea
n

Draw to
EyeLink Host *¶

.drawToEyeLink
Host

Integer

Reinitialize
Triggers *†
Reinitialize
Actions *†
Reinitialize
Video Resources
*†
Flush Log *†

.reinitTriggers

Boolea
n
Boolea
n
Boolea
n

.reinitActions
.reinitVideoReso
urces
.flushLogs

Boolea
n

means that events already in the queues may be
evaluated by the triggers following the action.
If enabled (default), all of the possible images
used in the current sequence (and sequences
nested within it) will be preloaded for real-time
performance.
If enabled (default), all of the possible sound
clips used in the current sequence (and
sequences nested within it) will be preloaded for
real-time performance.
If set to “NO” (0), no feedback graphics are
drawn on the Host PC screen. If set to
“IMAGE” (1), transfers one of the display
screens to the tracker PC as the backdrop for
gaze cursors. If set to “PRIMITIVE” (2), draws
primitive line drawings on the Host PC to
indicate the location of resources used in a
display screen. This attribute is only available in
an EyeLink experiment.
If checked, performing this action will also clear
trigger data for re-initialization.
If checked, performing this action will also clear
action data for re-initialization.
If checked, any video resources used in the
previous trial will be rewound to the beginning
of the clip.
If checked, this will write the messages to the
log file and clear the buffer.

The following (Figure 7-21) illustrates the use of the PREPARE_SEQUENCE action. In
this example, “Draw to EyeLink Host” field of the PREPARE_SEQUENCE action is set
to IMAGE. The “Use for Host Display” field of the DISPLAY_SCREEN is also checked
so that drawing on that screen will be shown on the Host PC.

SR Research Experiment Builder User Manual

Figure 7-21. Using Prepare Sequence Action.

SR Research Experiment Builder User Manual

7.8.12

Reset Node

Similar to the PREPARE_SEQUENCE action, the RESET_NODE action (
) can be
used to re-initialize trigger and action data. The RESET_NODE can also be used to clear
the data stored in an accumulator.
Field

Type

Content

Label *
Type #

Attribute
Reference
.label
NR

String

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Reset Node *¶

Label of the RESET_NODE action.
The type of Experiment Builder object
("ResetNode") the current node belongs to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the "Save Messages"
attribute of the Experiment node checked) when
the RESET_NODE action is done.
Display PC time (in milliseconds from the start
of the experiment) when this action is done.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the
node starts (the action is not done yet by this
time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
The node to be reset.

7.8.13

Playing Sound

Experiment Builder supports playing .WAV audio files using the PLAY_SOUND action
(
). Please make sure the target sound files are loaded into the library manager of the
experiment by clicking “Edit → Library Manager” from the application menu bar (see
Figure 7-22). The Library Manager dialog allows users to load in images, videos, sound
resources, and interest area set files. Select the “Sound” tab and click the “Add” button to
load in audio files, or select the audio files in Windows Explorer (Finder in Mac OS X)
and drag them into the Library Manager window. The name of the audio files to be
imported should not contain spaces or non-ASCII characters.

SR Research Experiment Builder User Manual

Please note that the playing of an audio clip in Experiment Builder is asynchronous (i.e.,
the action returns before the sound finishes playing). As a result, if a sound clip is played
at the end of a sequence (e.g., used as a feedback to the participant), users must attach a
timer following the play sound action to ensure that the whole sound clip will be played.

Figure 7-22. Adding Audio Files to the Library Manager.
In Windows, users may choose either the DirectX or ASIO audio driver to play the sound
files (chosen from the “Devices → Audio” settings; see Figure 7-23). The ASIO driver
supports predictable and low latency audio playback and recording, and is therefore ideal
for experiments that require high audio timing precision (e.g., with audio-visual
synchronization or an audio stimulus onset asynchrony manipulation). If using the ASIO
driver, make sure a sound card that supports the ASIO 2.0 specification is installed on the
computer(s) used for developing and running the experiment. In the device setting for the
ASIO driver (Figure 7-23, left panel), “ASIO Audio driver” indicates the name of the
ASIO driver. The “Output Interval” property returns the interval (in milliseconds)
between the ASIO buffer swaps, which determines how often new sounds can be output.
The “Minimum Output Latency” property indicates the minimum output latency of the
ASIO driver (delay from the buffer switch to first sample output).
In Mac OS X, the audio driver is set to "OSX". Similar to the ASIO driver, it schedules
audio events ahead of time to achieve a precise playing time. All audio clips scheduled

SR Research Experiment Builder User Manual

with a TIMER trigger with a duration longer than the “Minimum Scheduling Latency”
(which is about 40 ms) or played through the “Synchronize Audio” option of a
DISPLAY_SCREEN action will be played at the intended/scheduled time.

Figure 7-23. Choose Audio Driver.
The following table lists the properties of a PLAY_SOUND action.
Field
Label *

Attribute
Reference
.label

Type

Content

String

Label of the PLAY_SOUND Action. The
default value is “PLAY_SOUND”.
The type of Experiment Builder object
("PlaySound") the current node belongs to.
The absolute path of the node in the experiment
graph.
Message to be sent to the EDF file (in an
EyeLink experiment) or messages.txt (in a nonEyeLink experiment with the "Save Messages"
attribute of the Experiment node checked) when
the PLAY_SOUND action is executed.
Display PC time (in milliseconds from the start
of the experiment) when the PLAY_SOUND
action is done.
Display PC time (in milliseconds from the start
of the experiment) when the processing of the

Type #

Node Path #

.absPath

String

Message

.message

String

Time #

.time

Float

Start Time #

.startTime

Float

SR Research Experiment Builder User Manual

Clear Input
Queues †

.clearInputQueue
s

Boolea
n

Audio Device #

Sound File

.firstSoundFile

String

Volume

.firstVolume

Float

Playing #

.playing

Boolea
n

node starts (the sound playing has not started
yet by this time).
If true, all events from input queues are flushed
when the action starts. This includes all
Experiment Builder triggers, such as keyboard,
mouse, TTL, and EyeLink inputs (button,
saccade, fixation). This feature is designed to
ensure the software only evaluates the
upcoming triggers that occur after the start of
the action. If false, the input queues are not
cleared when the action is performed. This
means that events already in the queues may be
evaluated by the triggers following the action.
Indicates the current audio driver setting (either
DirectX or ASIO in Windows, or OS X in Mac
OS X). This field is neither editable nor
referable.
The name of the sound file. This is
automatically set to one of the sound files in the
library (“None” if no sound file is loaded in the
library).
Adjusts the volume of audio playing. Volume
ranges from 0.0 (muted) to 1.0 (full volume).
The default value is 1.0.
Whether the sound playing has begun and is in
progress. The possible values are “True” and
“False”. Returns “False” if sound playing hasn’t
started, if sound playing is paused (with DirectX
driver), or if sound playing is done.

Note: The following fields are specific to the ASIO driver only.
Balance
.firstPan
Float
Adjusts the balance of the sound buffer. Balance
ranges from -1.0 (left channel only) through 0.0
(left and right channels have equal volume) to
1.0 (right channel only). Balance works by
attenuating one of the channels: for example, at
a pan of 0.5 the right channel is at full volume
while the left channel is at a volume of 0.5. This
option is not available on Mac OS X.
Estimated
.estimatedPrepare Float
If the sound is scheduled enough in advance it
Prepare Time
Time
will play on time. The estimated time to prepare
for clip playing for guaranteed performance will
be the ASIO minimum output latency * 2.
Play Start
.playStartSample Integer The position within the buffer for the start of
Sample
play (samples from the beginning of the file
loaded into buffer; 0, beginning of the buffer).
In Windows, this option is only available when
using the ASIO driver.
Play End
.playEndSample
Integer The position within the buffer for the end of
Sample
play (samples from the beginning of the file

SR Research Experiment Builder User Manual

Play Start Time
#

.playStartTime

Float

Buffer Max
Samples #
Sample Count #

.bufferMaxSampl
es
.sampleCount

Integer

Is Mono #

.ismono

Sample Rate #

sampleRate

Boolea
n
Integer

Current Play
Position #
Current Sample
#

playPosition

Float

.currentSample

Integer

loaded into buffer; 0, end of the buffer). In
Windows, this option is only available when
using the ASIO driver.
Reports the Display PC time (in milliseconds
from the start of the experiment) at which the
first sample of a clip was played. This is set to 0
when the clip playing is scheduled. End of audio
play can be determined by a combination
of .playing (when it returns "False")
and .playStartTime attributes (when it returns a
value greater than 0).
Reports the maximum number of samples the
audio buffer allocated can hold.
Reports the actual sample count stored in the
buffer.
Reports whether the buffer contains mono or
stereo data.
Reports the sample rate (in samples per second)
of the buffer. All of the audio buffers have a
sample rate of either 48,000 or 24,000 samples
per second, chosen to be compatible with most
ASIO drivers.
Reports the current play position (time in
milliseconds from the start of the clip playing).
Reports the current sample being played.

When you run a project using the ASIO driver in Windows, a "Creative ASIO Control
Panel" dialog box will show up. This latency sets the minimum output latency of the
ASIO driver (delay from buffer switch to first sample output) and the interval (in
milliseconds) between ASIO buffer swaps (i.e., how often new sounds can be output).
For better ASIO playing/recording performance, set the ASIO buffer latency to 10 ms
(the default is 50 ms).

Figure 7-24. Setting ASIO Buffer Latency.

SR Research Experiment Builder User Manual

The synchronization of audio and visual presentations is critical in some experiments.
When the DirectX driver is used for playing an audio clip, the play sound action is done
as quickly as possible; however, no timing certainty should be expected when using this
audio driver. If using Windows to create and run an experiment requiring accurate audio
timing, the ASIO driver should be used. The ASIO driver creates two audio buffers for
each input or output channel. When producing sounds, one buffer is being played by the
sound card while the other buffer is being filled with sound data by Experiment Builder.
When the ASIO driver finishes playing its buffer, the application and driver buffers are
switched. This means that sounds are actually produced at a short (but highly predictable)
delay after the data is stored in the buffer. Since the Creative Labs sound cards we
recommended have a typical latency setting of 10 milliseconds, this would have a buffer
switch interval of 10 milliseconds and an output delay of 10 milliseconds. The time that
the clip was actually played will be accurately reported in the EDF file. When using an
ASIO driver:
•

If the start of a sound has been commanded far enough in advance of the time the
sound is to be played (e.g., the PLAY_SOUND action is preceded by a TIMER
trigger with a duration of greater than 20 ms), Experiment Builder will be able to
write the sound data in advance to the ASIO buffer and therefore the first sample
of the clip will be emitted from the sound card within 3 milliseconds (plus or
minus) of the scheduled time.

•

If the sound is commanded to happen as quickly as possible (e.g., for example in
response to a participant’s response, external signal, or eye movement event), or if
the sound play command was not given far enough in advance (e.g., the
PLAY_SOUND action is preceded by a TIMER with a duration shorter than 20
ms or is not preceded by a timer), Experiment Builder is unable to compensate for
system delays and the audio will begin after a short delay. However, the exact
moment that the sound will play is predictable and can be reported precisely for
analysis later.

•

Experiment Builder allows users to schedule the audio playback at a predictable
time relative to the visual stimulus presentation when the display screen and play
sound actions are separated by only a TIMER trigger. Experiment Builder also
allows users to play audio files directly from the DISPLAY_SCREEN action by
enabling the "Synchronize Audio" check box. Users then specify the clip to be
played and the time offset relative to the display onset (a negative offset value
means the audio clip will be played before the visual stimulus, and a positive
offset means the visual information will be presented earlier). A PLAY_SOUND
action is not necessary if the audio playing is scheduled through the “Synchroniz
e Audio” option of the DISPLAY_SCREEN action. You may check out one
example in the .CHM version of this document (section “Installation → Windows
PC System Requirements → ASIO Card Installation → Related → Using ASIO
Driver”). In Windows this option is only available if ASIO is selected as the
Audio Device.

SR Research Experiment Builder User Manual

Audio played with the ASIO driver will have messages automatically logged in the EDF
(EyeLink experiment) or message file (non-EyeLink experiment with the "Save
Messages" option enabled in the project node). The start time of audio playing is logged
with a "!V APLAYSTART" message and the end time is marked by a "!V APLAYSTOP
" message. Both messages have a negative time offset typically preceding this message.
•
•

Playing Starts: MSG < !V APLAYSTART>

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : No
Page Count                      : 408
PDF Version                     : 1.4
Title                           : EB_2.1.140C
Author                          : 
Subject                         : 
Producer                        : Mac OS X 10.11.6 Quartz PDFContext
Creator                         : Word
Create Date                     : 2017:11:08 16:50:04Z
Modify Date                     : 2017:11:08 16:50:04Z
Apple Keywords                  :

EXIF Metadata provided by EXIF.tools

Experiment Builder User Manual

Navigation menu

Versions of this User Manual:

Views

Navigation