Reading experiments with the EyeLink under Linux in K.12

Introduction

This page aims to give you a step-by-step guide to running your own readingVisual World Paradigm (VWP) experiment under Linux under Windows with the EyeLink 1000 in room K.12, booth 5. Technical details about this set-up can be found here on the facilities page. Baby EyeLink in room K.09. Technical details about this set-up can be found here on the facilities page. SMI RED250mobile eye tracker.

This page is always under construction. If you find mistakes or have things to add, please send them to Iris Mulders.

Recipe for a readingVisual World Paradigm (VWP) experiment

• Step 1. Before you start, you’ll need to learn about how we work in the lab, and about the equipment.
• Step 2. Create stimuli and implement your experiment.
• Step 3. Test your experiment in K.12in K.09on the SMI laptop.
  • Repeat steps 2 and 3 as necessary.
• Step 4. Calibration.
• Step 5. Pilot and prepare for subjects.
• Step 6. Convert your data.
• Step 7. Code your critical regions.
• Step 8. Clean up and code your data with Fixation (in K.06, or on your own PC).
• Step 9. Prepare your data for analysis

Step 1. Before you start

Support and opening hours

• Read the Introduction Guide to ILS Labs and follow all the steps there to create the user accounts etc that you will need.
• Contact Iris Mulders to discuss your experiment design, and for a tutorial on how to use the equipment.
• In the time period that you are working on your experiment, attend the eye-tracking lab user meetings.
• You can reserve the experimental booth cabin 5 the baby eye-tracking lab K.09 the SMI eyetracker and the experimental booth cabin 6 in the reservation system. Don’t block whole weeks, only reserve the timeslots that you will actually be in the lab. Please unreserve the timeslot if an appointment is canceled. In busy times, we will coordinate reservations in the eye-tracking lab user meetings.
• Always arrange precise pick-up times for the SMI with the lab technicians.
• For details on lab opening hours, see this page.
• Always report any problems to lab support immediately: go to room 0.09 on the first floor, or alert the support staff by email or phone.

Equipment: architecture of the set-up

In remote mode, the EyeLink 1000 system samples one eye at 500 HzThe SMI RED250mobile eye tracker samples both eyes at 250Hz, using infrared video based tracking technology. Freedom of movement is 32 x 21 cm at a 60 cm distance; gaze position accuracy is 0.4 degrees. For a full technical specification of the SMI RED250mobile, see their product flyer.

The EyeLink Host PC and the Stimulus PC communicate over a (crossover, orangered) ethernet cable using SR Research software.

Practicing camera setup and calibration

Step 4 outlines how to perform camera setup and calibration. Working with the equipment does require some instruction and practice; please read the information in Step 4, and contact Iris Mulders for a tutorial. Do this well before you are ready to start running your experiment!

Accessing scripts and data on other computers

The eye-tracking labThe SMI laptop is primarily meant for running experiments; you are expected to do some of your experiment preparation, and all of your data analysis, on other computers, outside the eye-tracking lab (for instance in our practicum room K.06, or at home). Use the ILS Labs data server to safely store your data, and to access your data on other computers.

Up to steps overview

Step 2. Create stimuli and implement your experiment.

Technical implementation

It is recommended that you create and try out a few stimulus materials on the actual setup you will use to run your experiment, before you move on to creating all your stimulus materials on other PCs. This way you can sort out all technical details, before creating all materials in a potentially ‘wrong’ way. Get help from Iris Mulders or Maarten Duijndam the first time you work in K.12in K.09on the SMI laptop. They will also give you some pointers on how to work with the equipment; all of that information is also detailed in Steps 3-5 below.

Implement your experiment

Start your experiment implementation on the SMI laptopthe Stimulus PC in K.12the Stimulus PC in K.09, logged in to the Kubuntu Operating System. Once you have figured out the technical issues, you can finalize your implementation elsewhere.

Download a boilerplate experiment

Make up a three-letter name for your experiment. (Note: in the analysis program Fixation, only the first three letters of your experiment name will survive.) Rename the experiment directory, and your ZEP script with this name:

data_file_format                = EYE_FILE_FORMAT_EYELINK_ASC;

Do a test run of the boilerplate experiment

To get a feeling for how the experiment looks and works, do the following:

Under Windows, double-click the file windows-terminal.bat in your experiment directory. In the DOS console that opens, type zep YOURTHREELETTEREXPERIMENTNAME.zpEnter.

