Fixation manual

If you have suggestions on how to improve this document, or find mistakes, please send them to ilslabs@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
   • Output files for reading experiments:
     • .jnf output file Join file: list of fixations.
     • .agc output file Aggregated by code: list of (visual) areas of interest.
     • .ago output file Aggregated by object.
   • Total reading times
   • Notes for previous users of SMIana
   • Output files for Visual World Paradigm experiments:
     • .jnf output file Join file: list of fixations.
     • .ags output file Aggregated by sample (cf. jnf).
     • .agt output file Aggregated by time (auditory segment) and code (visual area of interest).
     • .agp output file Aggregated by path.

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:

Aggregation file over regions: *.agc

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

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 python 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:

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:

Time?: *.agt

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

Path?: *.agp

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