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.