gazelib package¶
Subpackages¶
Submodules¶
gazelib.containers module¶
Classes that store the gaze data and can be fed to analysis functions.
-
class
gazelib.containers.
CommonV1
(raw_common_or_filepath=None)[source]¶ Bases:
object
-
exception
EmptyContainerException
[source]¶ Bases:
exceptions.Exception
Raised if there is not enough content for a CommonV1 method. For example get_relative_start_time cannot return anything if there is no timelines or they are empty.
-
exception
CommonV1.
InsufficientDataException
[source]¶ Bases:
exceptions.Exception
Raised if container does not provide required data. For example if some streams are missing.
-
exception
CommonV1.
InvalidEventException
[source]¶ Bases:
exceptions.Exception
Raised if an event does not fit the CommonV1 specification.
-
exception
CommonV1.
InvalidRangeException
[source]¶ Bases:
exceptions.Exception
Raised if invalid range index pair were given. E.g. start > end
-
exception
CommonV1.
InvalidStreamException
[source]¶ Bases:
exceptions.Exception
Raised if a stream does not fit the CommonV1 specification.
-
exception
CommonV1.
InvalidTimeException
[source]¶ Bases:
exceptions.Exception
Raised if a time is not an integer.
-
exception
CommonV1.
InvalidTimelineException
[source]¶ Bases:
exceptions.Exception
Raised if a timeline does not fit the CommonV1 specification.
-
exception
CommonV1.
MissingEnvironmentException
[source]¶ Bases:
exceptions.Exception
Raised if a given environment name cannot be found.
-
exception
CommonV1.
MissingStreamException
[source]¶ Bases:
exceptions.Exception
Raised if a given stream name cannot be found.
-
exception
CommonV1.
MissingTagException
[source]¶ Bases:
exceptions.Exception
Raised if a given event tag cannot be found
-
exception
CommonV1.
MissingTimelineException
[source]¶ Bases:
exceptions.Exception
Raised if a given timeline name cannot be found.
-
CommonV1.
SCHEMA
= {'$schema': 'http://json-schema.org/draft-04/schema#', 'required': ['schema', 'time_reference', 'environment', 'timelines', 'streams', 'events'], 'type': 'object', 'properties': {'environment': {'patternProperties': {'.+': {}}, 'type': 'object'}, 'time_reference': {'type': 'integer'}, 'streams': {'patternProperties': {'.+': {'required': ['timeline', 'values'], 'type': 'object', 'properties': {'timeline': {'type': 'string'}, 'confidence': {'items': {'minimum': 0.0, 'type': 'number', 'maximum': 1.0}, 'type': 'array'}, 'derived': {'type': 'string'}, 'values': {'type': 'array'}}}}, 'type': 'object'}, 'timelines': {'patternProperties': {'.+': {'items': {'type': 'integer'}, 'type': 'array'}}, 'type': 'object'}, 'events': {'items': {'required': ['tags', 'range'], 'type': 'object', 'properties': {'range': {'items': {'type': 'number'}, 'type': 'array'}, 'extra': {}, 'derived': {'type': 'string'}, 'tags': {'items': {'type': 'string'}, 'type': 'array'}}}, 'type': 'array'}, 'schema': {'pattern': 'gazelib/common/v1', 'type': 'string'}}, 'title': 'gazelib/common/v1'}¶
-
CommonV1.
add_environment
(env_name, env_value)[source]¶ Add new environment.
- Parameters:
- env_name
- A string, the name of the environment. Use of semantic names is recommended.
- env_value
- Any type of JSON-compatible object.
-
CommonV1.
add_event
(tags, start_time, end_time, derived=None, extra=None)[source]¶ Add new event.
- Parameters:
- tags
- A list of tag strings.
- start_time
- A relative time in microseconds. The starting time of event.
- end_time
- A relative time in microseconds. The ending time of event.
- derived
- Optional name of function that was used to derive the event.
- extra
- An optional place for extra info. Typically a dict.
-
CommonV1.
add_stream
(stream_name, timeline_name, values, confidence=None)[source]¶ Add a new sequence of sampled data.
- Parameters:
- stream_name
- A string. It is advisable to use semantic names.
- timeline_name
- The name of the timeline that contains the sampling times of the values.
- values
- An iterable of values. The length cannot be larger than the length of the timeline.
- confidence
- An optional iterable of confidence values. The confidencies must be inclusively within 0.0 and 1.0.
-
CommonV1.
add_timeline
(timeline_name, timeline_values)[source]¶ Add a new timeline.
- Parameters:
- timeline_name
- A string that will be referenced from the streams.
- timeline_values
- An iterable of integer microseconds. Will be converted to list.
-
CommonV1.
assert_has_environments
(env_names)[source]¶ Raises CommonV1.InsufficientDataException if the any of the given environments is missing from the container. This is used in analysis scripts that require certain environments.
-
CommonV1.
assert_has_streams
(stream_names)[source]¶ Raises CommonV1.InsufficientDataException if the any of the given streams is missing from the container. This is used in analysis scripts that require certain streams.
-
CommonV1.
assert_range_order
(start, end, start_name, end_name)[source]¶ Raise InvalidRangeException if start larger or equal than end.
-
CommonV1.
convert_to_relative_time
(unix_time_micros)[source]¶ Return relative time in microseconds (int)
-
CommonV1.
count_events
(tag=None)[source]¶ Return integer, number of stored events. If the optional tag is given, count only events with the tag.
-
CommonV1.
get_duration
()[source]¶ Difference in microseconds between the smallest and largest time point.
-
CommonV1.
get_event_by_tag
(tag, index=0)[source]¶ Return event that has the given tag. By default the first occurence is returned.
Raise MissingTagException if no events are found. Raise IndexError if tags found but index out of range.
-
CommonV1.
get_relative_end_time
()[source]¶ Find the largest time in the container as relative time. Can be negative.
-
CommonV1.
get_relative_start_time
()[source]¶ Find he smallest time in the container as relative time. Can be negative.
-
CommonV1.
get_relative_time_by_index
(timeline_name, index)[source]¶ Return relative time on the timeline at index.
-
CommonV1.
get_stream
(stream_name)[source]¶ Return: CommonV1 stream dict. Raise: CommonV1.MissingStreamException: if name not found.
-
CommonV1.
get_stream_timeline_name
(stream_name)[source]¶ Return: the timeline name associated with the stream. Raise: CommonV1.MissingStreamException: if name not found.
-
CommonV1.
get_stream_values
(stream_name)[source]¶ Return: the full list of values of the stream. Raise: CommonV1.MissingStreamException: if name not found.
-
CommonV1.
get_timeline
(timeline_name)[source]¶ - Return:
- timeline i.e. a list of relative times.
- Raise:
- CommonV1.MissingTimelineException: if name not found.
-
CommonV1.
get_timeline_mean_interval
(timeline_name)[source]¶ Return mean interval in microseconds, measured over the timeline.
-
CommonV1.
has_environments
(env_names)[source]¶ Test if environments are available.
- Parameter:
- env_names, list of strings
- Return:
- True, if all the given environments are available. False, otherwise
-
CommonV1.
has_streams
(stream_names)[source]¶ Test if streams are available.
- Parameter:
- stream_names, list of strings
- Return:
- True, if all the given streams are available. False, otherwise
-
CommonV1.
iter_by_tag
(tag, limit_to=None)[source]¶ DEPRECATED as too vague. Use iter_slices_by_tag instead.
-
CommonV1.
iter_events_by_tag
(tag)[source]¶ Yield events that have the tag. Raise MissingTagException if no events found.
Yield events that have at least one of the tags. For example, used internally by save_events_as_csv(tags)
- Parameters:
- tags: a list of tags
If no such events found, iter []
-
CommonV1.
iter_slices_by_tag
(tag, limit_to=None)[source]¶ Slice to multiple portions. E.g. if there is ten events with “trial” tag, returns iterable over ten slices, one for each tag.
- Parameters
- tag
- string
- limit_to
- max number of slices to return. By default returns all.
- Return
- iterable of CommonV1 objects
If no such slices found, iter []
Return list of unique tags in the events. Order is not defined.
-
CommonV1.
save_as_json
(target_file_path, human_readable=False)[source]¶ Store the content in gazelib/common/v1 in a JSON file.
- Parameters:
- target_file_path
- Absolut or relative file path as string.
- human_readable
- Set True for new lines and indentation. Default to False.
-
CommonV1.
save_events_as_csv
(tags, target_file_path, delimiter='\t')[source]¶ - Save CSV file with each event as row and with columns:
- start_time: event start time in unix time end_time: event end time in unix time <1st tag>: 1 = event has tag, 0 = event does not have this tag <2nd tag>: ...
The file includes header row.
-
CommonV1.
save_timeline_as_csv
(timeline_name, target_file_path, delimiter='\t')[source]¶ Store timeline and its associated streams in a comma separated values format. Note that neither events nor environments are included.
-
CommonV1.
set_time_reference
(microseconds_from_epoch)[source]¶ Can be used to anonymize data.
- Parameter:
- microseconds_from_epoch, integer.
- Raise:
- InvalidTimeException if not integer.
-
CommonV1.
slice_by_relative_time
(rel_start_time, rel_end_time=None)[source]¶ Return new CommonV1 object with data only in the time range. Will slice events that are partially outside. Will remove empty streams and events that are completely outside. Will remove empty timelines Does not update time_reference because easier implementation and more efficient execution.
-
CommonV1.
slice_by_tag
(tag, index=0)[source]¶ - Parameters:
- tag index
- Return:
- CommonV1 instance
- that has data only during the tagged event.
Raise MissingTagException if no events with given tag found. Raise IndexError if tag found but index out of range.
-
CommonV1.
slice_by_timeline
(timeline_name, start_index, end_index=None)[source]¶ Return new CommonV1 object with data only in the time range specified by the indices of the timeline.
- Parameters:
timeline_name: string start_index: inclusive end_index:
Optional, exclusive, first element to not be included. If None given, slice to the end.
-
CommonV1.
slice_by_unix_time
(start_time, end_time=None)[source]¶ - Parameters:
- start_time: unix time in microseconds end_time: unix time in microseconds
Return new CommonV1 object with data only from the time range.
-
exception
gazelib.io module¶
Input-Output functions that help to read and write gaze data.
-
gazelib.io.
load_csv_as_dictlist
(filepath, delimiter='\t')[source]¶ Load a file in csv (common in .gazedata) and return data as list of dicts. Each dict contains the column names as keys and cell values as dict values.
Raise IOError if filepath is invalid Raise ValueError if file is not CSV formatted.
-
gazelib.io.
load_json
(filename)[source]¶ Load json-type file and return its contents as python object.
Raise IOError if loading failed. Raise ValueError if JSON decoding failed.
Note: IOError might vary between environments. See: http://stackoverflow.com/q/15032108/638546
-
gazelib.io.
write_dictlist_as_csv
(target_filename, dictlist, headers=None, delimiter='\t')[source]¶ Write given list of dicts to a file as CSV. Each dict is required to have key for each column name. The column names are read from the first dict.
- Parameters:
- target_filename:
- A path to target file
- dictlist:
- A list of dicts. Each dict is required to have same set of keys.
- headers:
- Optional list of keys. Defines the order of columns.
- delimiter:
- Delimiter character.
gazelib.package module¶
gazelib.settings module¶
Gazelib settings
gazelib.validation module¶
Format validation.
-
gazelib.validation.
has_keys
(dict, keys)[source]¶ - Parameter
- dict, dict to examine keys, a list of strings
- Return
- true, if all given keys are found from the dict. false, otherwise
-
gazelib.validation.
has_only_keys
(dict, keys)[source]¶ Return true if obj has all and only the given keys.
Module contents¶
Gazelib, a toolkit for gaze analysis.