NAME

EyeTracking::EYD

VERSION

version 0.1.2

SYNOPSIS

   # the binary EYD file
   my $file='/home/foranw/remotes/B/bea_res/Data/Tasks/BarsScan/Basic/10128/20080925/Raw/EyeData/10128_run1.eyd';
   my $id="10128.20090925.1";
   my $errorfile="$id.err";
   # an expected order-of-events long file

   my $order='/home/foranw/remotes/B/bea_res/MR_Scanner_Experiments/Scanner Tasks/MRRC tasks/Rewards Scanner Bars/OrderOfEvents-v1.txt';
   ##trial.num event
   #1 neutral007
   #1 LongFix
   #2 FIVEpunish532
   #2 LongFix
   #3 FIVEreward532
   ### used by barsEprimeTrialOrder
   ### hardcoded xdat codes (start,target,stop) as hash from e.g. neutral007
   ###           time delays as a result of eg LongFix


   my $eyd = EyeTracking::EYD->new($file,$id,$errorfile);
   # $eyd->{verbose}=1;     # print lots of fun things
   # $eyd->{printerrors}=1; # errors also go to stdout
   $eyd->read();
   # print Dumper($eyd->{data}),"\n";
   $eyd->printEyeData(); # just: xdat, dil, gaze
   $eyd->printallEyeData(); # print everying


   use Number::Range;
   my $startCodes  = Number::Range->new("50,100,200");
   my $targetCodes = Number::Range->new("110..160,201..210");
   my $stopCodes   = Number::Range->new("250");
   $eyd->trialPositions($startCodes,$targetCodes,$stopCodes );
   # print Dumper($eyd->{codes}),"\n";

   # print codes and index in triplet pairs
   # eg. 100  147  250  15387 15568 15666
   $eyd->printCodes();

   # use order of exerpiment to set timing
   $eyd->barsEprimeTrialOrder($order);
   #print Dumper($self->{_idealOrderHash})
   $eyd->checkAlignment();
   # with verbose, prints a nice list like:
   #strt trg   stp   ITIo  ITIe  strtp trgp  stpp  lastp proc
   #200  201   250   357   363   |  480   656   753   837   +LongFix
   #

   #$eyd->{checked}
   # we have a 'legacy' format to persever
   # print in that format
   my @fields=@{$eyd->{checkedHdr}}{qw/strt trg stp strtp trgp stpp lastp strtep trgep stpep/};
   print ( map {join("\t",@$_[@fields ]),"\n"} @{$eyd->{checked}}  ), "\n";

DESCRIPTION

This provides functions to deal with ASL EYD binary files specifically in the context of EPrime run experments.

In addition to pupil dilation and gaze location, we are particularly interested in using the eyd timing as a way to confirm task progress (via xdat codes) and adjust expected timing from eprime (via sample number)

Parsing the binary file was largely copied from http://tech.groups.yahoo.com/group/ilab/

NAME

EyeTracking::EYD - extract EYD binary files in a start,target,stop paradigm

METHODS

new

$eyd = EyeTracking::EYD->new($file,$id,$errorfile) requries an eyd file be passed as the sole argument set $self->{verbose} to true for more printing

read

$eyd->read() reads the eyd file provided when new() is called

creates $eyd->{qw/_startbyte _endbyte _recfmt _records fields data}

data and fields

data is a 2D array of where each row has a sample of of @fields =item @_records

@_records stores the type and name of each field

other

_recfmt, start, and endbyte together describe the start and end of the binary blob and what the order of encoding is

"Corrects" gaze by origvalue/10

this code is taken mostly from ilab =back

printEyeData

$eyd->printEyeData(filename=<stdout>) prints XDAT, pupil_diam and gaze to stdout unless af filename is given one sample per line

printallEyeData

$eyd->printallEyeData() prints everything collected one sample per line

trialPositions

$eyd->trialPositions($start,$target,$stop) where start,target,stop are all number::range ojbects will make a wide fromate table of start | target | stop in the form of a hash as {codes}

   my $startCodes  = Number::Range->new("50,100,200");
   my $targetCodes = Number::Range->new("110..160,201..210");
   my $stopCodes   = Number::Range->new("250");
   $eyd->trialPositions($startCodes,$targetCodes,$stopCodes) 
   print Dumper($eyd->{codes})

barsEprimeLog and barsEprimeTrialOrder

$eyd->barsEprimeLog($logfile) or $eyd->barsEprimeTrialOrder($orderfile) results in $eyd->{_idealOrderHash}

where logfile is an eprime experement's log file and orderfile is a space deliminted file with 'trial# displayevent' on each line

logfiles are specific to one subject on a particular run orderfiles are generic for all subjects for a particular run

the output is an array of hashes like

   $VAR42 = {
      'startcode' => 100,
      'Latency' => '451',              #*
      'masterlist' => '142',           #*
      'location' => '532',
      'fixationTxt' => '+LongFix',
      'fixation' => 363,
      'targetcode' => 149,
      'Score' => '60',                 #*
      'Procedure' => 'FIVEpunish532',
      'Correct' => '1',                #*
      'Running' => 'masterlist'        #*
   };

* denotes hash elements only created by barsEprimeLog not in barsEprimeTrialOrder

fixationTxt is a + delim. list of fixation events duration is the number of samples (assumed 60Hz) as estimated by parsing and evaluating fixationTxt

example orderfile

   1 neutral007
   1 LongFix
   2 FIVEpunish532
   2 LongFix
   3 FIVEreward532
   3 LongFix
   3 fix
   3 fix
   3 punCatch1
   3 fix
   4 neutral532
   ...

example logfile

study details

| bars | cross | dot | cross cue prep sac | fixations | | | | start target stop=250 | 1.5 1.5 1.5 | 1.5s*N LongFix==2*1.5s | {,ONE..FIVE}{punish,neutral,reward}{[position]} | LongFix + { fix,Catch{1,2} }*

Ring Rewards

We can also parse ring rewards eprime order files parsed trial information is stored in $eyd->{_idealOrderHash}

checkAlignment

$eyd->checkAlignment(filename=<STDERR>) returns the alignment score between observed and experiement setup (eprime) and prints alignment errors to stderr or specified file extensivle checks value of $self->{verbose} when printing

uses {_idealOrderHash} and {codes} (both arrays of hashes with startcode and targetcode) to find the optimal (NeedlemanWunsch with gap/mismatch=-5) alignment of start and target codes

setting $self->{codeTableFN} to a file will write the ITIobserved against ITIexpected table to that file

printCodes

$eyd->printCodes() prints codes to a given file name (or stdout if no arguments) is a nice way of exporting $self->{codes}

AUTHOR

Will Foran <willforan+cpan@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Will Foran <willforan+cpan@gmail.com>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm EyeTracking::EYD

perl -MCPAN -e shell
install EyeTracking::EYD