Scene
index
c:\temp\skardan\workspace\python\emdat\src\scene.py

UBC Eye Movement Data Analysys Toolkit
Created on 2011-09-30
 
@author: skardan

 
Modules
       
geometry
math
params

 
Classes
       
Segment.Segment
Scene

 
class Scene(Segment.Segment)
    Scene is a class that represent one scene in the experiment.
 
Scene is a class that represent one scene in the experiment. The Scene is designed to capture all "Datapoint"s related to a target
conceptual entity in the experiment. A Scene should have at least one Segment assigned to it. The Scene class is also used to 
combine multiple "Segment"s and calculate the aggregated statistics for this new entity as a whole. This class is the equivalent
of scenes as defined in Tobii studio.
 
Attributes:
    scid: a string containing the Scene ids
    segments: a list of "Segment"s for this Scene
    
Attributes inherited from Segment:
    alldata: A list of "Datapoint"s for this Scene
    features: A dict with feature names as its keys and feature values as its values 
    completion_time: An integer indicating total duration of the Scene in milliseconds
        minimum is 16 ms (ength of one sample with 60Hz sampling rate (ms)
    start:An integer indicating the Scene's start time in milliseconds
    end: An integer indicating the Scene's end time in milliseconds
    sample_start_ind: An integer indicating the index of the first Datapoint for this Scene 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 Scene 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 Scene 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 Scene in the Participant's list of all "Fixation"s (fixation_data)
    numfixations: An integer indicating the number of "Fixation"s in this Scene
    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 Scene in milliseconds
    proportion_valid: A float indicating the proportion of valid samples over all the samples in this Scene
    proportion_valid_fix: A float indicating the proportion of (valid + restored) samples over all the samples in this Scene 
    validity1: a boolean indicating whether this Scene is valid using proportion of valid samples threshold 
    validity2: a boolean indicating whether this Scene is valid using largest acceptable gap threshold
    validity3: a boolean indicating whether this Scene is valid using proportion of (valid + restored) samples threshold
    is_valid: a boolean indicating whether this Scene is considered valid by the validity method indicated by params.VALIDITY_METHOD
    length: An integer indicating total duration of the Scene in milliseconds
    numsamples: An integer indicating total number of samples in the Scene 
    fixation_data: A list of "Fixation"s for this Scene
    fixation_start = fixation_data[0].timestamp
    fixation_end = fixation_data[-1].timestamp
    aoi_data: A list of AOI_Stat objects for relevants "AOI"s for this Scene
    has_aois: A boolean indicating if this Scene has AOI features calculated for it
 
  Methods defined here:
__init__(self, scid, seglist, all_data, fixation_data, Segments=None, aoilist=None, prune_length=None, require_valid=True, auto_partition=False)
Args:
    scid: A string containing the id of the Scene.
    
    seglist: a list of tuples of the form (segid, start, end) defining the segments
    *Note: this method of defining segments is implemented to make batch processing of
    files defining segments easier
    
    all_data: a list of "Datapoint"s which make up this Scene.
    
    fixation_data: a list of "Fixation"s which make up this Scene.
    
    Segments: a list of "Segment"s which belong to this Scene.
                 
    aoilist: If not None, a list of "AOI"s.
     
    prune_length: If not None, an integer that specifies the time 
        interval (in ms) from the begining of each Segment of this Scene
        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: 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 ssub "Segment"s discarding the largest invalid sample gap in 
        the "Segment". default = False
Yields:
    a Scene object
calc_abs_angles(self, fixdatalists)
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:
    fixdatalists: a list of lists 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, fixdatalists)
returns the Euclidean distances between a sequence of "Fixation"s
 
Args:
    fixdatalists: a list of lists of "Fixation"s
calc_rel_angles(self, fixdatalists)
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:
    fixdatalists: a list of lists of  "Fixation"s
    
Returns:
    a list of relative angles for the saccades formed by the given sequence of "Fixation"s in Radiant
getid(self)
Returns the scid for this Scene
 
Returns: a string conataining the scid for this Scene
set_aois(self, segments, aois)
Sets the "AOI"s relevant to this Scene
 
Args:
    segments: a list of "Segment"s which belong to this Scene.
 
    aois: a list of "AOI"s relevant to this Scene

Methods inherited from Segment.Segment:
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_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
print_(self)
Ourputs all feature names and their values for this Segment on the console
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
       
maxfeat(obj_list, feat)
a helper method that calculates the max of a target feature over a list of objects
 
Args:
 
    obj_list: a list of objects
    
    feat: a string containing the name of the target feature
 
Returns:
    the max of the target feature over the given list of objects
merge_aoistats(main_AOI_Stat, new_AOI_Stat, total_time, total_numfixations)
a helper method that updates the AOI_Stat object of this Scene with a new AOI_Stat object
 
Args:
    main_AOI_Stat: AOI_Stat object of this Scene
    
    new_AOI_Stat: a new AOI_Stat object
    
    total_time:
    
    total_numfixations:
 
Returns:
    the updated AOI_Sata object
minfeat(obj_list, feat)
a helper method that calculates the min of a target feature over a list of objects
 
Args:
 
    obj_list: a list of objects
    
    feat: a string containing the name of the target feature
 
Returns:
    the min of the target feature over the given list of objects
sumfeat(obj_list, feat)
a helper method that calculates the sum of a target feature over a list of objects
 
Args:
 
    obj_list: a list of objects
    
    feat: a string containing the name of the target feature
 
Returns:
    the sum of the target feature over the given list of objects
warn(...)
Issue a warning, or maybe ignore it or raise an exception.
weightedmeanfeat(obj_list, totalfeat, ratefeat)
a helper method that calculates the weighted average of a target feature over a list of Segments
 
Args:
    obj_list: a list of Segments which all have a numeric field for which the weighted average is calculated 
    
    totalfeat: a string containing the name of the feature that has the total value of the target feature 
    
    ratefeat: a string containing the name of the feature that has the rate value of the target feature
 
Returns:
    the weighted average of the ratefeat over the Segments