dispel.providers.generic.tasks.pinch.attempts module#

A module dedicated to format user pinch into attempts.

class dispel.providers.generic.tasks.pinch.attempts.PinchAttempt[source]#

Bases: Gesture

A pinching gesture.

TOUCH_CLS#: alias of PinchTouch

__init__(touches, is_valid, is_successful, top_finger, bottom_finger, pinch_begin, pinch_end)#

Parameters:

touches (Sequence[Touch]) –
is_valid (bool) –
is_successful (bool) –
top_finger (PinchTouch) –
bottom_finger (PinchTouch) –
pinch_begin (datetime) –
pinch_end (datetime) –

Return type:

None

static add_is_valid_pinch(first, second, target_radius, target_coords)[source]#

Add is valid pinch variable to the given touches.

Parameters:

first (PinchTouch) – The first pinch touch.
second (PinchTouch) – The second pinch touch.
target_radius (float) – The radius of the pinch target.
target_coords (Tuple[float, float]) – The coordinates of the pinch target.

Returns:

The modified given pinch touches.

Return type:

Tuple[PinchTouch, PinchTouch]

bottom_finger: PinchTouch#: The bottom finger touch interaction

property double_touch_asynchrony: timedelta#

Get the double touch asynchrony of the pinch attempt.

Returns:: The time difference between the first and second finger touching the screen for a pinch attempt.
Return type:: datetime.timedelta

property first_push_bottom_fingers: float#

Get the first pressure measurement of the bottom finger.

Returns:: The first pressure reading from the bottom finger that was non-zero.
Return type:: float

property first_push_top_fingers: float#

Get the first pressure measurement of the top finger.

Returns:: The first pressure reading from the top finger that was non-zero.
Return type:: float

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

Create PinchAttempt from a data frame.

Parameters:

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

Returns:

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

Return type:

List[PinchAttempt]

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

Get a pinch attempt gesture from touches.

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

is_successful: bool#: Is successful if the gesture led to the burst of the target

is_valid: bool#: Is valid if it is comprised of two touch interactions

pinch_begin: datetime#: The time stamp when the pinching started

pinch_end: datetime#: The time stamp when the pinching ended

property pinching_duration: timedelta#

Get the duration of the pinching.

Returns:: Returns the duration of the pinching if the gesture is considered a valid pinch based on pinch_begin and pinch_end. If the pinch is not valid according to the app (isValidPinch in the screen data set is false) it returns None.
Return type:: datetime.timedelta

top_finger: PinchTouch#: The top finger touch interaction

class dispel.providers.generic.tasks.pinch.attempts.PinchTarget[source]#

Bases: object

A pinch target class.

This encapsulates pinch targets for each level e.g. ‘right-small’, ‘right-small-01’ etc.

id#

The pinch target identifier e.g. ‘right-small-01’.

Type:: str

parent_id#

The pinch target parent identifier e.g. ‘right-small’.

Type:: str

hand#

The hand used for the pinch.

Type:: HandModality

size#

The target bubble size.

Type:: BubbleSizeModality

radius#

The radius of the pinch target.

Type:: float

coordinates#

The coordinates of the pinch target.

Type:: Tuple[float, float]

appearance#

The timestamp at which the target initially appeared.

Type:: pandas.Timestamp

attempts#

A list of the pinch attempts for the current target.

Type:: List[PinchAttempt]

__init__()[source]#

contact_coordinates_bottom_fingers(outcome=AttemptOutcomeModality.ALL)[source]#

Get the attempts contact coordinates for bottom fingers.

Parameters:: outcome (AttemptOutcomeModality) –
Return type:: List[Tuple[float, float]]

contact_coordinates_top_fingers(outcome=AttemptOutcomeModality.ALL)[source]#

Get the attempts contact coordinates for top fingers.

Parameters:: outcome (AttemptOutcomeModality) –
Return type:: List[Tuple[float, float]]

contact_distances(finger, outcome=AttemptOutcomeModality.ALL)[source]#

Get contact distances for fingers.

Parameters:

finger (FingerModality) –
outcome (AttemptOutcomeModality) –

Return type:

List[float]

property first_attempt: PinchAttempt#: Get the first pinch attempt.

first_pushes(finger, outcome=AttemptOutcomeModality.ALL)[source]#

Get the first pushes of a pinch target’s fingers attempts.

Parameters:

finger (FingerModality) –
outcome (AttemptOutcomeModality) –

Return type:

List[float]

classmethod from_level(level)[source]#

Initialize pinch target from level.

Parameters:: level (Level) – The level from which the pinch target is to be initialized.
Returns:: The pinch target.
Return type:: PinchTarget
Raises:: ValueError – If the PinchTarget id doesn’t start with a hand-size format

get_attempts_from(modality)[source]#

Get the list of attempts from success pinche modality.

