dispel.providers.generic.tasks.draw.shapes module#

A module dedicated to format user and reference trajectories.

dispel.providers.generic.tasks.draw.shapes.AREA_RADIUS = 40#

The radius of a circle centered in the first reference point of a drawing shape that define the valid starting area.

dispel.providers.generic.tasks.draw.shapes.CTR = (319, 639)#

Corner definitions, i.e. CTL for Corner Top Left, …

dispel.providers.generic.tasks.draw.shapes.HALF_SCREEN_X = 187.5#

Define the half of the x axis of the screen.

dispel.providers.generic.tasks.draw.shapes.HALF_SCREEN_Y = 406#

Define the half of the y axis of the screen.

dispel.providers.generic.tasks.draw.shapes.SHAPE_BOUNDARIES = ((56, 319), (123, 639))#

Define boundaries of a square-like shape in order to detect if a user point is inside or outside the shape in the screen x and y axes coordinates.

dispel.providers.generic.tasks.draw.shapes.SHAPE_SIZE = {'ADS': {'infinity': 1000, 'spiral': 779, 'square_clock': 1038, 'square_counter_clock': 1038}, 'BDH': {'infinity': 641, 'spiral': 607, 'square_clock': 124, 'square_counter_clock': 124}}#

Define the number of points of the reference shape.

dispel.providers.generic.tasks.draw.shapes.bottom_left(data)[source]#

Return the bottom left part of a square-like shape (user/reference).

Parameters:

data (DataFrame) – A pandas data frame containing at least a trajectory (x and y coordinates) of a square-like shape.

Returns:

The bottom left part of the square-like shape given as input.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.bottom_right(data)[source]#

Return the bottom right part of a square-like shape (user/reference).

Parameters:

data (DataFrame) – A pandas data frame containing at least a trajectory (x and y coordinates) of a square-like shape.

Returns:

The bottom right part of the square-like shape given as input.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.check_is_in_area(ser, x_ref, y_ref)[source]#

Return if the user points are within a specific area.

The area is considered as the circle of 40 pts radius with x_ref and y_ref as its center.

Parameters:

  • ser (Series) – A pandas series corresponding to a user point.

  • x_ref (float) – The x coordinate of the reference trajectory to be considered as the center of the area.

  • y_ref (float) – The y coordinate of the reference trajectory to be considered as the center of the area.

Returns:

Whether the point is in the starting area or not.

Return type:

bool

dispel.providers.generic.tasks.draw.shapes.extract_distance_axis_sc(data, ref)[source]#

Extract the distance between draws and reference perpendicular axes.

This function is specific to the square_clock shapes.

This distance is defined as follow: the distance between a user trajectory and an encountered perpendicular axis corresponding to a 90° trajectory change of the square-like shape. If the user overshoots (goes outside the square) the 90° trajectory change, the distance will be the perpendicular projection of the most distant user point to the axis and the axis itself. If the user never overshoot (stay within the square) the axis, the considered distance will be the perpendicular projection of the closest user point of the axis and the axis itself.

Parameters:

  • data (DataFrame) – A pandas data frame composed of at least the user trajectory to consider.

  • ref (DataFrame) – A pandas data frame composed of at least the reference trajectory to consider.

Returns:

A tuple composed of the extracted aforementioned distances (for the 3 axes).

Return type:

Tuple[float, float, float]

dispel.providers.generic.tasks.draw.shapes.extract_distance_axis_scc(data, ref)[source]#

Extract the distance between draws and reference perpendicular axes.

This function is specific to the square_counter_clock shapes.

This distance is defined as follow: the distance between a user trajectory and an encountered perpendicular axis corresponding to a 90° trajectory change of the square-like shape. If the user overshoots (goes outside the square) the 90° trajectory change, the distance will be the perpendicular projection of the most distant user point to the axis and the axis itself. If the user never overshoot (stay within the square) the axis, the considered distance will be the perpendicular projection of the closest user point of the axis and the axis itself.

Parameters:

  • data (DataFrame) – A pandas data frame composed of at least the user trajectory to consider.

  • ref (DataFrame) – A pandas data frame composed of at least the reference trajectory to consider.

Returns:

A tuple composed of the extracted aforementioned distances (for the 3 axes).