In the ZEP control window that opens next, click the Start button to start the experiment. Follow the directions on the screen to continue.

If you want to try out the experiment without an eye tracker, choose the simulated eye-tracker. The mouse cursor will then simulate a gaze, and you can use it to get through the drift check (just hold the mouse/gaze over the drift check dot). If this doesn’t work, you can use the space bar to get through the drift check.

To abort ZEP at any time: press alt-F4 (prompts for confirmation) or ctrl-break (no confirmation).

Create your own stimulus file

Specify your stimuli in /YOURTHREELETTEREXPERIMENTNAME/stimuli/test_items.csv.

It may be helpful to consult this page about working with .csv files.

In the .csv file in the boilerplate experiment, each row beyond the header describes one trial (including a question, which is optional). The meaning of the columns is:

1. index This column determines in which list a stimulus will appear. If you have eg. four lists this column will have four indices. Indices start at zero, hence there will be a number of 0, 1, 2 or 3’s in this column. Stimuli with index 0 will appear in the first list, indices 2 in the third etc. NB1: ZEP uses the participant’s group number to control which list the participant sees. A participant with GRP1 will get list 0, a participant with GRP2 will get list 1, etc. Specify the names for your groups in the file YOURTHREELETTEREXPERIMENTNAME/modules/grouping.zm. NB2: The .csv file for the practice items doesn’t have this index, as the stimuli in the practice block are displayed in the order specified in the .csv file (no pseudorandomization).
2. id This is the item number of the trial. Use three digits for the item numbers (001, 002 etc). Excel/OpenOffice/LibreOffice will ‘helpfully’ try to delete the leading zeros in your item numbers (it will change ‘001’ to ‘1’); to prevent this, format the column as text. (The item number needs to have three positions for the data processing in the analysis phase.) Of course, make sure that the combination of item number and condition is unique for all items.
3. type This column refers to the experimental condition of the stimulus. The entered value has to correspond to the values in the /YOURTHREELETTEREXPERIMENTNAME/test/stimuli.zm file (note that it is case senstive). Specifically they should match one of the values in the enum ItemType. In the boilerplate experiments, the conditions are PRAC, FILL, CNDA, CNDB, CNDC, CNDD – which map to practice, filler, condition A, B, C and D respectively. Make sure to rename the conditions to names that make sense to you, so that you’ll know what each condition is in the analysis phase. Remember: use NO numbers, and use five letters maximum(four if you measure eye movements on question pages, as question pages will be prefixed with a Q thus taking up one letter space)!
4. image_filename Specifies the file name for the visual stimulus.
5. sound_filename Specifies the file name for the auditory stimulus.
6. expected_answer Set this variable to true if the expected answer to the question is correct, false otherwise.
7. record_eye_movements Set to true if the eyetracker should record the eye movements in this item, false otherwise. Set to true for all experimental items, false for fillers.
8. do_drift_check Set to true if the trial should be started with a drift check, false otherwise. Is usually set to true.
9. text Here the text for the stimulus is written (see Stimulus formatting below).
10. driftchk Set to true if the trial should be started with a drift check, false otherwise. Is usually set to true.
11. receye Set to true when the eye movements should be recorded for the text. Set to true for experimental items, false for fillers.
12. qtext The question that belongs to this trial.
13. qdriftcheck Set to true when the question should be preceded with a drift check, false if not. You will usually set this to false for all trials (unless you are measuring eye movements on the questions, of course).
14. qreceye Set to true when the eye movements should be recorded for the question.
15. qanswer Set this variable to true if the expected answer to the question is correct, false otherwise.

Specify your practise items in stimuli/prac_items.csv.

Specify the pseudo-randomization of your items

Out of the box, the boilerplate experiment will present your experimental stimuli in a different pseudo-randomized order for each participant. The pseudo-randomization follows the constraints specified in /test/shuffle.zm. In the boilerplate experiment the following constraints are specified: no more than three experimental items may appear in a row, no more than two experimental items in the same condition may follow each other, and the first trial must always be a filler.

You can adapt the constraints in /test/shuffle.zm to your own needs. If you need help to implement your ordering constraints, ask Maarten Duijndam.

Your practise items will always simply be displayed in the order you specify in stimuli/prac_items.csv.

No pseudo-randomization

