Segment
index
c:\temp\skardan\workspace\python\emdat\src\segment.py

UBC Eye Movement Data Analysis Toolkit
Created on 2011-08-26
 
@author: skardan

 
Modules
       
geometry
math
params

 
Classes
       
Segment

 
class Segment
    Segment is a class that represents the smallest unit of aggregated eye data samples with a conceptual meaning.
 
A segment is the smallest unit of aggregated eye data samples that has conceptual meaning. This class is the equivalent
of segments as defined in Tobii studio. 
 
Attributes:
    segid: A string containing the id of the Segment.
    alldata: A list of "Datapoint"s for this Segment
    features: A dict with feature names as its keys and feature values as its values 
    completion_time: An integer indicating total duration of the Segment in milliseconds
        minimum is 16 ms (length of one sample with 60Hz sampling rate (ms))
    start: An integer indicating the Segment's start time in milliseconds
    end: An integer indicating the Segment's end time in milliseconds
    sample_start_ind: An integer indicating the index of the first Datapoint for this Segment in the Participant's list of all "Datapoint"s (all_data) 
    sample_end_ind: An integer indicating the index of the last Datapoint for this Segment in the Participant's list of all "Datapoint"s (all_data)
    fixation_start_ind: An integer indicating the index of the first Fixation for this Segment in the Participant's list of all "Fixation"s (fixation_data)
    fixation_end_ind: An integer indicating the index of the first Fixation for this Segment in the Participant's list of all "Fixation"s (fixation_data)
    numfixations: An integer indicating the number of "Fixation"s in this Segment
    time_gaps: a list of tuples of the form (start, end) indicating the start and end of the gaps of invalid samples in the Segement's samples
    largest_data_gap: An integer indicating the length of largest invalid gap for this Segment in milliseconds
    proportion_valid: A float indicating the proportion of valid samples over all the samples in this Segment
    proportion_valid_fix: A float indicating the proportion of (valid + restored) samples over all the samples in this Segment 
    validity1: a boolean indicating whether this Segment is valid using proportion of valid samples threshold 
    validity2: a boolean indicating whether this Segment is valid using largest acceptable gap threshold
    validity3: a boolean indicating whether this Segment is valid using proportion of (valid + restored) samples threshold
    is_valid: a boolean indicating whether this Segment is considered valid by the validity method indicated by params.VALIDITY_METHOD
    length: An integer indicating total duration of the Segment in milliseconds
    numsamples: An integer indicating total number of samples in the Segment 
    fixation_data: A list of "Fixation"s for this Segment
    fixation_start = fixation_data[0].timestamp
    $$$ Daria: fixation_start - timestamp of the first entry from list of "Fixation"s for this Segment
    fixation_end = fixation_data[-1].timestamp
    $$$ Daria: fixation_end - timestamp of the last entry from list of "Fixation"s for this Segment
    aoi_data: A list of AOI_Stat objects for relevant "AOI"s for this Segment
    has_aois: A boolean indicating if this Segment has AOI features calculated for it
 
  Methods defined here:
__init__(self, segid, all_data, fixation_data, aois=None, prune_length=None)
Args:
    segid: A string containing the id of the Segment.
    
    all_data: a list of "Datapoint"s which make up this Segment.
    
    fixation_data: a list of "Fixation"s which make up this Segment.
    
    aois: a list of "AOI"s relevant to this Segment.
 
    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 segments
        will be disregarded.
        
Yields:
    a Segment object
calc_abs_angles(self, fixdata)
returns the absolute angles between a sequence of "Fixation"s that build a scan path.
 
Abosolute angle for each saccade is the angle between that saccade and the horizental axis
 
Args:
    fixdata: a list of "Fixation"s
    
Returns:
    a list of absolute angles for the saccades formed by the given sequence of "Fixation"s in Radiant
calc_distances(self, fixdata)
returns the Euclidean distances between a sequence of "Fixation"s
 
Args:
    fixdata: a list of "Fixation"s
calc_largest_validity_gap(self, all_data)
Calculates the largest gap of invalid samples in the "Datapoint"s for this Segment.
 
Args:
    all_data: The list of "Datapoint"s which make up this Segement
    
Returns:
    An integer indicating the length of largest invalid gap for this Segment in milliseconds
calc_num_samples(self, all_data)
Returns the number of samples in the Segment
 
Args:
    all_data: a list of "Datapoint"s which make up this Segment.
    
Returns:
    An integer determining the number of samples in the Segment
calc_rel_angles(self, fixdata)
returns the relative angles between a sequence of "Fixation"s that build a scan path in Radiant
 
