pywib 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

pywib/__init__.py

@@ -0,0 +1,63 @@
+"""
+"""
+
+__version__ = "0.1.0"
+__author__ = "Guillermo Dylan Carvajal Aza"
+__email__ = "carvajalguillermo@uniovi.es"
+
+from .constants import *
+from .utils import (validate_dataframe, validate_dataframe_keyboard, 
+                    extract_traces_by_session, visualize_trace, compute_space_time_diff, video_from_trace, validate_duplicate_timestamps)
+from .core import (velocity, acceleration, jerkiness, path, auc_ratio, 
+                   execution_time, movement_time, pauses_metrics, velocity_metrics, 
+                   acceleration_metrics, jerkiness_metrics, number_of_clicks, 
+                   click_slip, num_pauses, deviations, auc_ratio_metrics, typing_speed_metrics, typing_speed, backspace_usage)
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__", 
+    "__email__",
+
+    # Constants
+    "EventTypes",
+    "ComponentTypes",
+    
+    # Utility functions
+    "validate_dataframe",
+    "validate_dataframe_keyboard",
+    "extract_trace",
+    "visualize_trace",
+    "compute_space_time_diff",
+    "extract_traces_by_session",
+    "video_from_trace",
+    "validate_duplicate_timestamps",
+
+    # Movement functions
+    "velocity",
+    "acceleration",
+    "auc_ratio",
+    "jerkiness",
+    "path",
+    "velocity_metrics",
+    "acceleration_metrics",
+    "jerkiness_metrics",
+    "deviations",
+    "auc_ratio_metrics",
+
+    # Mouse functions
+    "number_of_clicks",
+    "click_slip",
+
+    # Keyboard functions
+    "typing_speed",
+    "typing_speed_metrics",
+    "backspace_usage",
+
+    # Timing
+    "pauses_metrics",
+    "execution_time",
+    "movement_time",
+    "num_pauses",
+
+]

pywib/algorithms/patterns/straight_pattern.py

@@ -0,0 +1,39 @@
+import pandas as pd
+from pywib.utils import validate_dataframe, extract_mouse_click_traces_by_session_with_intial_pause
+from pywib.core import auc_ratio
+
+def obtain_straight_patterns(df: pd.DataFrame = None, traces : list[str, list[pd.DataFrame]] = None, per_traces= False, threshold = 100) -> list[pd.DataFrame]:
+    """
+        First described in 'Investigating the Differences in Web Browsing Behaviour of Chinese and European Users Using Mouse Tracking' (Lee & Chen, 2007),
+        the Straight Pattern can be described as a direct or straight movement in direction to a target, characterized by a pause before a direct
+        movement towards a target without significant pauses in between the initial movement and the target acquisition.
+        
+        TODO : initial pause
+
+        Parameters:
+            df (pd.DataFrame): DataFrame containing 'sessionId', 'sceneId', 'eventType', 'timeStamp', 'x', and 'y' columns.
+            traces (list): List of traces to analyze. Each trace is a pd.DataFrame.
+            per_traces (bool): If True, process per traces. Default is False.
+            threshold (float): Threshold (in px) for the AUC perpendicular distance to consider a movement as a straight pattern. Default is 100.
+        Returns:
+            list[pd.DataFrame]: A list of DataFrames, each corresponding to a straight pattern trace.
+    """
+    if(traces is None and per_traces):
+        validate_dataframe(df)
+        # This variable will always contain point and click traces
+        traces = extract_mouse_click_traces_by_session_with_intial_pause(df)
+
+    if(not per_traces):
+        raise NotImplementedError("The 'per_traces' functionality is not yet implemented.")
+    
+    auc_values = auc_ratio(None, traces= traces, per_traces= True)
+
+    straight_patterns_per_session = {}
+    for session_id, trace in auc_values.items():
+        straight_patterns = []
+        for i, auc in enumerate(trace):
+            # TODO usar auc_ratio con un porcentaje del threshold?
+            if(auc['auc_perp'] <= threshold):
+                straight_patterns.append(traces[session_id][i])
+        straight_patterns_per_session[session_id] = straight_patterns
+    return straight_patterns_per_session

pywib/constants.py