Return type:

Tuple[float, float, float]

dispel.providers.generic.tasks.draw.shapes.flag_valid_area(user, reference)[source]#

Add a series named isValidArea to determine if a point is valid.

e.g. if a point or a Series of point belongs to a draw which has triggered the starting area condition.

Parameters:

  • user (DataFrame) – A pandas data frame with user trajectory, touch actions and timestamps of touch events.

  • reference (DataFrame) – The reference trajectory corresponding to the current shape.

Returns:

The same pandas data frame given as input plus a pandas Series isValidArea.

Return type:

pandas.DataFrame

Raises:

ValueError – If no down touch action is detected.

dispel.providers.generic.tasks.draw.shapes.generate_infinity()[source]#

Generate the ‘infinity’ level (shape).

Return type:

Dict[str, ndarray]

dispel.providers.generic.tasks.draw.shapes.generate_model_coordinates(level_name)[source]#

Generate the model coordinates for a given level name.

Parameters:

level_name – The name of the desired level.

Returns:

The 2 dimension numpy array corresponding to the desired level (shape).

Return type:

Dict[str, numpy.ndarray]

Raises:

ValueError – If the given level name is unrecognized.

dispel.providers.generic.tasks.draw.shapes.generate_spiral()[source]#

Generate the ‘spiral’ level (shape).

Return type:

Dict[str, ndarray]

dispel.providers.generic.tasks.draw.shapes.generate_square_clock()[source]#

Generate the ‘squareClock’ level (shape).

Return type:

Dict[str, ndarray]

dispel.providers.generic.tasks.draw.shapes.generate_square_counter_clock()[source]#

Generate the ‘squareCounterClock’ level (shape).

Return type:

Dict[str, ndarray]

dispel.providers.generic.tasks.draw.shapes.get_max_dist_corner(user, attrib, ref, corner)[source]#

Retrieve the Fréchet distance within a corner zone.

The Fréchet distance is the maximum of the minimum distance between the user and the reference trajectories based on the dynamic time warping attributions.

Parameters:

  • user (DataFrame) – The user trajectory user for computing the DTW attributions.

  • attrib (DataFrame) – The related dynamic time warping attributions for the considered reference trajectory with the user trajectory of interest.

  • ref (DataFrame) – The reference trajectory

  • corner (Tuple[int, int]) – The corner zone of the reference trajectory to consider.

Returns:

The maximum of the minimum distances from DTW attributions within the considered corner zone.

Return type:

float

dispel.providers.generic.tasks.draw.shapes.get_proper_level_to_model(level_id)[source]#

Extract the correct camel type key to explore the ‘screen’ data set.

Parameters:

level_id (str) – The desired level id to consider.

Returns:

The corresponding level id in Camel type.

Return type:

str

Raises:

KeyError – If the given identifier doesn’t match any level.

dispel.providers.generic.tasks.draw.shapes.get_reference_path(level, height)[source]#

Extract the reference trajectory x and y coordinates.

Parameters:

  • level (Level) – The desired level on which you want to compute model path.

  • height (float) – The height in pts corresponding to the screen of the user’s smartphone.

Returns:

A pandas data frame composed of the reference trajectory x and y coordinates.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.get_segment_deceleration(level_id)[source]#

Retrieve the segment of the deceleration profile of a given shape.

The aim of that is to compute intentional tremors for square-like shapes. Segments on which to compute intentional tremors have been determined by capturing the velocity profile of each shape against 50 Healthy Control Participants evaluations. For each shape, the segment is defined as model points where the mean velocity is comprised between 50% and 20% of the maximum of the velocity profile.

Parameters:

level_id (str) – The level id on which to retrieve proper the deceleration profile of the shape.

Returns:

The list of model path indexes to consider to build the signal to study intentional tremors.

Return type:

range

Raises:

KeyError – If passed level_id is not in segments.

dispel.providers.generic.tasks.draw.shapes.get_user_path(data, reference, height)[source]#

Extract user path coordinates, timestamps and touch actions.

Parameters:

  • data (DataFrame) – A pandas data frame corresponding to the ‘screen’ raw data set.

  • reference (DataFrame) – The reference trajectory corresponding to the current shape.

  • height (float) – The height in pts corresponding to the screen of the user’s smartphone.

