Merge branch 'master' into release

Author: dcnieho

I2MC.m

@@ -3,24 +3,24 @@
 % The I2MC algorithm was designed to accomplish fixation detection in data
 % across a wide range of noise levels and when periods of data loss may
 % occur.
-
+% 
 % Cite as:
 % Hessels, R.S., Niehorster, D.C., Kemner, C., & Hooge, I.T.C., (2016).
 % Noise-robust fixation detection in eye-movement data - Identification by 
-% 2-means clustering (I2MC). Submitted.
-
+% 2-means clustering (I2MC). Behavior Research Methods.
+% 
 % For more information, questions, or to check whether we have updated to a
 % better version, e-mail: [email protected] / [email protected]. I2MC is
 % available from www.github.com/royhessels/I2MC
-
+% 
 % Most parts of the I2MC algorithm are licensed under the Creative Commons
 % Attribution 4.0 (CC BY 4.0) license. Some functions are under MIT 
 % license, and some may be under other licenses.
-
+% 
 % Quick start guide for adopting this script for your own data:
 % 1) Build an import function specific for your data (see importTobiiTX300
 % for an example). 
-
+% 
 % 2) Change line 106 to use your new import function. The format should be:
 %
 % data.time for the timestamp
@@ -31,15 +31,15 @@
 % You may provide coordinates from both eyes, only the left, only the
 % right, or only the average.
 % Gaze coordinates should be in pixels, timestamps should be in milliseconds
-
+% 
 % 3) Adjust the variables in the "necessary variables" section to match your
 %    data
 % 4) Run the algorithm
-
-% Requirements: Signal Processing Toolbox for downsampling. If not
-% available you may set opt.downsample to []. This may, however, degrade
-% performance of the algorithm.
-
+% 
+% Note: Signal Processing Toolbox is required for the default downsampling
+% procedure. If not available, set opt.downsampFilter to 0. This will use a
+% different downsampling procedure.
+% 
 % Tested on MATLAB R2012a, R2014b & R2016a
 
 %% INITIALIZE
@@ -83,10 +83,11 @@
 % opt.maxdisp                     = opt.xres*0.2*sqrt(2); % maximum displacement during missing for interpolation to be possible
 % 
 % % K-MEANS CLUSTERING
-% opt.windowtime                  = 0.2; % time window (s) over which to calculate 2-means clustering (choose value so that max. 1 saccade can occur)
-% opt.steptime                    = 0.02;% time window shift (s) for each iteration. Use zero for sample by sample processing
-% opt.maxerrors                   = 100; % maximum number of errors allowed in k-means clustering procedure before proceeding to next file
+% opt.windowtime                  = 0.2;        % time window (s) over which to calculate 2-means clustering (choose value so that max. 1 saccade can occur)
+% opt.steptime                    = 0.02;       % time window shift (s) for each iteration. Use zero for sample by sample processing
+% opt.maxerrors                   = 100;        % maximum number of errors allowed in k-means clustering procedure before proceeding to next file
 % opt.downsamples                 = [2 5 10];
+% opt.downsampFilter              = 0;          % use chebychev filter when downsampling? 1: yes, 0: no. requires signal processing toolbox. is what matlab's downsampling functions do, but could cause trouble (ringing) with the hard edges in eye-movement data
 % 
 % % FIXATION DETERMINATION
 % opt.cutoffstd                   = 2; % number of standard deviations above mean k-means weights will be used as fixation cutoff

README

@@ -1,7 +1,7 @@
 The I2MC algorithm was designed to accomplish fixation detection in data across a wide range of noise levels and when periods of data loss may occur.
 
 Cite as:
-Hessels, R.S., Niehorster, D.C., Kemner, C., & Hooge, I.T.C., (2016). Noise-robust fixation detection in eye-movement data - Identification by 2-means clustering (I2MC). Submitted.
+Hessels, R.S., Niehorster, D.C., Kemner, C., & Hooge, I.T.C., (2016). Noise-robust fixation detection in eye-movement data - Identification by 2-means clustering (I2MC). Behavior Research Methods.
 
 For more information, questions, or to check whether we have updated to a better version, e-mail: [email protected] / [email protected]. I2MC is available from www.github.com/royhessels/I2MC
 
@@ -17,11 +17,13 @@ data.left.X & data.left.Y for left gaze coordinates
 data.right.X & data.right.Y for right gaze coordinates
 data.average.X & data.average.Y for average of right and left gaze coordinates
 
-You may provide coordinates from both eyes, only the left, only the right, or only the average. Gaze coordinates should be in pixels, timestamps should be in milliseconds
+You may provide coordinates from both eyes, only the left, only the right, or only the average. 
+Gaze coordinates should be in pixels, timestamps should be in milliseconds
 
-3) Adjust the variables in the "necessary variables" section to match your data
+3) Adjust the variables in the "necessary variables" section to match your
+   data
 4) Run the algorithm
 
-Requirements: Signal Processing Toolbox for downsampling. If not available you may set opt.downsample to []. This may, however, degrade performance of the algorithm.
+Note: Signal Processing Toolbox is required for the default downsampling procedure. If not available, set opt.downsampFilter to 0. This will use a different downsampling procedure.
 
 Tested on MATLAB R2012a, R2014b & R2016a

functions/I2MC/I2MCfunc.m

@@ -29,6 +29,7 @@
 par.windowtime      = .2;       % time window (s) over which to calculate 2-means clustering (choose value so that max. 1 saccade can occur)
 par.steptime        = .02;      % time window shift (s) for each iteration. Use zero for sample by sample processing
 par.downsamples     = [2 5 10]; % downsample levels (can be empty)
