Eyetracking updates May 2007
Modifications were made to the Matlab eyetracking processing programs in May 2007 in order to handle data files without events. A new argument was added to specify whether the pupil data is 'old' (prior to 2004) or 'new' (post 2004) format. The logFileName can be set to 'noevents' to specify that there is no log file containing events.
The new call has the form:
eyetrack_toMat('.','H',30,20,1,5,5,Inf,Inf,200,'negneu1.txt','new','noevents');
Eyetracking updates April 2004
Modifications were made to the Matlab eyetracking processing programs in April 2004 in order to handle the slightly modified pupil data files produced by the new eyetracking software and to read log files produced by the skin conductance (SCR) software (see notes below on original version). The Windows program IDFConverter.exe is used to convert the binary .idf files produced by the eyetracker into text files (using the iv3 compatible option).
The new call is:
eyetrack_toMat('.','H',30,20,1,5,5,Inf,Inf,200,'negneu1.txt','res888negneu1.log');
where '.' is the current working directory, H - horizontal pupil diameter (or V for vertical), 30,20,1,5,5,Inf,Inf,200 are blink correction parameters (see description below) which seem to work well with the new eyetracking data, negneu1.txt is the eyetracking pupil data file and res888negneu1.log is the log file created by the skin conductance (SCR) software.
The first few lines of the pupil data file negneu1.txt are:
#FileVersion: 2
#Fileformat: 2558
#Subject:
#Date: April 01, 2004
#Description:
## of Pts Recorded: 20625
#Offset Of Calibration Area: 0 0
#Size Of Calibration Area: 800 600
#Sample Rate: 60
#
#Time Set Pupil H Pupil V C.R. H C.R. V
ScreenH ScreenV Diam H Diam V
0 0 5786 3915
5222 3922 292
307 2144 2304
16 0 5792 3920
5222 3924 287
315 2144 2304
33 0 5794 3919
5220 3925 283
315 2144 2272
49 0 5794 3915
5217 3928 281
305 2144 2272
66 0 5740 3917
5199 3927 308
297 2144 2304
83 0 5619 3916
5155 3918 387
287 2176 2336
100 0 5590 3915
5134 3915 402
289 2144 2304
116 0 5585 3919
5131 3918 405
294 2176 2272
which is essentially the same as the original eyetracking data file format (see run1.dat below) except that there are no Counter, Objects and Aux in columns 1, 12 and 13 respectively.
The first few lines of the log file (res888negneu1.log)
created by the skin conductance (SCR) software during the eyetracking run are:
Thursday, April 01, 2004
11:14 AM
sample rate: 20
gain: 0.500000
event codes:
8 start run
1 enhance
2 maintain
3 suppress
4 negative
5 neutral
6 null
7 image onset
9 end run
0 no event
event time fileOnset description
8 0 0
start run
0 395 8295 no event
5 415 8715 neutral
0 455 9555 no event
4 515 10815 negative
0 555 11655 no event
6 575 12075 null
0 615 12915 no event
5 635 13335 neutral
0 675 14175 no event
4 695 14595 negative
0 735 15435 no event
4 775 16275 negative
The Matlab function that reads this log file verifies that the sample rate is 20 and that the column header line just after the blank line contains the word 'description' as a check that the log file has the correct format.
A new Matlab function eyetrack_createMeans(fileName,sessName,studyName) was written to process the filtered output from eyetrack_toMat into event locked time interval means and write them to an ascii file for statistical processing. Parameter studyName determines the details of the processing. So far only the RESMRI study is supported.
For RESMRI there are two types of runs, negative/neutral (negneu) where negative and neutral pictures are presented and regulation (reg) where all pictures are negative and a cue (enhance, maintain, or suppress) is given four seconds after picture presentation. The output text files consist of nine columns containing session number, run number, valence, regulation, time interval number, time in ms, 0.5 sec mean pupil diameter, five sample mean about minimum value in 0.5 sec interval, and fraction of corrected data in 0.5 sec interval. Each line contains the values for a 0.5 second interval with the time intervals extending from 1 sec before each picture event to 1 second before the next picture (or end run) event. Before computing 0.5 second means and minimums the filtered and blink corrected data from 1 second before the first event to 1 second before the "end run" event are detrended.
Below is the output for eyetrack_createMeans('RES085_negneu_run2H_mat.DAT','3','RESMRI')
Sess run val. reg. intvl# time(ms) mn pupdiam
min pupdiam frac blink corrected data
3 2 4 0 1
20000 264.5
247.3 0.17
3 2 4 0 2
20500 182.6
149.2 0.67
3 2 4 0 3
21000 148.7
138.1 0.50
3 2 4 0 4
21500 -1.9
-54.6 1.00
3 2 4 0 5
22000 -33.6
-54.8 1.00
3 2 4 0 6
22500 59.8
11.3 1.00
3 2 4 0 7
23000 18.8
1.5 0.33
3 2 4 0 8
23500 7.5
-15.7 0.50
3 2 4 0 9
24000 101.1
70.5 1.00
3 2 4 0 10
24500 131.8
120.0 0.50
3 2 4 0 11
25000 144.0
133.8 0.67
3 2 4 0 12
25500 144.9
142.0 0.00
3 2 5 0 1
26000 163.7
145.8 0.67
3 2 5 0 2
26500 139.6
116.7 0.17
3 2 5 0 3
27000 129.2
82.1 1.00
Below is the output for eyetrack_createMeans('RES085_reg_run1H_mat.DAT','3','RESMRI')
Sess run val. reg. intvl# time(ms) mn pupdiam
min pupdiam frac blink corrected data
3 1 7 1 1
19750 86.9
72.5 0.33
3 1 7 1 2
20250 129.0
110.8 0.67
3 1 7 1 3
20750 88.4
70.0 0.00
3 1 7 1 4
21250 54.8
-40.3 0.83
3 1 7 1 5
21750 -156.7 -206.4
0.33
3 1 7 1 6
22250 -137.9 -190.4
0.83
3 1 7 1 7
22750 -80.8
-96.7 0.50
3 1 7 1 8
23250 -39.7
-59.9 1.00
3 1 7 1 9
23750 -98.1 -127.6
0.50
3 1 7 1 10
24250 -97.5 -137.0
0.83
3 1 7 1 11
24750 -64.5 -100.9
0.83
3 1 7 1 12
25250 -118.8 -137.8
0.50
3 1 7 1 13
25750 -56.5
-97.7 0.33
3 1 7 1 14
26250 4.2
-20.0 0.83
3 1 7 1 15
26750 0.2
-19.8 1.00
3 1 7 1 16
27250 -32.3
-40.3 0.33
3 1 7 1 17
27750 -28.9
-31.6 0.67
3 1 7 1 18
28250 17.5
-19.3 0.67
3 1 7 1 19
28750 28.7
12.3 1.00
3 1 7 1 20
29250 18.7
-36.2 0.50
3 1 7 1 21
29750 -46.3
-81.3 0.83
3 1 7 1 22
30250 -51.8
-64.5 1.00
3 1 7 1 23
30750 -28.8
-51.8 1.00
3 1 7 1 24
31250 -53.3
-66.4 0.83
3 1 7 1 25
31750 -81.9
-93.1 0.33
3 1 7 1 26
32250 -57.1
-80.9 0.33
3 1 7 1 27
32750 -23.7
-45.4 0.33
3 1 7 1 28
33250 -25.7
-48.7 0.17
3 1 7 1 29
33750 25.3
-2.1 0.17
3 1 7 1 30
34250 68.4
64.8 0.00
3 1 7 1 31
34750 66.4
62.4 0.33
3 1 7 1 32
35250 80.4
65.6 0.67
3 1 7 1 33
35750 89.4
64.5 0.33
3 1 7 1 34
36250 60.0
50.0 0.83
3 1 7 1 35
36750 74.4
56.5 1.00
3 1 7 1 36
37250 103.9
85.5 1.00
3 1 7 1 37
37750 147.1
124.2 1.00
3 1 7 1 38
38250 158.6
152.9 1.00
3 1 7 1 39
38750 163.6
136.9 1.00
3 1 7 1 40
39250 150.8
144.4 1.00
3 1 7 3 1
39750 167.9
157.3 1.00
3 1 7 3 2
40250 123.4
88.5 1.00
3 1 7 3 3
40750 79.9
74.8 0.17
Eye Tracking (original version notes)
The eye tracking software consists of a set of Matlab programs which read eyetracking data files, remove blinks, smooth the data and save it to .DAT files which can be viewed with EEGSCORE. Processing eyetracking data is started by calling the main Matlab program eyetrack_toMat and results can be processed in SAS or SPSS by calling eyetrack_createText (this function was written for processing RESMRI data). An example batch file for processing vertical pupil eyetracking data is shown below (change 'V' to 'H' to process horizontal pupil data):
cd .\RES002
eyetrack_toMat('.','V',200,100,1,5,5,Inf,Inf,200);
cd .\RES002
eyetrack_createText('run1V_mat.DAT','2');
eyetrack_createText('run2V_mat.DAT','2');
eyetrack_createText('run3V_mat.DAT','2');
eyetrack_createText('run4V_mat.DAT','2');
cd ..\RES008
eyetrack_toMat('.','V',200,100,1,5,5,Inf,Inf,200);
cd .\RES008
eyetrack_createText('run1V_mat.DAT','8');
eyetrack_createText('run2V_mat.DAT','8');
eyetrack_createText('run3V_mat.DAT','8');
eyetrack_createText('run4V_mat.DAT','8');
for this example the pupil data were in files in the RES### directory:
run1.dat
run2.dat
run3.dat
run4.dat
some lines from run1.dat are:
#Fileversion: 2
#Fileformat: 3071
#Subject: Wisconsin 2
#Date: 7/24/02
#Description: None
## of Pts Recorded: 60465
#Offset Of Calibration Area: 0 0
#Size Of Calibration Area: 400 543
#Sample Rate: 60
#
#Counter Time Set Pupil H Pupil V C.R. H C.R. V ScreenH ScreenV Diam H Diam V
Objects Aux
0 0 0
5862 6754 7677 6620
301 146 4992 9344
0 0
1 17 0 5862
6791 7679 6647 302
147 4960 9344 0
0
2 34 0 5862
6818 7679 6668 303
148 4960 9344 0
0
3 50 0 5862
6818 7679 6671 304
149 4960 9344 0
0
4 67 0 5862
6818 7679 6671 304
149 4992 9344 0
0
5 84 0 5862
6843 7679 6671 305
152 4992 9344 0
0
6 100 0 5862
6843 7679 6680 306
153 4992 9344 0
0
and the parent directory contained the event files which were the same for all
sessions:
events_run1.txt
events_run2.txt
events_run3.txt
events_run4.txt
Some lines from events_run1.txt follow:
21000 1
24000 3
38000 1
42000 4
55000 1
60000 4
72000 2
78000 4
89000 1
94000 5
where the first column is times in milliseconds and the
second is valence for events 1,3,5 ... and regulation for events 2,4,6 ...
The main function has the following form
function
eyetrack_toMat(dirName,direction,regThreshold,slopeThreshold,extremeThreshold,
...
numSamples,weightingWidth,outofrange,outofwiderange,widerange,fileName)
%
% function eyetrack_toMat(dirName,regThreshold,slopeThreshold,extremeThreshold,
...
% numSamples,weightingWidth,outofrange,outofwiderange,widerange,[fileName])
%
% this function translates all the .dat eyetracking files in directory
% dirName into Matlab files compatible with eegscore
% if fileName specified then only that file is translated
% it assumes that the event files are in the parent directory to dirName
%
% modified 5/1/03 adding direction argument = 'H' or 'V' to process either
% the horizontal or vertical pupil diameters
Thus for the batch file above:
dirName = '.' the current directory
RES002
direction = 'V'
regThreshold = 200
slopeThreshold = 100
extremeThreshold=1
numSamples=5
weightingWidth=5
outofrange=Inf
outofwiderange=Inf
widerange=200
fileName not specified so that all .dat files in directory are processed
In order to view the output files with EEGSCORE, a minor
modification may need to be made to the default EEGSCORE4v1.CFG file if pupil
diameters exceed 3200 as shown in the example file above. The DATA SCALE factor
may be changed from the default value of 10 to 1 as shown below. A copy of
the modified EEGSCORE4v1.CFG file can be found in /d1/local/matlab/eyetracking
or simply open one of the run#_mat.DAT with eegscore letting it create a default
configuration file. Then close eegscore and use TextEdit to change the
lines shown below. Reopen the .DAT file in eegscore and choose the
modified EEGSCORE4v1.CFG file.
# Scale factor to convert data to two byte integers)
# use 10 (default) if data in range -3200, +3200)
DATA SCALE: 1
eyetrack_toMat() creates an EEGSCORE compatible set of Matlab files with the raw data displayed in the first channel, filtered and blink removed data in channel 3, events coded as height of spike equal to event value in channel 3 and blink mask displayed in channel 4.
The egi_createText function was written to process RESMRI data and computes average pupil dilation values from the processed data created by eyetrack_toMat:
function eyetrack_createText(fileName,sessName)
%
% function eyetrack_createText(fileName,sessName)
%
% this function processes RESMRI run#V_mat.DAT or run#H_mat.DAT files
% creating a text file with eight columns containing sessName, run#,
valence,regulation,
% time interval#,time in ms, 0.5 sec mean (30 points) of detrended vertical
pupil dilation data
% and fraction of data masked in that 0.5 second period
% each line contains 0.5 sec averages from 1 sec before valence event mark
% to 16 sec after (numbered from 1-34 in column 3; thus there are 34 x numEvents
lines of data
%
% 3/13/03 LLG
% modified 3/17/03 adding sessName, run# and time columns
%
% modified 5/1/03 by LG to compute 0.5 sec means from 1 sec before valence event
to 1 sec
% before next valence event whenever that might be.
% also added column to output file with time in msec of start of each 0.5 sec
mean
% in order to verify that all times are correct.
Sample output looks like:
sess run val reg intrvl time mn
pupdiam frac blink corrected data
1 1 1 3 1
20000 757.4 1.00
1 1 1 3 2
20500 471.4 1.00
1 1 1 3 3
21000 15.0 1.00
1 1 1 3 4
21500 -1068.0 1.00
1 1 1 3 5
22000 -1074.8 1.00
1 1 1 3 6
22500 -691.1 1.00
1 1 1 3 7
23000 -736.4 1.00
1 1 1 3 8
23500 -824.6 1.00
1 1 1 3 9
24000 -463.5 1.00
1 1 1 3 10
24500 16.3 1.00
1 1 1 3 11
25000 245.2 1.00
1 1 1 3 12
25500 186.6 1.00
1 1 1 3 13
26000 38.7 1.00
1 1 1 3 14
26500 341.4 1.00
1 1 1 3 15
27000 402.2 1.00
1 1 1 3 16
27500 593.7 1.00
1 1 1 3 17
28000 493.6 1.00
1 1 1 3 18
28500 216.7 1.00
1 1 1 3 19
29000 -147.9 1.00
1 1 1 3 20
29500 -559.9 1.00
1 1 1 3 21
30000 -551.9 1.00
1 1 1 3 22
30500 -519.8 1.00
1 1 1 3 23
31000 107.0 1.00
1 1 1 3 24
31500 466.5 1.00
1 1 1 3 25
32000 416.2 1.00
1 1 1 3 26
32500 325.6 1.00
1 1 1 3 27
33000 117.0 1.00
1 1 1 3 28
33500 343.7 1.00
1 1 1 3 29
34000 -337.4 1.00
1 1 1 3 30
34500 24.7 1.00
1 1 1 3 31
35000 433.3 1.00
1 1 1 3 32
35500 623.2 1.00
1 1 1 3 33
36000 389.6 1.00
1 1 1 3 34
36500 380.5 1.00
The egi_createAutText function was written to process Autism data and computes average pupil dilation values and count blinks from the processed data created by eyetrack_toMat:
% function eyetrack_createAutText(fileName,sessName)
%
% this function processes the run#(H or V)_mat.DAT file for the Autism study
% modified 4/28/03 from eyetrack_createText
% creates two text files one _250ms.txt with 250 msec averages of detrended
% vertical or horizontal pupil dilation data
% and a second _blinks.txt with number of blinks in 3 seconds after each event
% and number of blinks from 3 secs to the next stimulus
%
% output columns for _blinks.txt are: sess#, stimulus value, time(ms), #blinks
% within 3s period after stim. and #blinks from 3s to next stim
%
% output columns for _250ms.txt are: sess#, time(ms) of start of 250ms period,
% mean pupil diameter for 250ms
Sample output files are:
runV_mat_250ms.txt
1 0 310.8
1 250 311.4
1 500 312.0
1 750 312.5
1 1000 243.5
1 1250 228.4
1 1500 264.5
1 1750 229.6
1 2000 187.5
1 2250 188.4
1 2500 290.7
1 2750 317.3
1 3000 272.8
runV_mat_blinks.txt
1 3 31000 0 0
1 2 40000 0 0
1 3 48000 0 0
1 2 57000 0 0
1 3 67000 0 0
1 1 75000 0 1
1 1 84000 0 0
1 4 94000 0 1
1 2 102000 0 1
Description of Matlab functions:
function
eyetrack_toMat(dirName,direction,regThreshold,slopeThreshold,extremeThreshold,
...
numSamples,weightingWidth,outofrange,outofwiderange,widerange,fileName)
calls
function
eyetrack_makeMat(fileName,regThreshold,slopeThreshold,extremeThreshold, ...
numSamples,weightingWidth,outofrange,outofwiderange,widerange,direction)
which reads input data: pupilDat = eyetrack_readDat(fileName,direction);
reads event data from files in parent directory named events_basefileName.txt
for example if pupil data files are named:
run1.dat
run2.dat
run3.dat
run4.dat
then the parent directory contains the event files:
events_run1.txt
events_run2.txt
events_run3.txt
events_run4.txt
and creates event channel assuming 60Hz sampling and events in milliseconds
Array allChannelData is created for output with raw pupilDat in channel one
(i.e. column 1) and events in channel three. All processing of the raw pupil
data is handled by function puppreprocess as shown below:
% set up structure for puppreprocess
data.RescaleData = allChannelData(:,1)';
data.NoBlinks = zeros(size(pupilDat,1),1);
data.BlinkTimes = zeros(size(pupilDat,1),1);
data.BlinkMask = ones(size(pupilDat,1),1);
data = puppreprocess(data,regThreshold,slopeThreshold,extremeThreshold, ...
numSamples,weightingWidth,outofrange,outofwiderange,widerange);
column 2 of allChannelData receives the cleaned up pupil data, data.NoBlinks,
and column 4 data.BlinkMask which indicates where blinks were detected.
puppreprocess calls dbfilter to smooth data and rblinks to remove blinks
function [avgdata]=dbfilter(data,ptstoaverage,numtimes)
ptstoaverage is set to weightingWidth and the default numtimes = 2 is used. So
dbfilter performs a simple running average of weightingWidth points and applies
it twice.
Next puppreprocess calls rblinks to remove blinks from the data. The averaged
data, avgdata, is sent to rblinks
function[noblinks]=rblinks(indata,regThreshold,slopeThreshold,extremeThreshold,numSamples,
weightingWidth,outofrange)
indata = avgdata
regThreshold: if any numSamples values depart from regression by more than
regThreshold then a blink is found
slopeThreshold: if exceeded by regression slope and max minus min values of
numSamples exceeds
extremeThreshold: then a blink is found (also if pupil dilation = 0 blink is
found)
numSamples: is number of samples used in regression to test for blink slope
weightingWidth: is no longer used in rblinks (see dbfilter)
outofrange: if pupil dilation values depart by outofrange from median value then
blink is found
eyetrack_makeMat then writes allChannelData to a Matlab .DAT file named
basefileName(H or V)_mat.DAT and creates the auxilary files necessary to open
this file in eegscore. For the example above the output files for pupil
data run1.dat would be:
run1V_mat.DAT
run1V_mat.MASK
run1V_mat_CFG.m
run1V_mar_CHN.m
Parameters:
regThreshold: if any numSamples values depart
from regression by more than regThreshold then a blink is found
slopeThreshold: must be exceeded by blink slope to be considered a blink
(extremeThreshold must also be exceeded)
extremeThreshold: max minus min values of numSamples must exceed this
value to be a blink (in addition to slopeThreshold being exceeded)
numSamples: number of samples to use in regression equation to determine
blink slope
weightingWidth: number of samples to use in running average
outofrange: if pupil dilation values depart by outofrange from median
value then blink is found
outofwiderange: if < Inf then puppreprocess calls rblink a second time
with slopeThreshold = Inf, extremeThreshold = outofrange,
and numSamples = widerange
widerange: used only if outofwiderange < Inf; numSamples is set to
widerange in second call to rblink