if (shuffle_test_items(selected_group) != OK) 
    terminate;

// if (shuffle_test_items(selected_group) != OK) 
//     terminate;

if(test::shuffle_stimuli(selected_group) == ERROR)
    return ERROR;

// if(test::shuffle_stimuli(selected_group) == ERROR)
//     return ERROR;

Now specify the stimuli in the desired order in the /stimuli/test_items.csv file and make sure they have the right list number. So if your .csv file looks something like this:

index;id;type;
0;001;FILL;...
1;001;FILL;...
2;001;FILL;...
3;001;FILL;...
0;001;CNDA;...
1;001;CNDB;...
2;001;CNDC;...
3;001;CNDD;...
etc

Participants in group GRP1 will then always get FILL001 and CNDA001 in that order, group GRP2 will get FILL001 and CNDB001 in that order, etc.

Language

You can set the language in which the experiment communicates with the participant (the welcome screen etc) by importing the appropriate module (language modules are for instance std_texts_cn.zm for Chinese, std_texts_nl.zm for Dutch). To import a module, in your .zp script file, search for import to see how it’s done.

If you want to change anything in a language module (for instance, change yes/no as answer options to correct/incorrect), copy the module from the module directory of the ZEP installation directory to the module directory of your own experiment and make the changes in that copy. In the lab under Linux the ZEP module directory is usr/share/zep/2.5/modulesIn the lab setups under Windows the ZEP module directory is C:\Program Files (x86)\zep\1.14\modules; if you are working on your own PC, it depends on where you installed ZEP of course, and which version of zep you are using.

Preparing/finishing stimulus files under Windows

Here are some known issues with preparing stimulus files under Windows:

• DO NOT use Microsoft Word or Wordpad to prepare your files; use a proper text editor instead, such as Notepad, Notepad++, or TextPad.
• Your files need to have DOS/Windows line breaks, and the character encoding has to be UTF-8.
  • TextPad gives you usable files if you save them using File -> Save as -> File format: PC, and Encoding: UTF-8.
  • To set the default encoding in Notepad++: go to Settings -> Preferences -> New Document/Default Directory, and select UTF-8 as the encoding, and ‘Windows’ as the Format. To fix a wrongly encoded file, go to Encoding -> Ansi and save.
  • Notepad will give you useable files if you use ‘save as’ and specify UTF-8 as the font encoding.

For preparing stimulus .csv files, you can also use Excel, OpenOffice, or LibreOffice Calc under Windows, but this is usually an extremely frustrating endeavor, as explained above, and in this page about working with .csv files. Better to work in a text editor, especially if your stimulus file is nearing completion.

Back to Step 1. Before you start
Up to steps overview

Step 3. Test your experiment in K.12in K.09on the SMI laptop

Switch on the equipment

Monitors

During the experiment, you can press F5 to see the stimulus together with the participant gaze, in the ZEP control window on the experimenter monitor.

Back to Step 2. Prepare your experiment
Up to steps overview

Step 4. Calibration

This section outlines how to perform camera setup and calibration in the context of our lab.

Working with the equipment does require some instruction and practice; please read the information in this section, and contact Maarten Duijndam or Iris Mulders for a tutorial.

Starting the experiment software

1. Start your experiment in ZEP.
2. NB: if you have been moving your experiment between Windows and Linux, it may happen that the executable bit on the file linux-terminal.sh is lost, in which case the system will simply open the file in a text editor instead of offering to run it in the terminal. If that happens, right-click the linux-terminal.sh file in the window manager, go to ‘Properties’, ‘Permissions’, and check the box ‘Is executable’: Then try again.
3. Press the ‘Experiment’ button and change the experiment status to ‘piloting’ or ‘testing’, depending.
4. Create a participant and select it. The participant ID has to have the format ‘pp###’, for instance pp001, pp002 etc. (Do use exactly this format, otherwise you’ll run into problems when you have to convert your data later on in the process).
5. Press ‘Start’ to start the experiment. At the Welcome screen, press the space bar to advance to the next screen.
6. You will get to a screen with the following options:
   

   ZEP Connect to Eyetracker Menu

7. Press L to connect to the SMI eyetracker. A box will appear on the screen with a representation of the eyes. (Drag this to the external left screen if you are using it).
8. You will get to a screen with the following options:
   

   ZEP Connect to Eyetracker Menu

