Logo Utrecht University

UiL OTS Labs

How-tos

Fixation manual

Last updated on 5 July 2018 by Iris Mulders

If you have suggestions on how to improve this document, or find mistakes, please send them to labman.gw@nulluu.nl

Introduction

Fixation gives you the ‘missing link’ between stimuli and eye-movement data. It shows the stimuli in the order in which they were presented in the experiment, and superposes the fixations over the stimulus. Objects (areas of interest) are displayed as well.

The Fixation program can be used to analyze textual stimuli (reading experiments), and for the analysis of so-called ‘visual world paradigm’ (VWP) studies, where an auditory stimulus is presented during presentation of a visual stimulus.

The program was created by (the wonderful) Rein Cozijn who generously allows us to use it as long as we do not distribute it further; do not bug Rein with questions or comments, send them to Iris Mulders instead.

This synoptic manual covers the following topics:

  1. Input files: What files you need and where to put them
  2. Working in Fixation: Some hints and tips, and an explanation of what Fixation does
  3. Known bugs/troubleshooting
  4. Units

Input files

Keep your input files organized in one experiment folder with the following six subdirectories:

  • \dat: Contains the eye movement data files (*.asc).
  • \img: Contains your visual stimuli in *.bmp format.
  • \obt: Contains your object files (*.obt), in which you specify the content of your areas of interest in the visual stimulus. <insert meaning of columns in obt here>
  • \result: Contains the Fixation output files.
  • \tim: contains timing files (*.tim): files in Praat Textgrid format that flag the onset of relevant regions in your auditory stimulus (only relevant for VWP experiments)
  • Audio files (*.wav): your auditory stimuli (you don’t strictly need these files for the analysis but it can be handy to let Fixation play them as a reminder) (only relevant for VWP experiments)

Working in Fixation

  • Specify the settings for your experiment under Settings -> Edit, or by clicking the third icon from the left in the toolbar. Here you can specify:
    • the types of output files you want to obtain (tab ‘General’). Checking ‘Variablenames in output’ gives you a header row in your output files, specifying the meaning of the columns.
    • where the input and output files can be found or will be saved: tab ‘Directories’. Make sure to specify the path to all input files, even if they are not present (*.tim and *.wav). If you don’t, Fixation will choke and give an error ‘I/O error 6’.
    • You can specify whether you want the program to read in a join file (*.jnf) – if you check that setting, the work you did last time you worked on a file will be loaded, so this is the recommended setting. Choose Settings -> Edit, tab Directories, click the checkbox ‘Load result file data (*.jnf) if available’.
    • color settings for the objects (words): tab ‘Objects’.
    • color settings for the fixations: tab ‘Fixations’.
  • Assign a fixation to an object using the mouse: right-click the fixation and drag it to the desired object. (The mouse pointer will change to a rectangle when you move the mouse outside the fixation’s system-assigned object). To move all the fixations in a trial at once: hold shift, right-click and drag, release mouse button, then release shift. (To undo this, press the ‘reset fixations shift’ button, top right, looks like a cross with arrows pointing to the middle).
  • Assign a fixation to an object using the keyboard:
    • Select a fixation and an object, and press ctrl-a. Unassign by pressing ctrl-u.
    • To select a fixation: you can ‘walk through’ the fixations by using the cursor arrows. You can also select a fixation by left-clicking it. The default color for a selected fixation is green. To select an object, hold shift and press cursor arrows. The default color for a selected object is teal.
  • Reject a fixation by selecting it and pressing r. Accept by pressing a.
  • A rejected fixation will still show up in the output files, but its ‘Qual’ variables will have a value of 8 or higher (so you can exclude the rejected fixations in your final analysis). See below under output files. Note that rejected fixations lead to invalid aggregation values (see below for details). Un-assign rejected fixations.
  • Un-assign a fixation by right-clicking it and dragging it outside the objects, or by pressing ctrl-u. The fixation will show up in the *.jnf output file with all values from the column ‘Mark’ onwards (see below) set to zero. In the *.agc everything from the sixth column (=code/region) will have the value 0.