@@ -0,0 +1,84 @@
+"""
+
+"""
+
+# Version and library information
+LIBRARY_NAME = "pywib"
+LIBRARY_VERSION = "0.1.0"
+
+# Event types for interaction tracking
+class EventTypes:
+    """ Event type constants for interaction tracking."""
+    EVENT_ON_MOUSE_MOVE = 0
+    """Event type for mouse move events."""
+    EVENT_ON_CLICK = 1
+    """Event type for mouse click events."""
+    EVENT_ON_DOUBLE_CLICK = 2
+    """Event type for mouse double click events."""
+    EVENT_ON_MOUSE_DOWN = 3
+    """Event type for mouse down events."""
+    EVENT_ON_MOUSE_UP = 4
+    """Event type for mouse up events."""
+    EVENT_ON_WHEEL = 5
+    """Event type for mouse wheel events, specificaly for wheel clicks."""
+    EVENT_CONTEXT_MENU = 6
+    """Event type for context menu events."""
+    EVENT_ON_TOUCH_MOVE = 7
+    """Event type for touch move events, specific for mobile and tablet devices."""
+    EVENT_WINDOW_SCROLL = 11
+    """Event type for window scroll events."""
+    EVENT_WINDOW_RESIZE = 12
+    """Event type for window resize events."""
+    EVENT_KEY_DOWN = 13
+    """Event type for key down events."""
+    EVENT_KEY_PRESS = 14
+    """Event type for key press events."""
+    EVENT_KEY_UP = 15
+    """Event type for key up events."""
+    EVENT_FOCUS = 16
+    """Event type for focus events."""
+    EVENT_BLUR = 17
+    """Event type for blur events."""
+    EVENT_ON_CHANGE_SELECTION_OBJECT = 18
+    """Event type for change selection events."""
+    EVENT_ON_CLICK_SELECTION_OBJECT = 19
+    """Event type for click selection events."""
+    EVENT_INIT_TRACKING = 100
+    """Custom event type for initializing tracking."""
+    EVENT_TRACKING_END = 200
+    """Custom event type for ending tracking."""
+
+class ComponentTypes:
+    """ Component type constants for UI elements."""
+    COMPONENT_TEXT_FIELD = 1
+    COMPONENT_COMBOBOX = 2
+    COMPONENT_OPTION = 3
+    COMPONENT_RADIO_BUTTON = 4
+    COMPONENT_CHECK_BOX = 5
+
+class ColumnNames:
+    """ Standard column names for DataFrame operations."""
+    SESSION_ID = 'sessionId'
+    SCENE_ID = 'sceneId'
+    EVENT_TYPE = 'eventType'
+    ELEMENT_ID = 'elementId'
+    TIME_STAMP = 'timeStamp'
+    X = 'x'
+    Y = 'y'
+    KEY_VALUE_EVENT = 'keyValueEvent'
+    KEY_CODE_EVENT = 'keyCodeEvent'
+    SOURCE_SESSION_ID = 'sourceSessionId'
+    DT = 'dt'
+    DX = 'dx'
+    DY = 'dy'
+    VELOCITY= 'velocity'
+    ACCELERATION = 'acceleration'
+    JERKINESS = 'jerkiness'
+    AUC_RATIO = 'auc_ratio'
+
+class KeyCodeEvents:
+    """ Key code event constants for keyboard interactions."""
+    KEY_CODE_BACKSPACE = 8
+    """Key code for the Backspace key."""
+    KEY_CODE_DELETE = 46
+    """Key code for the Delete key."""

pywib/core/__init__.py

@@ -0,0 +1,34 @@
+"""
+Utility functions for PyWib
+"""
+from .timing import execution_time, movement_time, num_pauses, pauses_metrics
+from .movement import (velocity, acceleration, jerkiness, 
+                       path, auc_optimal, auc_ratio, auc, auc_ratio_metrics,
+                       velocity_metrics, acceleration_metrics, jerkiness_metrics,
+                       deviations)
+from .mouse import click_slip, number_of_clicks
+from .keyboard import (typing_speed, typing_speed_metrics, backspace_usage)
+
+__all__ = [
+    "execution_time",
+    "movement_time",
+    "num_pauses",
+    "pauses_metrics",
+    "velocity",
+    "acceleration",
+    "jerkiness",
+    "path",
+    "auc_optimal",
+    "auc_ratio",
+    "auc_ratio_metrics",
+    "auc",
+    "velocity_metrics",
+    "acceleration_metrics",
+    "jerkiness_metrics",
+    "click_slip",
+    "number_of_clicks",
+    "deviations"
+    "typing_speed",
+    "typing_speed_metrics",
+    "backspace_usage",
+]

pywib/core/keyboard.py