9. Press L to connect to the EyeLink eyetracker.
10. Follow the instructions on the screen, until you see a screen that looks like this:
    

    ZEP Eye-tracking Menu

11. Press Enter to go to the ZEP camera setup menu.

Camera setup and calibration

When your experiment script opens the connection to the EyeLink Host PC, you will see the following screen appear on the EyeLink Host PC:

EL1000 setup screen

This screen gives an overview of the options that are available to you at this point (setting up the camera image, calibrating, validating etc.).

In principle you can operate the software from the EyeLink Host PC keyboard by either clicking on the function you need with the mouse, or by using the corresponding keyboard shortcuts (for instance, press c to enter the calibration routine). However, when you are running an experiment using ZEP or any other experiment program, it is advisable to control the communication with the eye tracker through the experiment program, using either the Stimulus PC keyboard in the control room, or in the participant room. The commands that are not implemented (such as pupil threshold adjustment) can be done with the mouse directly to the EyeLink Host PC, but things like starting calibrations are best done through the experiment/display software, to prevent miscommunications between the EyeLink Host PC software and ZEP.

When the ZEP script reaches the camera setup part, on the Display monitor in the booth you will just see the ZEP camera setup screen.

The ZEP camera setup screen indicates the keys corresponding to the menu options that are available to you at this point:

• Enter will take you to the views of the camera image
• c will take you to the calibration screen
• v will take you to the validation screen
• d will perform a drift check (you won’t need to manually invoke this option)
• Esc will take you out of the camera setup menu, back up to the eye-tracking menu

To start the setup procedure, press Enter to see one of the camera views (head view, eye close-up, target sticker close-up). Pressing the left or right cursor key will switch between camera views. Press one of these cursor keys to switch to the head view.

Place a target sticker on the participant’s forehead, somewhat off to the right (see image above). Adjust the height of the participant chair so that the participant’s eyes are level with the top half of the monitor. The seat can be moved up by pumping the foot pedal, and down by stepping on the pedal (push through). If necessary you can slightly tilt the camera mount to make the eye appear vertically in the middle of the overview camera image, or adjust the book stack under it to move it up/down. Push the chair close to the table to get about the right distance to the screen.

The system should now find the right eye and the target sticker automatically. A white cross will be drawn through both, and a green circle and a red box will appear around the right eye, and a green box around the target sticker. Focus the camera by turning the lens.

The participant should be positioned at about 600mm from the camera (anywhere between 550 and 650mm should work, but aim for 600mm as the optimal distance so that participants still have some room to move). Go to the control room and check the ‘DIST’ status message below the camera image on the EyeLink Host PC to see what the distance is.

Use the EyeLink Host PC mouse to click on the pupil of the participant in the overview camera image. This will line up the search boxes, and set the threshold for the pupil and corneal reflection. You’re looking to get an image where the pupil appears a solid dark blue with a green line drawn around it, and the CR (corneal reflection) in turquoise. Make the participant look at the corners of the screen to ensure you have a good image in all positions.

EL1000 eye image

When you have an acceptable image of the eye, press Esc to return to the menu, and c to open the calibration routine. The calibration routine consists of the timed presentation of thirteen points on the screen. Instruct the participant to look at the dot that appears in the middle of the screen, and press Enter; the thirteen calibration points will be presented on the screen in random order.

If there are problems with the camera setup, nothing will happen when you press Enter, or the system will seem to ‘get stuck’ at the presentation of a calibration point. If this happens, the EyeLink Host PC screen will probably tell you that the pupil is missing. In this case, press Esc to return to camera setup, and make adjustments there.

Things to check for in case of problems (in decreasing order of likelihood):

