Recording
index
c:\temp\skardan\workspace\python\emdat\src\recording.py

UBC Eye Movement Data Analysis Toolkit
Recording class
 
Author: Nicholas FitzGerald - nicholas.fitzgerald@gmail.com
Modified by: Samad Kardan to a general class independent of the study
 
Class to hold all the data from one recording (i.e, one complete experiment session)
for one participant

 
Modules
       
geometry
math
params

 
Classes
       
Recording

 
class Recording
     Methods defined here:
__init__(self, all_file, fixation_file, media_offset=(0, 0))
Args:
    all_file: a string containing the filename of the 'All-Data.tsv' 
        file output by the Tobii software.
        
    fixation_file: a string containing the filename of the 
        'Fixation-Data.tsv' file output by the Tobii software.
        
    media_offset: the coordinates of the top left corner of the window
        showing the interface under study. (0,0) if the interface was
        in full screen (default value)
    
Yields:
    a Recording object
process_rec(self, segfile=None, scenelist=None, aoifile=None, aoilist=None, prune_length=None, require_valid_segs=True, auto_partition_low_quality_segments=False)
Processes the data for one recording (i.e, one complete experiment session)
 
        
Args:
    segfile: If not None, a string containing the name of the segfile 
        with segment definitions in following format:
        <Scene_ID>      <Segment_ID>    <start time>    <end time>
 
        e.g.:
        s1    seg1    0    5988013
        With one segment definition per line
    scenelist: If not None, a list of Scene objects
    *Note: At least one of segfile and scenelist should be not None
        
    aoifile: If not None, a string containing the name of the aoifile 
        with definitions of the "AOI"s.
    aoilist: If not None, a list of "AOI"s.
    *Note: if aoifile is not None, aoilist will be ignored
     
     $$$ Daria: if both aoifile and aoilist are none AOIs are ignored
     
    prune_length: If not None, an integer that specifies the time 
        interval (in ms) from the beginning of each Segment in which
        samples are considered in calculations.  This can be used if, 
        for example, you only wish to consider data in the first 
        1000 ms of each Segment. In this case (prune_length = 1000),
        all data beyond the first 1000ms of the start of the "Segment"s
        will be disregarded.
    
    require_valid_segs: a boolean determining whether invalid "Segment"s
        will be ignored when calculating the features or not. default = True 
    
    auto_partition_low_quality_segments: a boolean flag determining whether
        EMDAT should automatically split the "Segment"s which have low sample quality
        into two new sub "Segment"s discarding the largest invalid sample gap in 
        the "Segment". default = False
Returns:
    a list of Scene objects for this Recording
    a list of Segment objects for this recording. This is an aggregated list
    of the "Segment"s of all "Scene"s in the Recording

 
Functions
       
read_all_data(all_file)
Returns a list of "Datapoint"s read from an "All-Data" file.
 
Args:
    all_file:A string containing the name of the 'All-Data.tsv' file output by the
        Tobii software.
Returns:
    a list of "Datapoint"s
read_aois_Tobii(aoifile)
Returns a list of "AOI"s read from a '.aoi' file.
 
The '.aoi' files have pairs of lines of the form:
aoiname[tab]point1x,point1y[tab]point2x,point2y[tab]...[new line]
#[tab]start1,end1[tab]...[new line]
 
The first line determines name of the AOI and the coordinates of each vertex of 
the polygon that determines the boundaries of the AOI.
The second line which starts with a '#' is optional and determines the time
intervals when the AOI is active. If the second line does not exist the AOI will
be active throughout the whole session (global AOI). 
*Note: If the AOIs are exported from Tobii software the '.aoi' file will only have the 
first line for each AOI and you need to override this method to generate AOIs that are
active only at certain times (non-global AOI). 
 
Args:
    aoifile: A string containing the name of the '.aoi' file
    
Returns:
    a list of "AOI"s
read_fixation_data(fixation_file, media_offset=(0, 0))
Returns a list of "Fixation"s read from an "Fixation-Data" file. 
 
Args:
    fixation_file: A string containing the name of the 'Fixation-Data.tsv' file output by the
        Tobii software.
    media_offset: the coordinates of the top left corner of the window
            showing the interface under study. (0,0) if the interface was
            in full screen (default value) 
Returns:
    a list of "Fixation"s
read_segs(segfile)
Returns a dict with scid as the key and segments as value from a '.seg' file.
    
    A '.seg' file consists of a set of lines with the following format:
    scene_name[ ]segment_name[  ]start_time[    ]end_time[
]
    
    scene_name is the id of the Scene that this Segment belongs to,
    segment_name is the id of the Segement,
    and start_time and end_time determines the time interval for the Segment
 
    Args:
        segfile: A string containing the name of the '.seg' file
        
    Returns:
        a dict with scid as the key and segments as value
warn(...)
Issue a warning, or maybe ignore it or raise an exception.