dispel.providers.generic.touch module#

The touch module provides general abstraction classes to handle touch events.

Touch events are represented in Touchs and Gestures that represent one consecutive interaction (touch down to touch up) and overlapping interactions, respectively.

class dispel.providers.generic.touch.Gesture[source]#

Bases: object

A collection of overlapping Touch interactions.

TOUCH_CLS#

The class used to create touches in touch_factory().

alias of Touch

__init__(touches)#

Parameters:: touches (Sequence[Touch]) –
Return type:: None

property begin: datetime#: Get the start date time of the gesture.

property duration: timedelta#: Get the duration of the gesture.

property dwell_time: timedelta#

Get the dwell time of the gesture.

Returns:: The time spent between the first touch on the screen and the first movement made after that.
Return type:: datetime.timedelta

property end: datetime#: Get the end date time of the gesture.

property first_movement: Touch#: Get the first moved touch interaction.

property first_touch: Touch#: Get the first touch interaction.

classmethod from_data_frame(data, **kwargs)[source]#

Create gestures from a data frame.

Parameters:

data (DataFrame) – A data frame containing touch events.
kwargs – Additional key word arguments passed to Gesture.gesture_factory().

Returns:

A sequence of gestures based on the provided data. The data frame is split according to the touchPathId into separate touch interactions. Consecutively overlapping touches are combined as gestures.

Return type:

List[Gesture]

classmethod gesture_factory(touches, **kwargs)[source]#

Get a gesture instance for a list of touches.

This method can be overwritten by inheriting classes to customize how gestures are constructed.

Parameters:

touches (Sequence[Touch]) – The results from the touch factory. See touch_factory() for details.
kwargs – Additional key word arguments for overridden methods to eventually use.

Returns:

The gesture representing the passed Touch objects in touches.

Return type:

Gesture

property last_touch: Touch#: Get the last touch interaction.

property movement_begin: datetime#

Get the start of the movement for the gesture.

Returns:: The date time of the first recorded movement of the gesture.
Return type:: datetime.datetime

classmethod touch_factory(touch_data, pointer)[source]#

Get a touch instance for touch data frame.

This method can be overwritten by inheriting classes to customize how touches are constructed.

Parameters:

touch_data (DataFrame) – The touch events for one consecutive touch interaction from one pointer.
pointer (Pointer) – The pointer of the touch events

Returns:

A touch interaction of a single pointer

Return type:

Touch

touches: Sequence[Touch]#: The touch interactions comprising the gesture

class dispel.providers.generic.touch.Pointer[source]#

Bases: object

Touch pointer reference.

__init__(index=0)#

Parameters:: index (int) –
Return type:: None

index: int = 0#: The index of the pointer

dispel.providers.generic.touch.TOUCH_ACTIONS = namespace(up='up', down='down', move='move')#: List of possible touch actions.

dispel.providers.generic.touch.TOUCH_COLUMNS = ['xPosition', 'yPosition', 'touchAction', 'tsTouch', 'touchPathId', 'pressure']#: The valid column names to use the touch module.’

class dispel.providers.generic.touch.Touch[source]#

Bases: object

A consecutive interaction with the screen.

The Touch represents the touch events of one consecutive interaction with the screen from the first down action until the up action.

__init__(data, pointer=UnknownPointer(index=0))#

Parameters:

data (dataclasses.InitVar[DataFrame]) –
pointer (Pointer) –

Return type:

None

property acceleration: Series#

Get the pointer acceleration during the interaction.

Returns:: The change of velocity over time.
Return type:: pandas.Series

property begin: datetime#

Get the start of the touch.

Returns:: The date time of the first touch event
Return type:: datetime.datetime

data: dataclasses.InitVar[DataFrame]#

property displacements: DataFrame#

Get the displacements per touch event.

Returns:: Returns the changes in position in x and y direction at each touch event.
Return type:: pandas.DataFrame

property duration: timedelta#

Get the duration of the touch.

Returns:: The duration of the touch interaction from its start to its end.
Return type:: datetime.timedelta

property end: datetime#

Get the end of the touch.

Returns:: The date time of the last touch event
Return type:: datetime.datetime

property first_position: Tuple[float, float]#

Get the first position of the touch interaction.

Returns:: The x and y coordinate of the first touch interaction with the screen.
Return type:: Tuple[float, float]