• Make sure the participant’s hair is not obscuring the target sticker. (Use our assortment of hair clips and headbands to keep the hair off the forehead).
• Check that the target sticker is not too close or too far away from the eye; if it is, EYEDIST will appear in red (see EyeLink User Manual).
• ANGLE error message: indicates that the target sticker is seen from too large an angle by the system. Check that the target sticker is not too far off to the side of the participant’s forehead, or too high up, in case the participant’s forehead slopes backwards. In the latter case, try to move the sticker closer to the eye then. (But not too close, if it’s too close you’ll get an EYEDIST error).
• Check the distance to the monitor. (DIST)
• You may need to turn down the lights. (The booth light switch has a dimmer; always close the booth door for calibration to get rid of disturbing lighting from the control room).
• If you see that one calibration point lies far outside the grid, this is usually caused by the camera being too far off to the side of the screen; if the camera films the eye from the side, a shadow will appear on one side of the iris that the system may confuse for part of the pupil in some angles. Usually the best image is obtained by having the camera straight in the middle of the monitor, and the participant’s face in the middle of the camera image.
• Another cause of one calibration point lying far outside the grid is the appearance of an extra corneal reflection in a certain position; you may see the crosshair for the CR reflection ‘jump’ (due to another CR reflection popping up in certain positions). Moving the participant a bit further away from the screen (no further than 700mm) usually helps. Setting the CR threshold value a bit lower may also help (click the arrows in the top left of the EyeLink control screen. You can also press the + or - key to control the CR threshold, but this does not always work during an experiment).
• The pupil threshold bias may be too high or too low. To adjust the threshold, click the arrows in the top left of the EyeLink control screen. You can also press the up or down arrow keys on the keyboard to adjust, but this does not always work during an experiment. Make sure you have a good solid image of the pupil, and that the pupil image doesn’t ‘merge’ with eyelashes or other dark parts of the image. Mascara may (but usually does not) interfere with the system finding the pupil. NB: adjusting the threshold manually is usually not necessary, and once you have adjusted the threshold manually, it can take about 30 seconds for the threshold adjustment to switch back to automatic.
• If the right eye is giving problems, you can try to measure the left eye instead: go to the EyeLink Host PC, and select which eye to measure by pressing E (toggles between left and right). Make sure to move the target sticker to a position over the left eye. If you do change over to measuring the left eye, don’t forget to change the setting back to the right eye for the next participant!

If the participant is wearing glasses:

• Adjust the infrared illumination level from 75% to 100%.
• Move the participant closer to the screen: distance around 550-600 mm. But not too close, because too close a distance may result in large drift during validation.
• Make sure the face of participant is straight in front of the camera. When the participant is wearing glasses, Eyelink data quality may be very sensitive to even slight angles between the face and the camera.
• If the reflection on the glasses is obscuring the pupil, or competing for the corneal reflection, you can try the following:
  • Measure the other eye. Toggle which eye is measured by pressing E in camera setup.
  • Instruct the participant to keep the chin up, then the extra reflection point is excluded from the search box. Again, the chin should not be moved up too much, because the system may report “Angle” on the target, which may effect data quality.
  • If you get reflections competing with the corneal reflection, you can adjust the size of the search limit box by pressing alt-arrow keys; its position can be adjusted with shift-arrow keys (these operations can only be performed from the EyeLink Host PC keyboard).

Once you have a stable image of the pupil, return to the calibration by pressing c.

Instruct the participant: during calibration the participant should fixate each point until it disappears, and keep her head as still as possible.

While the participant is doing the calibration, look at the image of her eye at the bottom left of the EyeLink Host PC screen, and check for the following aspects:

• Watch the pupil and the CR reflection to make sure they are solid at all angles and no unwanted competitors pop up.
• Make sure that the pupil and the target sticker stay neatly in the red box at the bottom of the screen.
• Check that the participant doesn’t look away too quickly from the calibration points.

You won’t have enough eyes to check for all these things at the same time; feel free to repeat the calibration procedure a few times.

Make sure to warn the participant if they move their eyes away from the target too quickly. Most first-time participants will want to look away too quickly and need to be explicitly trained to not do this; it is natural to want to look away as soon as they have seen the calibration point, but this behavior will mess up your calibration as well as cause the drift checks later to take longer than necessary, so take your time to train them and repeat calibration and validation if necessary after instructing them again. Tell them to just keep staring at the dot until it goes away.

Below are some illustrations of good and poor calibration results:

Examples of calibration results

If something goes wrong during your experiment

Some known issues; please do still report these issues if they happen to you!

