gazelib package

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.convert_to_unix_time(relative_time_micros)[source]

Return unix 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_environment(env_name)[source]

Return value of the environment.

CommonV1.get_environment_names()[source]

DEPRECATED: Use list_environment_names instead

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_names()[source]

DEPRECATED: Use list_stream_names instead

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_time_reference()[source]

Return the time reference as microseconds from unix epoch.

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()[source]

Iterate over each event. See list_events to get list directly.

CommonV1.iter_events_by_tag(tag)[source]

Yield events that have the tag. Raise MissingTagException if no events found.

CommonV1.iter_events_by_tags(tags)[source]

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 []

CommonV1.list_environment_names()[source]

Return list of names of provided environments.

CommonV1.list_events()[source]

Return full list of events

CommonV1.list_stream_names()[source]

Return list of names of provided streams.

CommonV1.list_tags()[source]

Return list of unique tags in the events. Order is not defined.

CommonV1.list_timeline_names()[source]

Return list of names of stored timelines.

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.

CommonV1.slice_first_microseconds(n)[source]
Parameters:
n: <integer> microseconds
Return:
CommonV1 instance
that has data only from the first n microseconds, counted from the beginning of the slice.
static CommonV1.validate(raw_common)[source]

Raises ValidationError if raw_common is not valid gazelib/common/v1

gazelib.containers.get_current_time_reference()[source]

Get current POSIX time in microseconds

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.io.write_fancy_json(filename, data)[source]

Write JSON so that it is readable by humans (new lines, indent..).

Raise (see write_json)

gazelib.io.write_json(filename, data, human_readable=False)[source]

Dump data to a given JSON file. File is created if it does not exist.

Raise TypeError if data is not serializable.

gazelib.package module

gazelib.settings module

Gazelib settings

gazelib.validation module

Format validation.

exception gazelib.validation.ValidationException[source]

Bases: exceptions.Exception

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.

gazelib.validation.is_integer(n)[source]

See also http://stackoverflow.com/a/3501408/638546

gazelib.validation.is_list_of_strings(l)[source]
gazelib.validation.is_real(r)[source]

Return true if r is real number

gazelib.validation.is_string(s)[source]

Return true if s is string or similar.

Module contents

Gazelib, a toolkit for gaze analysis.