Sr Research Experiment Builder
The SR Research Experiment Builder SREB is a visual experiment creation tool for use by Psychologists and Neuroscientists. The SREB 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 the SR Research EyeLink® eye tracking system, the SREB provides seamless integration into the EyeLink hardware and software platform.
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. The flow of the experiment is achieved by connecting sequentially related components in the workspace in a flow diagram like fashion.
One of the important concepts in SR Research Experiment Builder is 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 sequence or sub-graph 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.
Creating EyeLink Experiments
To create an Experiment with SR Research Experiment Builder, the user needs to take the following the following steps:
Experiment Design
Building and Test-running Experiment
Deploying Experiment
Participant Data Set Randomization
Data Collection
Data Analysis
Following these, a set of files are generated so that the experiment can be run for data collection without relying on the Experiment Builder application. To illustrate the use of Experiment Builder, a very simple eye-tracking experiment can be shown which runs three blocks of four trials. In each trial, a single word is displayed in the centre of the screen.
Creating a New Experiment Session
Click on the Experiment Builder to start a new session. When the application starts:
Click on “File ï€Â New” on the application menu bar.
In the following “New Project” dialog box, enter “Simple” in the “Project Name” edit box.
Click on the button on the right end of the “Project Location” to browse to the directory where the experiment project should be saved. If you are manually entering the “Project Location” field, please make sure that the intended directory already exists.
Make sure that “EyeLink Experiment” box is checked for an EyeLink experiment.
Note: The user shouldn’t manually add or remove files in the experiment directory.
Configuring Experiment Preference Settings
After a new experiment session is created, the user needs to check whether the default display and screen preference settings are fine for the experiment to be created.
Select “Edit ï€Â Preferences” from the application menu bar or press the “F4” key.
Click on “Preferences ï€Â Experiment ï€Â Devices ï€Â Display” to check display settings. Make sure that the settings (Width, Height, Bits per Pixel, and Refresh Rate) used are supported by your video card and monitor.
Click on “Preferences ï€Â Screen” to check Screen Builder settings. Set the Location Type as “Center Position”.
If any of the above settings have been changed and if you want to keep the new settings as defaults for all of your future experiments, click on the button “save properties as default”.
Creating Experiment Block Sequence
The first step is to add a block sequence for repeating blocks:
Click on the Experiment Tab in the Project Explorer Window to start.
Click on the “Action” Tab of component toolbox.
Select the “Sequence” node, hold down the left mouse button and drag it into the work area.
Place the mouse cursor on top of the “START” node; hold down the left mouse button while moving the mouse cursor on top of the “SEQUENCE” node. This makes the connection from the “START” node to “SEQUENCE” node. (Note: don’t make a single or double click on the START” node as this will select the node instead. If you have done so, place the mouse cursor on a blank area in the work space and make a single click there. Redo the current step again.)
Click on any blank area in the work window. Click the right mouse button and select “Arrange Layout” in the popup menu. This will re-arrange the nodes in a hierarchical fashion.
Click on the SEQUENCE node in the structure list to continue.
Editing Block Sequence
Next, one will need to edit the properties of the Block Sequence. This involves changing the “Label” of the sequence to make it more meaningful and changing the “iteration count” (total number of times a sequence must be executed) to the actual number of blocks to be tested.
Click on the value field of the “Label” property of the Sequence created. Write “BLOCK” in the text editor and press the ENTER key to finish.
Click on the “Iteration Count” value field and enter “3” as the total number of sequence loops.
In the experiment Work Space, double click on the Sequence object to continue.
In each block, one has to first give an instruction, perform a camera setup, calibration, and then run the trials (an example has been given below)
Click on the “Action” Tab of the component toolbox, select the “Display screen” action, hold down the left mouse button and drag the action into the work area.
Click on the “Trigger” Tab of the component toolbox, select the “Keyboard” trigger, hold down the left mouse button and drag the action into the work area.
Add an “EyeLink© Button” trigger to the work space.
Add a “Timer” trigger to the work space.
Click on the Timer trigger and set the duration to 20000 msec.
Click on the “Action” Tab of the component toolbox and add a “Camera Setup” action to the work space. Click on the action and set the “Background Color” to white (255, 255, 255).
Click on the “Action” Tab of toolbox and add a “Sequence” node to the work space. This will be our trial sequence.
Place the mouse cursor on top of the “START” node. Hold down the left mouse button while moving the mouse on top of the DISPLAY_SCREEN node. This makes the connection from the “start” node to the “DISPLAY_SCREEN” node.
Similarly, connect from “DISPLAY_SCREEN” to KEYBOARD, EL_BUTTON, TIMER triggers. Note that a number is added to these connections, indicating the evaluation order among the three trigger types.
Make the connection from the latter three triggers to the “EL_CAMERA_SETUP” node and from “EL_CAMERA_SETUP” to the SEQUENCE node.
Click at any blank area in the work window. Click the right mouse button and select “Arrange Layout” in the popup menu. This will re-arrange the nodes in an orderly fashion.
Double click on the “DISPLAY_SCREEN” object in the work space (not from the structure list) until the Screen Builder interfaces displayed in the Graph Editor Window.
Creating Instruction Screen
The user may want to provide instruction to the participants at the beginning of the experiment. This can be done by creating an image file containing the experiment instructions and then using DISPLAY_SCREEN action to show the image. The instruction text can also be created with the multiline text resource. In the current example, multiline text resource text source is used.
Click on the multiline text resource button on the screen builder toolbar to select the type of resource to be added.
Click anywhere on the screen.
In the following Multiline Text Resource Editor:
Enter the instruction text.
Press CTRL + A to select all text entered.
Click the “Margins” button box to set the text margins. Enter 100 (or desired value) in all fields. Click the “OK” button on the dialog box.
Make sure that the text is still selected. Now click the buttons on the toolbar to set the desired text appearance (font name, font size, font style, alignment style, line spacing, and text colour).
Click on the “Close” button at the top right corner of the dialog to finish.
To work with images instead of texts:
The image resource is flexible enough to accommodate various modes of displaying (e.g., original image size vs. stretched, top-left aligned or centred). The following discusses the option of displaying images in original size or stretching it to a specific dimension.
To display the image in original size, after the image is added to the display, the user should have “Use Original Size” field of the image checked. Please note that, enabling that field will also make several attributes read-only (“Width”, “Height”, “Clipping Location”, “Clipping Width”, “Clipping Height”, and “Clipping Area is Gaze Contingent”).
To stretch all images to a fixed width and height (1024 Ã- 768 for example), after the image is added to the display, the user should first make sure that the “Use Original Size” field is unchecked. Check the values of “Width” and “Height” fields of sample image added and adjust them if necessary. In addition, the user may need to check the values of “Clipping Location”, “Clipping Width” and “Clipping Height” attributes, which are used to control the part of the image to be shown. By default, the clipping width and height are the same as the image width and height. Please note that the clipping location is always top-left based and the location is relative to the top-left corner of the image.
If images are stretched to different dimensions, the user should add two columns in the experiment data source to specify the desired image width and height. After the sample image is added to the display, the user should refer the width, height, clip width, and clip height of the image to the two columns created in the data source.
Editing Trial Sequence: Data Source
Next, one will have to work on the sequence, which will contain all necessary triggers and actions in each trial. One would also have to create a data source to be used for setting parameters in individual trials.
Click on the last “SEQUENCE” node on the structure list to start.
In the property table, click on the value field of “LABEL”. Set it to “TRIAL”.
Click on the “Data Source” property to bring up Data Source Editor.
Click on the “Add Column” button. In the following dialog box, type “Trial” (without quotation marks) in the Column Name editor box and set Column type as “Number”. Click “OK” button to finish. Click on the “Add Column” button again. Set the Column Name as “Word” and Column type as “String”. Click “OK” button to finish.
Click on the “Add Row” button. Enter the desired number (here 12) in the “Number of Rows” edit box to generate the number of rows of empty cells (here 12).
Click on the empty cells of the table just generated. For this example, the values of the “Trial” column are set as 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, and 12. For the “word” column, the following strings have been used: “One”, “Two”, “Three”, “Four”, till “Twelve”.
Click on the “Split by” value field. Enter a value (here [4]. This makes sure that only 4 trials are run in each block.)
Double click on the “TRIAL” sequence node in the structure list. Click on Start node under it to continue.
Editing Trial Sequence: Preparing Sequence and Drift Correction
Each recording trial should begin with a prepare sequence action, followed by a drift correction action, and then by the actual trial recording. The prepare sequence action allows the user to preload the image files or audio clips for real-time image drawing or sound playing, to draw feedback graphics on the Host PC to evaluate participants’ performance, and to reinitialize trigger settings. The user should typically call this action before performing a drift correction.
Click on the “Action” Tab of the component toolbox, select the “Prepare Sequence” action, hold down the left mouse button and drag the action into the work space.
Click on the added PREPARE SEQUENCE action and review the settings in the property table. Make sure to check “Draw To EyeLink Host” field is set to “IMAGE” or “PRIMITIVE”. This will draw image or simple graphics on the host screen for the purpose of evaluating gaze accuracy.
Add a “Drift Correction” action from the action tab of the component toolbox.
Click on the “Action” Tab of toolbox, select the “Sequence” node, hold down the left mouse button and drag it into the work space.
Make a connection from the “START” node to “PREPARE_SEQUENCE”, from “PREPARE_SEQUENCE” to “DRIFT_CORRECTION”, and from “DRIFT_CORRECT” to the “SEQUENCE” node.
Click on any blank area in the Work Space. Click the right mouse button and select “Arrange Layout” in the popup menu to re-arrange the nodes in an orderly fashion.
Double click on the newly created sequence to fill in the actual events in the recording.
Editing Recording Sequence
In a simple recording sequence, one has to display a screen and then wait for a button press response from the participant. The trial times out automatically if no response is made within a user specified time interval in seconds. The display screen is then cleared.
Select the newly added “Sequence” node. Rename the label as “RECORDING”.
Make sure that the “Record” and “Is Real time” checkboxes are checked. Double click on the “RECORDING” node in the structure list until seeing a “START” node under it. As we double click on the “START” node, the content of the work area window is also updated.
Click on the “Action” Tab of the component toolbox, select the “display screen” action, hold down the left mouse button and drag the action into the work area.
Click on the “Triggers” Tab of toolbox, select the “TIMER” node, hold down the left mouse button and drag the trigger into the work space. Double click on the Timer object. Enter “Time out” (without quote) in the “Message” value field and 10000 (time in ms) in the “duration” field.
Add an “EyeLink© Button” trigger.
Add another “display screen” action. Double click on the action and modify its label as “DISPLAY_BLANK”. Also uncheck the “Send EyeLink DV Message” box.
Make a connection from the “START” node to “DISPLAY_SCREEN”, from “DISPLAY_SCREEN” to “TIMER”, from “DISPLAY_SCREEN” to “EL_BUTTON”, from “TIMER” to “DISPLAY_BLANK” and from “EL_BUTTON” to “DISPLAY_BLANK”.
Click at any blank area in the work space, then click the right mouse button and select “Layout …” in the popup menu. Click ok in the following dialog box. This will re-arrange the nodes in an orderly fashion.
Modifying Properties of Display Screen
One must first need to check the property settings of the display screen actions. For better Data Viewer integration and for reaction time calculation, a message should be written to the EDF file to indicate the time when the stimulus was visible to the participants. In addition, one may need to draw simple graphics onto the host screen so that the participants’ gaze accuracy during recording can be evaluated.
Click on the DISPLAY_SCREEN node. In the property window of the action, double click on the value field of “Message” property. Type in “SYNCTIME” and then press ENTER key to register the change.
Make sure that the “Send EyeLink© DV Messages” and “Use for Host Display” properties are checked.
Select the “DISPLAY_BLANK” action. Double click on the value field of “Message” property. Type in “blank_screen” and then press ENTER key to register the change.
Make sure that both “Send EyeLink© DV Messages” and “Use for Host Display” checkboxes for the “DISPLAY_BLANK” action is unchecked.
Creating Display Screen
In here, one has to add a text resource to the display screen and modify the properties of the text resource, such as font name, size, text to be displayed, and alignment style. One also must have to create an interest area for the text. To do this, first double click on the “DISPLAY_SCREEN” object in the work space, until the screen builder interface is displayed in the Graph Editor Window.
Click on the “Insert Text Resource” button on the Screen Builder tool bar, and click at any position in the work area.
Double click on the current value of Font Name (“New Times Roman”). This will bring up a dropdown list. Set the new font name as “Arial” (or any other).
Double click on the current value of Font Size (20). Enter the desired text size (40) in the text editor.
Double click on the far right end of the value field of the “Text” property. This will bring up an attribute editor dialog.
Click on DataSource node under “TRIAL” sequence on the node selection list.
Double click on the “word” node in the node attributes window. This will update the contents of “Attribute” editor dialog as “@”.
Click on the “OK” button to finish.
Check the “Use Runtime Word Segment” box. This will create interest area automatically for the text used.
Select the newly added text resource, click on both “Horizontal Center Alignment” and “Vertical Center Alignment” buttons to place the text in the center of the screen.
Select the text resource on the work area, click the right mouse button, and select the “Lock Selection” option so that the resource will not be moved accidentally.
Writing Trial ID to EDF file
A “TRIALID” message should be written to the EDF file so that the actual experiment condition under which the trial was conducted can be identified during analysis.
Click on the Experiment (the topmost) node in the structure list to start.
In the property table, click on the value field of the “EyeLink© DV Variables” property.
In the following dialog box, for each of the variables to be added to the trial ID message, select the variable and click the “ADD” button. The order of the selected variables can be modified with the “Move up” and “Move down” buttons.
Click on “OK” to finish.
Showing Experiment Progress Message on Tracker Screen
During trial recording, a text message can be displayed at the bottom of the tracker screen so that the experimenter can be informed of the experiment progress. For example, in this experiment, a text message like “Trial 1/12 One” on the tracker screen was shown.
Click on the “Recording” sequence node in the structure list to start.
In the property panel, click on the far right end of the value field of the “EyeLink© Record Status Message” property.
In the attribute editor, enter an equation as:
=”Trial ” + str(@) + “/12 ” +str(@)
Click on the “OK” button to finish.
Building the Experiment
Click on “Experiment ï€Â Build” menu to build the experiment. The Editor Selection Tab in the Graph Editor Window will be set to the “Output” tab and build information will be displayed. Watch out for error (displayed in red) and warning (in brown) messages during building.
The following is a list of common errors during experiment building:
Image file not found
No positions are added to the custom pattern
Use of runtime value with pre-build to image option on
No value is set at row… for the column…
The node could not be used in the sequence
Reference to… not found in the graph.
No link from node.
Infinite loop found
Invalid Reference.
No recording sequence found in an EyeLink© experiment.
The following is a list of common warnings during experiment building:
The keyboard trigger and mouse trigger is used in a real-time sequence. If this is the case, check whether these two triggers are indispensable for the experiment design. If so, uncheck the “Is Real-time” box in the recording sequence.
Default value use in attribute …
The user may also test the experiment by clicking on “Experiment ï€Â Run” from the application menu-bar. This will try to connect to the tracker PC and execute the experiment code. It should be noted that this should only be used for the purpose of testing and debugging experiment code. To collect experiment data, the user should use the deployed version of the experiment as it does not have to rely on the Experiment Builder application and can be run on a different computer.
Deploying the Experiment
After the experiment is built, the user must “deploy” the experiment to a new. 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. If a data source is used, this will create a “datasets” subdirectory with a copy of data set file in it. The user can create several copies of data set files with the randomizer application
Running the Experiment
To run the experiment, open the directory where the experiment is deployed to and click on “<filename>.exe”. If the EyeLink© host application is already running on the Host PC and the Ethernet connection and settings between the host and Display PCs are ok, the experiment should now start. This will first popup a dialog box asking for the data source file. Go to the “datasets” directory and select the target data source file. Following this, enter the desired EDF file name (must be in DOS 8.3 format) and click on the “OK” button to continue. Following the initial welcome message, the participant will be shown the camera setup and calibration screen and the recording can be started following calibration, validation, and drift correction. After the experiment has ended; an EDF file will be transferred to the Display PC. It may take some time to complete the file transfer.
Possible Errors
Error in Initializing Graphics: When you start the experiment and see an “Error Initializing Graphics” error, please check whether the display settings (screen resolution, colour bits, and refresh rate) specified for the experiment are supported by your video card. If not, please change the “Preferences → Experiment → Devices → Display” settings.
Error in Tracker Version: SR Research Experiment Builder works well with both EyeLink and EyeLink II eye trackers. The default tracker version is set to EyeLink II (see “Preferences → Experiment → Devices → EyeLink”). Therefore, EyeLink I users may see such an error message with the default tracker setting. If this is the case, please set the tracker-version in the device settings to “EyeLink I”.
Participant Data Set Randomization
In most experiments, the user will need 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 the user may use the internal randomizer to perform randomization unless counterbalancing or Latin-square designs are needed. The 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.
Data Collection
Data can now be collected from the deployed version of the experiment. Double click on 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, a dialog will be displayed, allowing the user to choose the appropriate data source file. In an EyeLink© Experiment, the user will also be asked to enter the experiment session name. At the End of experiment, an EDF file will be generated for EyeLink© recording session and saved in the experiment directory. Optional result file(s) will be created if the user has specified them in EyeLink© and non-EyeLink© experiments.
Data Analysis
EyeLink© recording file can be conveniently analyzed with EyeLink© Data Viewer as the 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. The user can also specify trial variables, create interest areas, and send messages for the ease of data analysis. The result file(s) from a non-EyeLink© recording session contains columnar outputs for selected variables in the experiment. This file can be easily loaded by common statistics packages.