• Sometimes the drift check page does not appear, and instead a blank page appears. Usually you can get out of this blank page by pressing Esc. If Esc doesn’t work, try to press F2 (brings the focus back to the control window) followed by Esc.
• Occasionally, the experiment will seem to ‘freeze’ after the drift check has been completed – it’ll look like the drift check went fine, but the experiment will not move on to the next trial. It’s not entirely clear why this happens. To get out of this frozen state, press Esc and do a recalibration.
• Occasionally the validation will show large offsets for all calibration points. The offset will be very similar for all points, and really large (like 4 degrees). Our currrent idea is that when this happens, the calibration somehow wasn’t saved via the ZEP program as it should be. To fix this, you can redo the calibration, and accept this calibration on the EyeLink host PC by using the mouse (click on ‘accept calibration’). Then it is saved and from our previous experience it won’t happen again so you can continue the normal flow. (Only accept a calibration result on the EyeLink Host PC in this situation! Generally it is not a good idea to operate the EyeLink directly from the EyeLink Host PC as this may confuse ZEP).
• Rare: when there are problems with the university network, ZEP may seem to freeze. If this happens, just waiting it out seems to be the best strategy. To avoid any network problems, run your experiment from the local disk rather than from the network drive.
• Flickering participant monitor: this will happen if the refresh rate is set to 60Hz. Ask lab support to change it back to 85Hz.
• Screen goes black during experiment: probably a display power management issue, the computer switches off the display to save power (when the only input the computer gets is button presses from the button box). The computers should be set up in such a way that this can’t happen, but sometimes stuff happens. Ask lab support to fix it.
• Error ‘Cannot connect to eyetracker’ – sometimes it helps to restart the system (both EyeLink Host PC and Stimulus PC).
• Disappearing crosshairs and circles: if you lose the green circle around the pupil, but the system is still measuring eye movements, you may be able to get the markings back by pressing ‘Crosshairs’ on the left in the EyeLink screen.
• Rare: the calibration may switch from a 13-point to a 9-point calibration. We don’t know what causes this, if you encounter this, please let us know.
• Extremely rare: the camera image may display in reverse (such that right is left and vice versa). Solution: quit the EyeLink software and restart it (type elcl at the prompt and press Enter).
• There used to be a known bug in ZEP that sometimes causes the calibration screen to be superposed over a trial that no eye movements are being measured on (a filler item). We think we’ve fixed this. If you encounter it anyway, please let us know!
• There used to be a known bug in the Linux graphical interface, that occasionally caused the whole operating system to shut down and return you to the login screen. In the eye-tracking experiments, this mostly seemed to happen at the transition between the practice block and the first test block, so no actual data was lost. We think this should be fixed in the Kubuntu version that we are running now, if you encounter it anyway, please let us know!
• Sometimes the SMI will lose the eyes completely. If that happens, try things like close and start up ZEP again, restart the iVNGRED Server, restart the whole computer, disconnect and reconnect the eyetracker.
• If the SMI is on for more than a few hours, it will give you only zeros as data points (so essentially it will stop measuring). The only known fix is to restart the iVNGRED Server. Right-click the icon in the serivices taskbar and restart it from there. Make sure to do this before every participant, to be on the safe side.

What to do if the experiment crashes/does extremely strange unexpected things, or if the operating system freezes/crashes:

• Let the participant know that there’s a technical problem. Don’t panic – the worst thing that can happen is that you’ll end up with no data for this participant, which is a pity but not the end of the world.
• Note in your experiment log at which trial the problem occurred. You can read off the trial item number and condition from the status line on the EyeLink Host PC (bottom of the screen), or off the ZEP control window.
• Decide on a course of action. If you’re still at the start of the experiment and the participant hasn’t seen any experimental trials yet, you’ll want to keep the participant there and restart the experiment. If the problem occurs further on in the experiment, the best course of action probably is to send the participant home (do pay/reward them and apologize as it’s not their fault).
• Copy the ZEP output that you see in the terminal, to a file and save it. It may contain important information for lab support to prevent the problem from occurring in the future.
• Restart the experiment if you want to, using the same participant number etc; the old data will not be overwritten because the new session will be saved to a new file.
• If ZEP wasn’t shut down properly, you will get a message that the database is locked. To unlock the database: make sure ZEP is not running, and run zepdbcheck -fix in the terminal. See the ZEP manual for more information.
• If you can’t get ZEP to shut down at all, try to kill ZEP from the command line: pkill zep. If that doesn’t work either, try pkill -9 zep.
• Please let lab support know what happened: go to room 0.09 on the first floor, or alert the support staff by email or phone. Be as specific as you can about what you were doing at the time of the crash.
• The .edf file from the failed run of the experiment will not be transferred to the Stimulus PC, since the transfer happens only at the end of the experiment. If you were almost at the end of the experiment, you may want to retrieve the .edf file for analysis, if so, ask lab support for help to do that, on the same day (note for support: this may involve running zepgetedf sessionnumber_blocknr, edfinfo).
• Ask lab support to run chkdsk on the EyeLink Host PC (to check the EyeLink Host PC for lost clusters etc).