@@ -0,0 +1,114 @@
+"""
+Analysis module for HCI Web Interaction Analyzer
+
+This module provides methods to analyze interaction data from DataFrames.
+"""
+
+import pandas as pd
+import numpy as np
+from pywib.utils.segmentation import extract_keystroke_traces_by_session
+from pywib.utils.validation import validate_dataframe_keyboard
+from pywib.constants import EventTypes, ColumnNames, KeyCodeEvents
+from pywib.utils.keyboard import (backspace_usage_df, backspace_usage_traces, typing_durations_df, typing_durations_traces, typing_speed_df, typing_speed_traces)
+
+def typing_durations(df: pd.DataFrame = None, traces: dict[str, list[pd.DataFrame]] = None, per_traces: bool = True) -> list:
+    """
+    Calculate the durations of individual keystrokes.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing interaction data with 'event_type', 'timestamp', and 'key' columns.
+        traces (dict[str, list[pd.DataFrame]]): optional Pre-extracted keystroke traces by session.
+        per_traces (bool): optional Whether to calculate durations per trace. Default is True.
+    Returns:
+        list: List of keystroke durations in milliseconds.
+    """
+    if traces is None and per_traces:
+        traces = extract_keystroke_traces_by_session(df)
+        return typing_durations_traces(traces, False)
+
+    if not per_traces:
+        return typing_durations_df(df)
+
+    return typing_durations_traces(traces)
+
+def typing_speed(df: pd.DataFrame = None, traces: dict[str, list[pd.DataFrame]] = None, per_traces : bool = True) -> dict[list[float]] | float:
+    """
+    Calculate the average typing speed in characters per minute (CPM).
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing interaction data with 'event_type', 'timestamp', and 'key' columns.
+        traces (dict[str, list[pd.DataFrame]]): optional Pre-extracted keystroke traces by session.
+        per_traces (bool): optional Whether to calculate speed per trace. Default is True. if False, mind that the df must only contain typing data in order to obtain the correct CPM calculation.
+
+    Returns:
+        dict (dict[list[float]] | float) : A dictionary with session IDs as keys and lists of typing speeds (CPM) per trace as values, or a float representing the typing speed if per_traces is False.
+    """
+
+    if per_traces and traces is None:
+        traces = extract_keystroke_traces_by_session(df)
+        return typing_speed_traces(traces, False)
+
+    elif not per_traces:
+        return typing_speed_df(df)
+
+    return typing_speed_traces(traces)
+
+def typing_speed_metrics(df: pd.DataFrame = None, traces: dict[str, list[pd.DataFrame]] = None) -> dict:
+    """
+    Calculate typing speed metrics including average CPM, total characters typed, and total time spent typing.
+    
+    This metrics include average typing speed (average_typing_speed) in CPM, total characters typed (total_characters), and total time spent typing (total_time_seconds) in seconds.
+    
+    The average keydown to keyup duration (avg_keydown_to_keyup_duration) is the average duration of a keystroke (from keydown to keyup) in milliseconds.
+
+    Parameters:
+        df : pd.DataFrame DataFrame containing interaction data with 'event_type', 'timestamp', and 'key' columns.
+        traces : dict[str, list[pd.DataFrame]], optional Pre-extracted keystroke traces by session.
+        per_trace : bool, optional Whether to calculate metrics per trace. Default is True.
+    Returns:
+        dict: A dictionary with session IDs as keys and their corresponding typing speed metrics as values.
+        """
+    if traces is None:
+        traces = extract_keystroke_traces_by_session(df)
+    
+    session_speeds = typing_speed(None, traces=traces, per_traces=True)
+
+    metrics_by_session = {}
+    for session_id, speeds in session_speeds.items():
+        if speeds:
+            avg_speed = np.mean(speeds)
+            total_chars = sum(session_traces[session_traces[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_KEY_UP][ColumnNames.EVENT_TYPE].count() for session_traces in traces[session_id])
+            total_time = sum((session_traces[ColumnNames.TIME_STAMP].diff().fillna(0).sum() / 1000.0) for session_traces in traces[session_id])
+            avg_keydown_to_keyup_duration = np.mean([
+                (trace[trace[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_KEY_UP][ColumnNames.TIME_STAMP].values - trace[trace[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_KEY_DOWN][ColumnNames.TIME_STAMP].values).mean()
+                for trace in traces[session_id]
+            ])
+            metrics_by_session[session_id] = {
+                "average_typing_speed": avg_speed,
+                "total_characters": total_chars,
+                "total_time_seconds": total_time,
+                "avg_keydown_to_keyup_duration": avg_keydown_to_keyup_duration  # TODO Review
+            }
+    return metrics_by_session
+
+
+def backspace_usage(df: pd.DataFrame = None, traces: dict[str, list[pd.DataFrame]] = None, per_trace: bool = True) -> dict:
+    """
+    Calculate the backspace usage rate (backspaces per 100 characters typed) for each session.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing interaction data with 'event_type', 'timestamp', and 'key' columns.
+        traces (dict[str, list[pd.DataFrame]]): optional Pre-extracted keystroke traces by session.
+        per_trace (bool): optional Whether to calculate usage per trace. Default is True.
+    Returns:
+        dict: A dictionary with session IDs as keys and their corresponding backspace counts as values.
+    """
+    if traces is None and per_trace:
+        validate_dataframe_keyboard(df)
+        traces = extract_keystroke_traces_by_session(df)
+        return backspace_usage_traces(traces, False)
+    if not per_trace:
+        validate_dataframe_keyboard(df)
+        return backspace_usage_df(df)
+    
+    return backspace_usage_traces(traces)

pywib/core/mouse.py

@@ -0,0 +1,109 @@
+import pandas as pd
+import numpy as np
+from ..utils.validation import validate_dataframe
+from ..utils.utils import compute_space_time_diff
+from ..utils.segmentation import extract_traces_by_session
+from ..constants import ColumnNames, EventTypes
+
+def number_of_clicks(df: pd.DataFrame) -> dict:
+    """
+    Calculate the number of clicks per session.
+    Parameters:
+        df (pd.DataFrame): DataFrame containing mouse event data.
+    Returns:
+        dict: A dictionary with session IDs as keys and number of clicks as values.
+    """
+    validate_dataframe(df)
+
+    clicks_per_session = {}
+    df = df.groupby(ColumnNames.SESSION_ID)
+    for session_id, group in df:
+        clicks_per_session[session_id] = group[group[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_CLICK].shape[0]
+    return clicks_per_session
+
+def click_slip(df: pd.DataFrame, threshold: float = 5.0) -> dict:
+    """
+    Calculate the number of click slips per session.
+    A click slip is defined as a click event that occurs within a certain distance
+    from the previous mouse position (indicating an unintended click).
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing mouse event data.
+        threshold (float): Distance threshold to consider a click as a slip.
+
+    Returns:
+        dict: A dictionary with session IDs as keys and the metrics (click slips, max, min, average) as values.
+    """
+    validate_dataframe(df)
+
+    click_slips_per_session = {}
+    df = df.groupby(ColumnNames.SESSION_ID)
+    metrics_per_session = {}
+    for session_id, group in df:
+        group = group.sort_values(by=ColumnNames.TIME_STAMP)
+        slips = 0
+        # We define a click slip as: the total path distance of all
+        # EVENT_ON_MOUSE_MOVE events that occur between an
+        # EVENT_ON_MOUSE_DOWN and the subsequent EVENT_ON_MOUSE_UP.
+        # If that total move-distance is less than `threshold` we count
+        # it as a slip.
+        in_down = False
+        last_move_x = None
+        last_move_y = None
+        accumulated_move_distance = 0.0
+        distances = []
+        durations = []
+        mouse_down_time = None
+        for _, row in group.iterrows():
+            # Mouse down: start a new segment
+            if row[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_MOUSE_DOWN:
+                in_down = True
+                # reset accumulators
+                last_move_x = row[ColumnNames.X]
+                last_move_y = row[ColumnNames.Y]
+                accumulated_move_distance = 0.0
+                mouse_down_time = row[ColumnNames.TIME_STAMP]
+
+            # While between down and up, accumulate move distances
+            if in_down and row[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_MOUSE_MOVE:
+                x = row[ColumnNames.X]
+                y = row[ColumnNames.Y]
+                if last_move_x is not None and last_move_y is not None:
+                    d = np.hypot(x - last_move_x, y - last_move_y)
+                    accumulated_move_distance += d
+                # set last seen move position (even if it was the first move)
+                last_move_x, last_move_y = x, y
+
+            # Mouse up: finalize the segment and decide if it's a slip
+            if row[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_MOUSE_UP and in_down:
+                x = row[ColumnNames.X]
+                y = row[ColumnNames.Y]
+                duration = row[ColumnNames.TIME_STAMP] - mouse_down_time if mouse_down_time is not None else 0
+                if last_move_x is not None and last_move_y is not None:
+                    d = np.hypot(x - last_move_x, y - last_move_y)
+                    accumulated_move_distance += d
+                if accumulated_move_distance >= threshold:
+                    slips += 1
+                    distances.append(accumulated_move_distance)
+                durations.append(duration)
+                in_down = False
+                last_move_x = None
+                last_move_y = None
+                mouse_down_time = None
+                accumulated_move_distance = 0.0
+        click_slips_per_session[session_id] = {
+            "slips": slips,
+            "distances": distances,
+        }
+        metrics = {
+            "click_slips": slips,
+            "longest_click_slip": max(distances) if distances else 0,
+            "shortest_click_slip": min(distances) if distances else 0,
+            "average_click_slip": slips / len(distances) if distances else 0,
+            "average_click_slip_distance": np.mean(distances) if distances else 0,
+            "average_click_duration": np.mean(durations) if durations else 0,
+            "max_click_duration": max(durations) if durations else 0,
+            "min_click_duration": min(durations) if durations else 0,
+        }
+        metrics_per_session[session_id] = metrics
+    return metrics_per_session