+par.downsampFilter  = 1;        % use chebychev filter when downsampling? 1: yes, 0: no. requires signal processing toolbox. is what matlab's downsampling functions do, but could cause trouble (ringing) with the hard edges in eye-movement data
 par.chebyOrder      = 8;        % order of cheby1 Chebyshev downsampling filter, default is normally ok, as long as there are 25 or more samples in the window (you may have less if your data is of low sampling rate or your window is small
 par.maxerrors       = 100;      % maximum number of errors allowed in k-means clustering procedure before proceeding to next file
 % FIXATION DETERMINATION
@@ -54,7 +55,7 @@
             checkNumeric(value,key);
             checkScalar(value,key);
             par.(key) = value;
-        case {'chebyOrder','maxerrors','edgeSampInterp'}
+        case {'downsampFilter','chebyOrder','maxerrors','edgeSampInterp'}
             checkInt(value,key);
             checkScalar(value,key);
             par.(key) = value;
@@ -158,7 +159,7 @@
 
     % get kmeans-clustering for averaged signal
     fprintf('2-Means clustering started for averaged signal \n');
-    [data.finalweights,stopped] = twoClusterWeighting(xpos,ypos,missingn,par.downsamples,par.chebyOrder,par.windowtime,par.steptime,par.freq,par.maxerrors);
+    [data.finalweights,stopped] = twoClusterWeighting(xpos,ypos,missingn,par.downsamples,par.downsampFilter,par.chebyOrder,par.windowtime,par.steptime,par.freq,par.maxerrors);
 
     % check whether clustering succeeded
     if stopped
@@ -170,7 +171,7 @@
 elseif q2Eyes
     % get kmeans-clustering for left eye signal
     fprintf('2-Means clustering started for left eye signal \n');
-    [finalweights_left,stopped] = twoClusterWeighting(llx,lly,llmiss,par.downsamples,par.chebyOrder,par.windowtime,par.steptime,par.freq,par.maxerrors);
+    [finalweights_left,stopped] = twoClusterWeighting(llx,lly,llmiss,par.downsamples,par.downsampFilter,par.chebyOrder,par.windowtime,par.steptime,par.freq,par.maxerrors);
 
     % check whether clustering succeeded
     if stopped
@@ -180,7 +181,7 @@
 
     % get kmeans-clustering for right eye signal
     fprintf('2-Means clustering started for right eye signal \n');
-    [finalweights_right,stopped] = twoClusterWeighting(rrx,rry,rrmiss,par.downsamples,par.chebyOrder,par.windowtime,par.steptime,par.freq,par.maxerrors);
+    [finalweights_right,stopped] = twoClusterWeighting(rrx,rry,rrmiss,par.downsamples,par.downsampFilter,par.chebyOrder,par.windowtime,par.steptime,par.freq,par.maxerrors);
 
     % check whether clustering succeeded
     if stopped

functions/I2MC/twoClusterWeighting.m

@@ -1,10 +1,11 @@
-function [finalweights,stopped] = twoClusterWeighting(xpos,ypos,missing,downsamples,chebyOrder,windowtime,steptime,freq,maxerrors)
+function [finalweights,stopped] = twoClusterWeighting(xpos,ypos,missing,downsamples,downsampFilter,chebyOrder,windowtime,steptime,freq,maxerrors)
 % Calculates 2-means cluster weighting for eye-tracking data
 %
 % Input:
 % xpos,ypos                     = horizontal and vertical coordinates from eye-tracker over which to calculate 2-means clustering
 % missingn                      = boolean indicating which samples are missing
 % downsamples                   = downsample levels used for data (1/no downsampling is always done, don't specify that) 
+% downsampFilter                = use chebychev filter when downsampling? 1: yes, 0: no. requires signal processing toolbox. is what matlab's downsampling functions do, but could cause trouble (ringing) with the hard edges in eye-movement data
 % chebyOrder                    = order of Chebyshev downsampling filter
 % windowtime                    = time window (s) over which to calculate 2-means clustering (choose value so that max. 1 saccade can occur)
 % steptime                      = time window (s) in each iteration. Use zero for sample by sample processing
@@ -35,12 +36,17 @@
 nd = length(downsamples);
 assert(~any(mod(freq,downsamples)),'Some of your downsample levels are not divisors of your sampling frequency')
 
-% filter signal. Follow the lead of decimate(), which first runs a
-% Chebychev filter as specified below
-rip = .05;	% passband ripple in dB
-[b,a,idxs] = deal(cell(1,nd));
+if downsampFilter
+    % filter signal. Follow the lead of decimate(), which first runs a
+    % Chebychev filter as specified below
+    rip = .05;	% passband ripple in dB
+    [b,a] = deal(cell(1,nd));
+    for p=1:nd
+        [b{p},a{p}] = cheby1(chebyOrder, rip, .8/downsamples(p));
+    end
+end
+idxs = cell(1,nd);
 for p=1:nd
-    [b{p},a{p}] = cheby1(chebyOrder, rip, .8/downsamples(p));
     idxs{p}     = fliplr(nrsamples:-downsamples(p):1);
 end
 
@@ -94,8 +100,12 @@
     % number of samples is reduced. select samples such that they are till
     % end of window
     for p=1:nd
-        ll_d{p+1} = filtfilt(b{p},a{p},ll_d{1});
-        ll_d{p+1} = ll_d{p+1}(idxs{p},:);
+        if downsampFilter
+            ll_d{p+1} = filtfilt(b{p},a{p},ll_d{1});
+            ll_d{p+1} = ll_d{p+1}(idxs{p},:);
+        else
+            ll_d{p+1} = ll_d{1}(idxs{p},:);
+        end
     end
 
     % do 2-means clustering