Back to Step 3. Test your experiment in K.12in K.09on the SMI laptop
Up to steps overview

Step 5. Pilot and prepare for subjects

5.1 Generate helper files that you’ll need to read your data in in Fixation

To analyze your data in Fixation, you will need to generate .bmp screendumps of your stimuli:

5.2 Pilot your experiment

To make sure that you have done everything right, you need to pilot your experiment. Change the experiment status to ‘piloting’ in ZEP, and first run a technical pilot on yourself.

To ensure smooth running of your experiment in case of any network hiccups, run your experiment from the local disk rather than running it from the network drive; carefully follow the instructions in the howto Properly run a ZEP experiment. You will want to run all your ‘real’ participants locally. (for VWP experiments this is more crucial than for reading experiments though).

When that seems OK, run a behavioral pilot with some pilot subjects (ask for some friends’ help). Note: while you are running actual participants, you will want to make sure the red light outside K.07 is burning, to indicate to people outside that they need to be quiet and cannot barge in. The red light comes on when you switch on the light in the kitchen – the light in the experimenter room and in the participant room do not make the red light come on.

Observe the behavior of your pilot subjects and ask what they think of the experiment to gauge whether the task is done by your participants the way you expected.

Then go through all the steps below and look at the response data, the eye movement data, and the Fixation output to double-check all your codings. Do this for all your lists. Also check whether the randomization of your stimuli works as intended.

Double-checking everything before you actually run the experiment may seem time-consuming and tedious now, but it will save you time in the long run.

5.3 Find subjects

• Help with recruiting adult participants in the lab is available here.
• An instruction template for participants can be found in the General Repository. If you want to adapt the instructions in your experiment itself, do so in YOURTHREELETTEREXPERIMENTNAME.zp.
• A template sign-off list is also provided.
• In addition, the Resources provide a template letter for obtaining parental consent for school-age children.

If you have similar materials to add that may be useful for others, please let lab support know!

Back to Step 4. Calibration
Up to steps overview

Step 6. Convert and transport your data

Eye movement data

All necessary files will appear in the directory ~/YOURTHREELETTEREXPERIMENTNAME/data/YOURTHREELETTEREXPERIMENTNAME. This directory can be read in in Fixation. It consists of four subdirectories:

• /YOURTHREELETTEREXPERIMENTNAME/dat contains your data files: .edf files (raw data file, contains samples), and .asc files (slightly less raw data file, contains fixations and saccades)
• YOURTHREELETTEREXPERIMENTNAME/obt contains your .obt files (specifying where the wordsareas of interest in your experiment are on the page, plus additional info. See Step 7 below for how to generate .obt files for VWP experiments.
• /YOURTHREELETTEREXPERIMENTNAME/img contains your .bmp files (the screendumps of the pages in your experiment that you generated in step 5.1 above).
• /YOURTHREELETTEREXPERIMENTNAME/result is empty, but provides a place for the result files you will generate in Fixation

Response data

Go to the YOURTHREELETTEREXPERIMENTNAME ZEP directory (so the higher instance, not the one inside YOURTHREELETTEREXPERIMENTNAME/data), and run zepdbextract in the terminal. This will generate a file YOURTHREELETTEREXPERIMENTNAME-1-1.csv in your experiment directory. In this file, you find all your subject’s responses (response, response time), and the order in which the trials were presented. Analyze as you see fit.

When you’re done for the day

Transport your data to a computer where you can run Fixation

Use the ILS Labs data server to access your data on a different PC. Working in Fixation will be much faster if you copy your data to a local directory. If you want to use Fixation in K.06, copy your entire experiment data directory to D:\eyetrack\data. (Just copy the directory carrying YOURTHREELETTEREXPERIMENTNAME that has dat, img, obt and resultdat, img, obt, result, tim and wav as immediate subdirectories – NOT your whole ZEP directory!) Don’t forget to upload the result files to the data server when you are done for the day – in K.06 your data can be deleted from the local disk D:\eyetrack\ by anyone!

Back to Step 5. Pilot and prepare for subjects
Up to steps overview

Step 7. Code your critical regions

Your .obt files specify the positions on the screen of the words in your stimuli. They are the missing link between (the XY-coordinates of) your eye-movement data and your stimulus.

In this step, you’ll specify which words make up your critical regions. This is a semi-intelligent task that you’ll have to do by hand. Note: the instructions below instruct you to use TextPad to edit your .obt files. If you use different software, bear in mind that Fixation can only read .obt files that have UTF8 encoding and are space delimited, OR ANSI encoding + tab delimited. UTF8 + tab delimited cannot be read by Fixation.

• Open TextPad. If you’re working on your own PC, you can download TextPad here.
• Open your .obt files. You can read in all your .obt files at once. If you want to avoid character encoding issues (not critical), you can choose to open your .obt files in UTF-8 encoding:

Screenshot TextPad

The columns in the obt-files specify the following information about the words in your stimulus:

1. object (word)
2. object length (number of characters, without spaces)
3. object number in line
4. number of objects in line
5. line length
6. object number in text
7. line number
8. number of lines in the text
9. stimulus number
10. object x-coordinate (upper left corner)
11. object y-coordinate (upper left corner)
12. object x + object width (including spaces)
13. object y + object height
14. object code 1
15. object code 2

Column 14 is where you specify your regions.

Do NOT use the number zero to code any region – the code 0 is reserved for ‘unassigned’ fixations in Fixation.

Furthermore, make sure that you number your regions consecutively. Do not, for instance, give all your non-critical regions number a particular number, as this will mess up the aggregation algorithm. So you can do this: 1112233455, but not this: 1112233255.

You may have a region that is present in one condition but not in another, that is fine: you can have something like 11334455 in one condition and 11222334455 in another. So skipping a number altogether is fine.

Back to Step 6. Convert your data
Up to steps overview

Step 8. Clean up and code your data

The next step is to clean up and code your eye-movement data with Fixation. See the Fixation manual.

8.1 Practicalities

Fixation is already installed on the PCs in K.06 (in D:\eyetrack\programs). If you want to work at home, you can also download it from the General Repository page.

8.2 Data cleanup

Back to Step 7. Code your critical regions
Up to steps overview

Step 9. Prepare your data for analysis

A Python script is available for post processing the data. Here is what the script does:

• it solves the problem that Fixation does not calculate total fixation times for regions. The script processes all your .agc and .jnf files, and for each .agc file outputs an .act file which is your .agc with five extra columns:
  1. totfixdur: sum of ALL fixation durations in the region (including second, third… nth pass)
  2. totfixcnt: the number of fixations in 1
  3. NumFixQualNot0: the number of fixations in 1 that do not have Qual 0 (blinks/rejected fixations)
  4. totfixQual0dur: sum of all fixations in 1 that have Qual 0
  5. totfixQual0cnt: the number of fixations in 4
• it writes all your .act files to a single file (allACTFiles.txt) in your result directory, splitting up the planame into condition and item number (so that you get those into separate columns when you read the datafile(s) in in SPSS or R).
• it writes all your .ags files to a single file AllAGSFiles.txt in your result directory, splitting up the planame into condition and item number (so that you get those into separate columns when you read the datafile(s) in in Excel, R, or SPSS).

To run the scripts, once you have assigned all your fixationsevaluated and coded all your data in Fixation, go to one of the PCs in K.06.

• Make sure you have all and only the data files that you want to use in your result directory – no subdirectories with older/discarded data files, for instance, as the script will process these too.
• The files you need are the .ags files if you want to analyze sample data (you probably do), and .agc and .jnf if you want to analyze fixation data rather than sample data (could be useful and quick in some cases, maybe).
• The files you need are the .agc and .jnf files.
• Download the script: right-click this link, choose ‘Save as’, and save it in your result directory.
• Run the script by double-clicking it.
• Watch for errors – the scripts give some rudimentary error messages in the terminal if something doesn’t work as expected.
• Output is written to your result directory.

If you are working from home, rather than on a PC in K.06, you need to install Python 2 or 3. For some more help, for instance on running under Mac OS, see the help here. If something doesn’t work as expected, contact Iris Mulders.

For a full overview of the meaning of the columns in your final data files – allACTFiles.txt for aggregated fixation data and AllAGSFiles.txt for sample data – see the Fixation manual.

Back to Step 8. Clean up and code your data with Fixation
Up to steps overview