Relative angle for each saccade is the angle between that saccade and the previous saccade.
 
Args:
    fixdata: a list of "Fixation"s
    
Returns:
    a list of relative angles for the saccades formed by the given sequence of "Fixation"s in Radiant
calc_validity1(self, threshold=0.84999999999999998)
Returns a boolean indicating whether this Segment is valid using proportion of valid samples threshold
 
Args:
    threshold:
    $$$ Daria: threshold: the minimum proportion of valid samples for a Segment or Scene to be considered valid.
    $$$ By default set to value VALID_PROP_THRESH from module params.py
calc_validity2(self, threshold=3000)
Returns a boolean indicating whether this Segment is valid using largest acceptable gap threshold
calc_validity3(self, threshold=0.84999999999999998)
Returns a boolean indicating whether this Segment is valid using proportion of (valid + restored) samples threshold
calc_validity_fixation(self, all_data)
Calculates the proportion of (valid + restored) "Datapoint"s over all "Datapoint"s of the Segment.
 
Restored samples are the samples which are not valid but they are part of a Fixation.
The idea is that if the user was looking at a certain point and then we loose the eye data for 
a short period of time and afterwards the user is looking at the same point we can assume that user
was looking at that same point during that period. 
 
Args:
    all_data: The list of "Datapoint"s which make up this Segement
    
Returns:
    A float indicating the proportion of (valid + restored) samples over all the samples in this Segment
calc_validity_proportion(self, all_data)
Calculates the proportion of "Datapoint"s which are valid.
 
Args:
    all_data: The list of "Datapoint"s which make up this Segement
    
Returns:
    A float indicating the proportion of valid samples over all the samples in this Segment
get_features(self, featurelist=None, aoifeaturelist=None, aoifeaturelabels=None)
Returns feature names and their values for this Segment
 
Args:
    featurelist: if not None, a list containing the name of features to be returned. If this is None all features will be returned
    aoifeaturelist: if not None, a list of features to be returned for each of the "AOI"s relevant to this Segment
    aoifeaturelabels: if not None, a list of AOI related features to be returned.
    *Note: while aoifeaturelist is a subset of features that will be returned for all relevant "AOI"s, aoifeaturelabels contains 
    the exact AOI feature name, i.e., a feature of the form: [AOI name]_[feature name]
    For example if an AOI called 'graph' is releveant to this Segment, aoifeaturelabels may contain 'graph_fixationrate'  
    
Returns:
    featnames: a list of feature names sorted alphabetically
    featvals: a corrsponding list of feature values
    e.g.
    featnames = ['fixationrate', 'length', 'meanabspathangles']
    featvals  = [0.00268522882294', '1529851', '1.60354714212']
get_indices(self)
Returns the index features
 
Returns:
    An integer indicating the index of the first Datapoint for this Segment in the Participant's list of all "Datapoint"s (all_data) 
    An integer indicating the index of the last Datapoint for this Segment in the Participant's list of all "Datapoint"s (all_data)
    An integer indicating the index of the first Fixation for this Segment in the Participant's list of all "Fixation"s (fixation_data)
    An integer indicating the index of the first Fixation for this Segment in the Participant's list of all "Fixation"s (fixation_data)   
    
Raises:
    Exception: An exception is thrown if the values are read before initialization
get_validity(self)
Determines if this Segment is valid with the given validity method set in params.VALIDITY_METHOD
 
Returns:
    A boolean indicating whether this Segment is valid
getgaps(self)
Returns the list of invalid gaps for this Segment
 
Args:
    a list of invalid gaps for this Segment
getid(self)
Returns the segid for this Segment
 
Returns: a string conataining the segid for this Segment
print_(self)
Ourputs all feature names and their values for this Segment on the console
set_aois(self, aois, fixation_data)
Sets the relevant "AOI"s for this Segment
 
Args:
    fixation_data: The list of "Fixation"s which make up this Segment
    aois: a list of "AOI"s relevant to this Segment
set_indices(self, sample_st, sample_end, fix_st, fix_end)
Sets the index features
 
Args:
    sample_st: An integer indicating the index of the first Datapoint for this Segment in the Participant's list of all "Datapoint"s (all_data) 
    sample_end: An integer indicating the index of the last Datapoint for this Segment in the Participant's list of all "Datapoint"s (all_data)
    fix_st: An integer indicating the index of the first Fixation for this Segment in the Participant's list of all "Fixation"s (fixation_data)
    fix_st: An integer indicating the index of the first Fixation for this Segment in the Participant's list of all "Fixation"s (fixation_data)

 
Functions
       
warn(...)
Issue a warning, or maybe ignore it or raise an exception.