Parameters:: modality (AttemptOutcomeModality) –
Return type:: List[PinchAttempt]

get_contact_distance(finger_coordinates)[source]#

Get contact distance given contact coordinates.

The contact distance is the euclidean distance between the finger coordinates and the surface of the pinch target i.e. the distance between the finger coordinates and the target center coordinates minus the radius of the target.

Parameters:: finger_coordinates (Tuple[float, float]) – The coordinates of the finger.
Returns:: The contact distance for the given finger coordinates.
Return type:: float

property has_attempts: bool#: Get whether the pinch target has attempts.

property reaction_time: Timedelta#: Get the user reaction time.

property total_duration: timedelta#: Get the total duration of the pinch attempts.

class dispel.providers.generic.tasks.pinch.attempts.PinchTouch[source]#

Bases: Touch

A pinch touch interaction.

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

Parameters:

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

Return type:

None

is_successful: bool#: Is successful if the gesture of the touch led to the burst of the target

property is_valid_pinch_exists: bool#: Check whether is valid pinch variable exists in touch data frame.

property pinch_begin: datetime#

Get the start of the pinching.

Returns:: The time stamp when the pinching started.
Return type:: datetime.datetime

property pinch_end: datetime#

Get the start of the pinching.

Returns:: The time stamp when the pinching started.
Return type:: datetime.datetime

set_is_valid_pinch(is_valid_pinch)[source]#

Set is valid pinch variable inside touch data frame.

Parameters:: is_valid_pinch (Series) – A pandas series containing isValidPinch boolean values and time stamps as indexes.

property valid_pinch_timestamps: Series#

Get the valid pinching time stamps.

Returns:: The timestamps of the valid pinching moments.
Return type:: pandas.Series
Raises:: KeyError – If isValid Pinch is missing from the touch data frame.

dispel.providers.generic.tasks.pinch.attempts.double_touch_asynchrony(target, attempt)[source]#

Compute the pinching attempts’ double touch asynchrony.

The double touch asynchrony i.e. time difference between the first and second finger touching the screen for all pinch attempts.

Parameters:

target (PinchTarget) – A pinch target object.
attempt (AttemptSelectionModality) – Pinching attempt selection modality.

Returns:

A list regrouping the computed double touch asynchrony in ms.

Return type:

List[float]

dispel.providers.generic.tasks.pinch.attempts.dwell_time(target, attempt)[source]#

Compute the pinching attempts’ dwell times.

The dwell time i.e. time spent between the first screen touching and the initiation of the movement.

Parameters:

target (PinchTarget) – A pinch target object.
attempt (AttemptSelectionModality) – Pinching attempt selection modality.

Returns:

A list regrouping the computed dwell times in ms.

Return type:

List[float]

dispel.providers.generic.tasks.pinch.attempts.number_successful_pinches(target)[source]#

Return number of successful pinches.

A pinch is defined as a potential pinch with at least one touch event marked with ledToSuccess.

Parameters:: target (PinchTarget) – A pinch target object.
Returns:: Number of successful pinches
Return type:: int

dispel.providers.generic.tasks.pinch.attempts.pinching_duration(target, modality=AttemptOutcomeModality.ALL)[source]#

Compute the pinching duration.

The pinching duration i.e. the duration spent actually deforming the bubble.

Parameters:

target (PinchTarget) – A pinch target object.
modality (AttemptOutcomeModality) – Pinching attempt success modality.

Returns:

A list regrouping the computed pinching durations in s.

Return type:

List[float]

dispel.providers.generic.tasks.pinch.attempts.reaction_time(target)[source]#

Compute the reaction time.

The reaction time of the user between the bubble appearance and the first touch event.

Parameters:: target (PinchTarget) – A pinch target object.
Returns:: The user reaction time in ms.
Return type:: float

dispel.providers.generic.tasks.pinch.attempts.success_duration(target, modality=AttemptOutcomeModality.ALL)[source]#

Compute the success duration.

The success duration i.e. the duration spent before succeeding at pinching a bubble.

Parameters:

target (PinchTarget) – A pinch target object.
modality (AttemptOutcomeModality) – Pinching attempt success modality.

Returns:

A list regrouping the computed success durations in s.

Return type:

List[float]

dispel.providers.generic.tasks.pinch.attempts.total_duration(target)[source]#

Compute the total duration of the pinch attempts.

Parameters:: target (PinchTarget) – A pinch target object.
Returns:: The computed total duration in s.
Return type:: float

dispel.providers.generic.tasks.pinch.attempts.total_number_pinches(target)[source]#

Return total number of pinches.

A pinch is defined as a potential pinch with at least one touch event marked with isValidPinch.

Parameters:: target (PinchTarget) – A pinch target object.
Returns:: The total number of pinches.
Return type:: int