get_data()[source]#

Get a copy of the touch data frame.

Return type:: DataFrame

property has_major_radius#: Has major radius measurements.

property has_pressure: bool#

Has the interaction pressure information.

Returns:: True if pressure information is available. Otherwise, False
Return type:: bool

property initial_pressure: float#

Get the initially exerted pressure of the pointer.

Returns:: The pressure exerted on the screen upon initiation of the interaction. If the first reading was 0 the subsequent one will be returned.
Return type:: float

property is_incomplete: bool#

Is the interaction incomplete.

Returns:: Returns True if either the down or up action is not observed. Otherwise, False.
Return type:: bool

property jerk: Series#

Get the pointer jerk during the interaction.

Returns:: The change of acceleration over time.
Return type:: pandas.Series

property length: float#

Get the length of the interaction.

Returns:: The length of the interaction based on the sum of euclidean norm vector of displacements.
Return type:: float

property major_radius: Series#: Get the major radius of the touch interaction.

property major_radius_tolerance: float#: Get the major radius tolerance property.

property mean_squared_jerk#

Get the average squared jerk.

Returns:: The average squared jerk.
Return type:: float

property mean_squared_pressure_jerk#

Get the average squared jerk of the applied pressure.

Returns:: The average squared jerk of the applied pressure.
Return type:: float

property movement_begin: datetime#

Get the start of the movement for the touch.

Returns:: The date time of the first recorded movement of the touch.
Return type:: datetime.datetime

overlaps(other)[source]#

Check if the touch has overlapping time points.

Parameters:: other (Touch) – The other touch interaction to test for overlapping.
Returns:: Returns True if the start or end of other fall within the start or end of this touch interaction (boundaries included). Otherwise, False.
Return type:: bool

pointer: Pointer = UnknownPointer(index=0)#: The pointer information of the touch interaction

property positions: DataFrame#

Get the x and y coordinates of the touch interactions.

Returns:: A data frame with two columns XPosition and yPosition and the time points as index.
Return type:: pandas.DataFrame

property pressure: Series#

Get the pressure information associated with the touch.

Returns:: The pressure values excluding 0-values at the very first reading.
Return type:: pandas.Series

property pressure_acceleration: Series#

Get the pressure acceleration.

Returns:: The second derivative of the pressure information.
Return type:: pandas.Series

property pressure_change: Series#

Get the pressure change.

Returns:: The first derivative of the pressure information.
Return type:: pandas.Series

property pressure_jerk: Series#

Get the pressure jerk.

Returns:: The change of pressure acceleration over time.
Return type:: pandas.Series

property speed: Series#

Get the pointer speed of the interaction.

Returns:: The change in position over time.
Return type:: pandas.Series

property time_deltas: Series#

Get the time differences between consecutive touch events.

Returns:: Returns a series of time differences in milliseconds between consecutive touch events with the index based on the touch event time stamp.
Return type:: pandas.Series

to_segments()[source]#

Get multi-segment representation of the touch interaction.

Return type:: Multisegment

property velocity: DataFrame#

Get the interaction velocity.

Returns:: The change in position over time for the respective axis.
Return type:: pandas.DataFrame

class dispel.providers.generic.touch.UnknownPointer[source]#

Bases: Pointer

Unknown pointer reference.

This pointer can be used if the pointer is unknown.

dispel.providers.generic.touch.reassign_touch_path_id(data)[source]#

Reassign touch path ids.

Touch path ids are sometimes mixed when there are no fingers on the screen. This function makes sure consecutive touches are assigned ascending new ids.

Parameters:: data (DataFrame | Dict[str, List]) – Dictionary of raw touch data
Returns:: Touch data for the level
Return type:: Dict[str, List]

dispel.providers.generic.touch.split_touches(raw_data, begin, end)[source]#

Split touch events.

This function reassign the touch path ids of raw touch events in a data frame by making sure that the path ids are unique and given in ascending order. One can also filter the input sequence by specifying the start and end timestamp.

Parameters:

raw_data (DataFrame) – Dataframe of the raw touch events
begin (int) – Raw timestamp of the beginning of the sequence
end (int | None) – An optional raw timestamp of the end of the sequence

Returns:

Touch data for the level

Return type:

Dict[str, List]