NOTE:

  1. Rejected fixations lead to invalid aggregation values. Use a rejection marking to later exclude a whole region containing the rejected fixation from your analysis. Rejection serves no other purpose.
  2. Aggregation is performed only on assigned fixations. Unassigned fixations are treated as if they never happened.
  3. To avoid messing up of the incremental aggregation algorithm, it is advised, during the analysis of stimuli, to un-assign, or properly assign, rejected fixations and blinks that fall within regions or objects following the region to which they ‘belong’. For instance, if a blink falls in object number 25 but you believe it belongs to object number 10, unassign it (or assign it to object 10). If it would not be un- or re-assigned, the algorithm would take it as the starting point of a new aggregation value, and furthermore, would consider all intermediate objects to be processed on second pass.
  4. If the quality of a total first gaze value is 2 (blink in the middle), this means that somewhere between start and end a blink has occurred. This value also reflects blinks occurring at the moment of leaving a region regressively (when the subject returns back to that region later), or of re-entering a region.

The analysis performed by Fixation consists of:

  • Linking fixations to objects.
    • Automatic linking: A fixation is linked to an object if its xy-coordinates fall within the borders of an object. The left and top borders of the object are included and the right and bottom borders are excluded.
    • Manual linking: Once (automatically) linked, links can be changed manually.
  • When linking fixations to objects, the program calculates first and second passes, and the direction of fixations (progressive/regressive).
    • First pass: All fixations in an object where there are no preceding fixations that are assigned to a higher object.
    • Second pass: All other fixations.
    • Progressive fixations: A fixation is determined as progressive if it is linked to an object with a higher number than the object number of the previous fixation. If the current fixation falls within the same object as the previous one, the direction of the current fixation is determined by the difference between the xy-coordinates of the two fixations.
    • Regressive fixations: All other cases.
  • Determining return sweep: a return sweep is detected if a fixation falls within a higher object than the previous fixation and the object is on a new line. Return sweeps are progressive by definition.
  • Coding fixations (reject/accept).
  • Combining objects (words) into regions.

Bugs/troubleshooting

  • If you get the error ‘Cannot create form. No MDI forms are currently available’ when opening an .asc file, this can be solved by unchecking the ‘show splash screen’ box in the General settings tab. Save the settings and restart the program.
  • Error ‘There was an error in object file X.obt in line N! The objects have not been read.’ This is caused by unreadable stuff in the line N in your .obt file X. If you open the obt file, you’ll probably find that the offending line occurs at the end of the file, on an empty line, and there is a tab or a space there. Remove it, save the obt, and try again. Also, see here.
  • Error ‘I/O error 6’: you haven’t specified a path to the tim and wav input files (see above).
  • Error ‘Access violation at address….’ when saving a .jnf file you worked on before – one potential cause is that you threw away some .obt files after you last worked on the .jnf.
  • Made-up samples in .ags files: due to what is probably a small bug in Fixation, occasionally (quite rarely really), Fixation ‘makes up’ samples that didn’t actually happen (i.e. don’t appear in the .asc file). As far as I know, these made-up samples always appear at the end of a trial when they do show up. They show up with a strange character in the ‘event’ column (which may be displayed as ^@ depending on the program you’re using for display of the file), and ‘0’ in the samstart, qual, obtnr, code, code2, timcode and timstart variables. You can just delete these lines.
  • Error message ‘List index out of bounds’: some argument could be missing in the .asc file. For instance, there could be a line ‘<timestamp> wavfile ‘ not specifying the sound file.

Units

For all data acquired with an EyeLink or a Tobii, the temporal measures are in milliseconds, and the spatial measures are in pixels (measured from the top left of the screen).

Output files for reading experiments

Join file: *.jnf

List of fixations. Gives information about each fixation, including the word and region it belongs to.

Meaning of the variables in this file:

Variable name Meaning Comments
expname three-letter name of the experiment first three characters of *.asc filename
imgfile name of the image file *.bmp
timfile name of the *.tim file associated with this stimulus (which contains the segmentation in your audio file) this column is empty if experiment is a reading experiment (i.e. if there is no file that specifies regions in an accompanying sound file). This gets confusing if you read in the *.jnf in excel (the columns are separated by a single space, but excel counts the two spaces surrounding the empty ‘timfile’ column as one). Simply remove the cell ‘timfile’ in the header row in excel and you’re good to go.
blocknr block number list number (the characters between the first and second underscore of *.asc filename, if these characters are numbers; zero otherwise)
subjectnr subject number
pagenr page number experimental trial number (counts excluding fillers)
fixnr fixation number
X x-coordinate of the fixation
Y y-coordinate of the fixation
fixstart time start of the fixation
fixdur duration of the fixation
SaccInDur duration of the in-saccade in-saccade is the saccade preceding the fixation
SaccOutDur duration of the out-saccade
Qual quality of the fixation see here
Mark mark of the fixation see here
obtnr number of the fixated object in text-based stimuli, object = word
oldobtnr number of the old assigned object if changed during analysis
wlen wordlength number of characters
nwonl number of word on line
twonl total number of words on line
ncharl total number of characters on line
nwonp number of word on page
nline number of line on page
tlines total number of lines on page
pagenr page number trial number (counts including fillers)
left left coordinate of object/visual area of interest (x-value) the XY-coordinates of the visual area of interest is automatically defined (by FEP in our case) in reading experiments, and defined in mkobjects for VWP experiments
top top coordinate of object/visual area of interest (y-value)
right right coordinate of object/visual area of interest (x-value)
bottom bottom coordinate of object/visual area of interest (y-value)
code code of the object codes areas of interest/analysis regions; numbering has to be consecutive to ensure proper calculation of the measures, but not all codes have to exist in all items; value is 0 if a fixation was not assigned to any object
code2 second code of the object second code for area of interest in a picture stimulus; can be used in VWP experiments to code location in the picture (top left, center bottom etc)
timcode time code in *.wav file comes from “point” in .tim; irrelevant for reading experiments
timstart marks onset of auditory segment the fixation occurred in comes from “time” in .tim; irrelevant for reading experiments
timname name of the auditory segment the fixation occurred in comes from “mark” in .tim; irrelevant for reading experiments
shiftx number of pixels the fixation has been moved by in the x-direction during analysis/data cleanup
shifty number of pixels the fixation has been moved by in the y-direction during analysis/data cleanup

Aggregation file over regions: *.agc

List of coded regions. Meaning of the variables in the columns:

Variable name Meaning Comments
expname three-letter name of the experiment first three characters of *.asc filename
blocknr block number list number (the characters between the first and second underscore of *.asc filename, if these characters are numbers; zero otherwise)
subjectnr subject number
imgfile name of the image file *.bmp
pagenr page number experimental trial number (counts excluding fillers)
code code of the object codes areas of interest/analysis regions; numbering has to be consecutive to ensure proper calculation of the measures, but not all codes have to exist in all items; value is 0 if a fixation was not assigned to any object
code2 second code of the object second code for area of interest in a picture stimulus; can be used in VWP experiments to code location in the picture (top left, center bottom etc)
ffdur first pass first fixation duration value is 0 if absent
ffqual quality of ff same value as qual in fixation record; 0 if absent
ffbck direction of the fixation following the first fixation???:

0 = ff is absent

1 = the fixation following the first fixation falls in a coded region with
a lower value (regressive/backward)

2 = the fixation following the first fixation falls in a coded region with
a higher value (progressive/forward)

ffin Saccade In duration of first fixation in-saccade is the saccade preceding the fixation
ffout Saccade Out duration of first fixation out-saccade is the saccade following the fixation
rpdur rp: first pass regression path difference between the start time of the first pass first fixation in a coded region and the end time of the last fixation before leaving the coded region in a forward direction; rpdur is 0 if absent
rpqual quality of rp = sum of the following values:
0 = ok (or rp is absent)
1 = the first fixation of rp is a blink, or started with a blink
2 = there is a blink somewhere in the middle of rp
4 = the last fixation of rp is a blink or ended with a blink
8 = there is a rejected fixation at the beginning of rp
16= there is a rejected fixation somewhere within rp
32= there is a rejected fixation at the end of rp
rpcnt the number of fixations in rp
rpsacc sum of saccade durations in rp note: number of saccades is rpcnt – 1
rpout Saccade Out duration of regression path
tgdur first pass total gaze (sum of the durations of fixations that fall within the coded region before the region is left progressively). Included are intermediate saccade durations and blink durations, and excluded are rejections; tg is 0 if absent
tgqual quality of tg = sum of the following values:
0 = ok (or tg is absent)
1 = the first fixation of tg is a blink, or started with a blink
2 = there is a blink somewhere in the middle of tg
4 = the last fixation of tg is a blink or ended with a blink
8 = there is a rejected fixation at the beginning of tg
16= there is a rejected fixation somewhere within tg
32= there is a rejected fixation at the end of tg
tgcnt the number of fixations in tg
tgsacc sum of saccade durations in tg note: number of saccades is tgcnt – 1
tgout Saccade Out duration of total gaze
gdur first pass first gaze (difference between the starttime of the first pass first fixation in a coded region and the endtime of the last fixation before leaving the coded region in any direction; gdur is 0 if absent)
gqual quality of gdur = sum of the following values:
0 = ok (or gdur is absent)
1 = the first fixation of gdur is a blink, or started with a blink
2 = there is a blink somewhere in the middle of g1
4 = the last fixation of gdur is a blink or ended with a blink
8 = there is a rejected fixation at the beginning of gdur
16= there is a rejected fixation somewhere within gdur
32= there is a rejected fixation at the end of gdur
gcnt the number of fixations in gdur
gsacc sum of saccade durations in gdur note: number of saccades is gcnt – 1
gbck direction of the fixation following gdur:
0 = gdur is absent
1 = the fixation following gdur falls in a coded region with a lower value (regressive/backward)
2 = the fixation following gdur falls in a coded region with a higher value (progressive/forward)
gout Saccade Out duration of gdur