Returns:

A pandas data frame composed of user path coordinates, timestamps, touch actions and the valid or non valid flag.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.get_valid_path(data)[source]#

Keep only the valid trajectory of the user.

Parameters:

data (DataFrame) – The pandas data frame obtained via a DrawShape.

Returns:

The pandas data frame given in input but composed of only the valid user trajectory.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.get_valid_up_sampled_path(data)[source]#

Extract an up sampled user trajectory.

It starts by filtering and keeping only the valid trajectory, then remove x and y potential duplicates (needed for the interpolation), and then apply the interpolation. It only returns a pandas data frame composed of x and y up sampled user coordinates, namely x and y.

Parameters:

data (DataFrame) – The pandas data frame obtained via a DrawShape.

Returns:

A pandas data frame composed of valid up sampled user coordinates x and y.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.remove_overshoots(data, reference)[source]#

Format data to remove overshoots from user trajectory.

Set the first user point as the closest point from the head of the reference trajectory and set the last user point as the closest point from the tail of the reference trajectory.

Parameters:

  • data (DataFrame) – A pandas data frame corresponding to the user data coming from an aggregated valid touch of a DrawShape.

  • reference (DataFrame) – A pandas data frame corresponding to the reference trajectory coming from a DrawShape.

Returns:

The user data without overshoots (head and tail).

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.remove_reference_head(data, reference)[source]#

Remove the reference head if the first user point doesn’t match.

The function removes the reference head when the reference point that is the closest to the first user point is different from the first reference point.

Parameters:

  • data (DataFrame) – A pandas data frame containing the user trajectory (with or without overshoot).

  • reference (DataFrame) – A pandas data frame containing the reference trajectory.

Returns:

The reference trajectory without the head if needed.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.sc_corners_max_dist(user, ref, attrib)[source]#

Compute maximum distance per corner zones.

For square clock shapes.

Parameters:

  • user (DataFrame) – A pandas data frame composed of at least the user trajectory used for computing DTW attributions.

  • ref (DataFrame) –

  • attrib (DataFrame) –

Return type:

Tuple[float, float, float]

ref

A pandas data frame composed of at least the reference trajectory.

attrib

The related dynamic time warping attributions for the considered reference trajectory with the user trajectory of interest.

Returns:

A tuple composed of the extracted aforementioned distances (for the 3 related corners).

Return type:

Tuple[float, float, float]

Parameters:
dispel.providers.generic.tasks.draw.shapes.scc_corners_max_dist(user, ref, attrib)[source]#

Compute maximum distance per corner zones.

For square counter clock shapes.

Parameters:

  • user (DataFrame) – A pandas data frame composed of at least the user trajectory used for computing DTW attributions.

  • ref (DataFrame) – A pandas data frame composed of at least the reference trajectory.

  • attrib (DataFrame) – The related dynamic time warping attributions for the considered reference trajectory with the user trajectory of interest.

Returns:

A tuple composed of the extracted aforementioned distances (for the 3 related corners).

Return type:

Tuple[float, float, float]

dispel.providers.generic.tasks.draw.shapes.top_left(data)[source]#

Return the top left part of a square-like shape (user/reference).

Parameters:

data (DataFrame) – A pandas data frame containing at least a trajectory (x and y coordinates) of a square-like shape.

Returns:

The top left part of the square-like shape given as input.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.top_right(data)[source]#

Return the top right part of a square-like shape (user/reference).

Parameters:

data (DataFrame) – A pandas data frame containing at least a trajectory (x and y coordinates) of a square-like shape.

Returns:

The top right part of the square-like shape given as input.

Return type:

pandas.DataFrame

dispel.providers.generic.tasks.draw.shapes.up_sample_user_path(data, up_sampling_factor=5)[source]#

Compute an up-sampled Bezier curve for a given user trajectory.

Parameters:

  • data (DataFrame) – A pandas data frame composed of the valid user trajectory and no duplicates.

  • up_sampling_factor (float) – The up sampling factor you want to apply.

Returns:

A pandas data frame composed of x and y up sampled user coordinates, namely x and y.

Return type:

pandas.DataFrame