Aggregation file over regions: *.ago

Same as .agc, with some (uninteresting) variables missing, and aggregated over objects rather than regions of interest. For reading experiments, this means that the measures are aggregated over the first, second etc word in your stimulus. Not used often.

Total reading times

Fixation does not generate total reading times on regions (sum of all fixation durations in a region; also useful to determine second pass reading time). A perl script that does do this is available here. For each .agc, the script outputs an .act file, that is the .agc plus five extra columns:

Variable name Meaning Comments
totfixdur sum of ALL fixation durations in the region (including second, third… nth pass)
totfixcnt the number of fixations in totfixdur
num_fixQualNot0 the number of fixations in totfixdur that do not have Qual 0 (blinks/rejected fixations)
totfixQual0dur sum of all fixations in totfixdur that have Qual 0
totfixQual0cnt the number of fixations in totfixQual0Dur

Notes for previous users of Smiana

  • The following variables that were generated by Smiana, are no longer generated by Fixation:
    • in the .agc: ffbck
    • in the .jnf: Wort
  • The .obt files that serve as input to Fixation have one extra column compared to the .obt files used by Smiana. This extra column serves to code regions, and the numbering does not have to be consecutive for these regions (it’s there to accommodate (auditory?) region coding for visual world paradigm studies).

Output files for Visual World Paradigm experiments

Samples: *.ags

Similar to .jnf, but coded for samples rather than fixations. Contains the following variables:

Variable name Meaning Comments
expname three-letter name of the experiment first three characters of *.asc filename
imgfile name of the image file *.bmp
timfile name of the *.tim file associated with this stimulus (which contains the segmentation in your audio file) this column is empty if experiment is a reading experiment (i.e. if there is no file that specifies regions in an accompanying sound file). This gets confusing if you read in the *.jnf in excel (the columns are separated by a single space, but excel counts the two spaces surrounding the empty ‘timfile’ column as one). Simply remove the cell ‘timfile’ in the header row in excel and you’re good to go.
blocknr block number list number (the characters between the first and second underscore of *.asc filename, if these characters are numbers; zero otherwise)
subjectnr subject number
pagenr page number experimental trial number (counts excluding fillers)
samplenr sample number
samstart starting time of the sample
event codes whether the sample is part of a fixation, a saccade, or a blink (F, S or B)
fixnr number of the fixation the sample is part of saccades are coded as belonging to the fixation following it
fixdur duration of the fixation the sample is part of saccades are coded as belonging to the fixation following it
Qual quality of the fixation see here
obtnr number of the fixated object in text-based stimuli, object = word
oldobtnr number of the old assigned object Fixation gives this variable in the header line of the output file, but the numbers are actually not present
code code of the object codes areas of interest/analysis regions; numbering has to be consecutive to ensure proper calculation of the measures, but not all codes have to exist in all items; value is 0 if a fixation was not assigned to any object
code2 second code of the object second code for area of interest in a picture stimulus; can be used in VWP experiments to code location in the picture (top left, center bottom etc)
timcode time code in *.wav file comes from “point” in .tim; irrelevant for reading experiments
timstart marks onset of auditory segment the sample occurred in comes from “time” in .tim; irrelevant for reading experiments
timname name of the auditory segment the sample occurred in comes from “mark” in .tim; irrelevant for reading experiments

Time?: *.agt

Similar to .agc, but aggregated over both code and timcode. Contains the following variables:

Variable name Meaning Comments
expname three-letter name of the experiment first three characters of *.asc filename
blocknr block number list number (the characters between the first and second underscore of *.asc filename, if these characters are numbers; zero otherwise)
subjectnr subject number
imgfile name of the image file *.bmp
pagenr page number experimental trial number (counts excluding fillers)
pathcnt path count
obtnr number of the fixated object in text-based stimuli, object = word
left left coordinate of object/visual area of interest (x-value) the XY-coordinates of the visual area of interest is automatically defined (by FEP in our case) in reading experiments, and defined in mkobjects for VWP experiments
top top coordinate of object/visual area of interest (y-value)
right right coordinate of object/visual area of interest (x-value)
bottom bottom coordinate of object/visual area of interest (y-value)
code code of the object codes areas of interest/analysis regions; numbering has to be consecutive to ensure proper calculation of the measures, but not all codes have to exist in all items; value is 0 if a fixation was not assigned to any object
code2 second code of the object second code for area of interest in a picture stimulus; can be used in VWP experiments to code location in the picture (top left, center bottom etc)
pagedur total looking time on the stimulus?
fixcnt the number of fixations on code in timcode?
ffdur first pass first fixation duration value is 0 if absent
ffqual quality of ff same value as qual in fixation record; 0 if absent
ffbck direction of the fixation following the first fixation???:
0 = ff is absent
1 = the fixation following the first fixation falls in a coded region with a lower value (regressive/backward)
2 = the fixation following the first fixation falls in a coded region with a higher value (progressive/forward)
ffin Saccade In duration of first fixation in-saccade is the saccade preceding the fixation
ffout Saccade Out duration of first fixation out-saccade is the saccade following the fixation
gdur first pass first gaze (difference between the starttime of the first pass first fixation in a coded region and the endtime of the last fixation before leaving the coded region in any direction; gdur is 0 if absent)
gcnt the number of fixations in gdur
gqual quality of gdur = sum of the following values:
0 = ok (or gdur is absent)
1 = the first fixation of gdur is a blink, or started with a blink
2 = there is a blink somewhere in the middle of g1
4 = the last fixation of gdur is a blink or ended with a blink
8 = there is a rejected fixation at the beginning of gdur
16= there is a rejected fixation somewhere within gdur
32= there is a rejected fixation at the end of gdur
gout saccade duration following the last fixation in gdur
fixstart time start of the fixation
gout Saccade Out duration of gdur
timcode time code in *.wav file comes from “point” in .tim
timstart marks onset of auditory segment the fixation occurred in comes from “time” in .tim
timname name of the auditory segment the fixation occurred in comes from “mark” in .tim

Path?: *.agp

Contains a proper subset of the variables contained in .agt; fixation time aggregated over code alone, not timcode. Contains the following variables:

Variable name Meaning Comments
expname three-letter name of the experiment first three characters of *.asc filename
blocknr block number list number (the characters between the first and second underscore of *.asc filename, if these characters are numbers; zero otherwise)
subjectnr subject number
imgfile name of the image file *.bmp
pagenr page number experimental trial number (counts excluding fillers)
pathcnt path count
obtnr number of the fixated object in text-based stimuli, object = word
left left coordinate of object/visual area of interest (x-value) the XY-coordinates of the visual area of interest is automatically defined (by FEP in our case) in reading experiments, and defined in mkobjects for VWP experiments
top top coordinate of object/visual area of interest (y-value)
right right coordinate of object/visual area of interest (x-value)
bottom bottom coordinate of object/visual area of interest (y-value)
code code of the object codes areas of interest/analysis regions; numbering has to be consecutive to ensure proper calculation of the measures, but not all codes have to exist in all items; value is 0 if a fixation was not assigned to any object
code2 second code of the object second code for area of interest in a picture stimulus; can be used in VWP experiments to code location in the picture (top left, center bottom etc)
pagedur total looking time on the stimulus?
fixcnt the number of fixations on code in timcode?
ffdur first pass first fixation duration value is 0 if absent
ffqual quality of ff same value as qual in fixation record; 0 if absent
ffbck direction of the fixation following the first fixation???:
0 = ff is absent
1 = the fixation following the first fixation falls in a coded region with a lower value (regressive/backward)
2 = the fixation following the first fixation falls in a coded region with a higher value (progressive/forward)
ffin Saccade In duration of first fixation in-saccade is the saccade preceding the fixation
ffout Saccade Out duration of first fixation out-saccade is the saccade following the fixation
gdur first pass first gaze (difference between the starttime of the first pass first fixation in a coded region and the endtime of the last fixation before leaving the coded region in any direction; gdur is 0 if absent)
gqual quality of gdur = sum of the following values:
0 = ok (or gdur is absent)
1 = the first fixation of gdur is a blink, or started with a blink
2 = there is a blink somewhere in the middle of g1
4 = the last fixation of gdur is a blink or ended with a blink
8 = there is a rejected fixation at the beginning of gdur
16= there is a rejected fixation somewhere within gdur
32= there is a rejected fixation at the end of gdur
gcnt the number of fixations in gdur
gout saccade duration following the last fixation in gdur