pywib 0.1.0__tar.gz

pywib-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+src/pywib/__pycache__
+src/pywib/tests/__pycache__
+src/pywib/utils/__pycache__
+src/pywib/core/__pycache__
+test/__pycache__
+dist
+.vscode/

pywib-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pywib-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: pywib
+Version: 0.1.0
+Summary: HCI Web Interaction Analyzer - A library for analyzing web user interactions
+Project-URL: Homepage, https://github.com/HumanCommunicationInteraction/pywib
+Project-URL: Bug Tracker, https://github.com/HumanCommunicationInteraction/pywib/issues
+Project-URL: Documentation, https://pywib.readthedocs.io/
+Project-URL: Repository, https://github.com/HumanCommunicationInteraction/pywib.git
+Author-email: Guillermo Dylan Carvajal Aza <carvajalguillermo@uniovi.es>, Alejandro Álvarez Varela <avarela@uniovi.es>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas>=1.3.0
+Description-Content-Type: text/markdown
+
+# pywib
+
+Pywib (Python Web Interaction Behaviour) is a library desgined for analysing and obtaning metrics from users interaction with web pages.
+
+## How to
+
+```

pywib-0.1.0/README.md

@@ -0,0 +1,7 @@
+# pywib
+
+Pywib (Python Web Interaction Behaviour) is a library desgined for analysing and obtaning metrics from users interaction with web pages.
+
+## How to
+
+```

pywib-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pywib"
+version = "0.1.0"
+authors = [
+  { name="Guillermo Dylan Carvajal Aza", email="carvajalguillermo@uniovi.es" },
+  { name="Alejandro Álvarez Varela", email="avarela@uniovi.es"}
+]
+description = "HCI Web Interaction Analyzer - A library for analyzing web user interactions"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "pandas>=1.3.0",
+    "numpy>=1.21.0",
+    "matplotlib>=3.5.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/HumanCommunicationInteraction/pywib"
+"Bug Tracker" = "https://github.com/HumanCommunicationInteraction/pywib/issues"
+Documentation = "https://pywib.readthedocs.io/"
+Repository = "https://github.com/HumanCommunicationInteraction/pywib.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pywib"]

pywib-0.1.0/requirements.txt

@@ -0,0 +1 @@
+pandas>=1.3.0

pywib-0.1.0/setup.py

@@ -0,0 +1,48 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+with open("requirements.txt", "r", encoding="utf-8") as fh:
+    requirements = [line.strip() for line in fh if line.strip() and not line.startswith("#")]
+
+
+setup(
+    name='pywib',
+    packages=find_packages(),
+    version='0.1.0',
+    description='HCI Web Interaction Analyzer - A library for analyzing web user interactions',
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/HumanCommunicationInteraction/pywib",
+    packages=find_packages(),
+    author='Guillermo Dylan Carvajal Aza',
+    author_email='carvajalguillermo@uniovi.es',
+    keywords=['HCI', 'Web Interaction', 'Analyzer'],
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Scientific/Engineering",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+    python_requires=">=3.9",
+    install_requires=requirements,
+    extras_require={
+        "dev": [
+            "pytest>=6.0",
+            "pytest-cov",
+            "black",
+            "flake8",
+        ],
+    },
+    include_package_data=True,
+    zip_safe=False,
+)

pywib-0.1.0/src/pywib/__init__.py

@@ -0,0 +1,43 @@
+"""
+"""
+
+__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
+from .core.movement import velocity, acceleration, jerkiness, path, auc_ratio
+from .core.timing import execution_time, movement_time, pauses_metrics
+from .utils.utils import compute_space_time_diff
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__", 
+    "__email__",
+
+    # Constants
+    "EventTypes",
+    "ComponentTypes",
+    
+    # Utility functions
+    "validate_dataframe",
+    "validate_dataframe_keyboard",
+    "extract_trace",
+    "visualize_trace",
+
+    # Movement functions
+    "velocity",
+    "acceleration",
+    "auc_ratio",
+    "jerkiness",
+    "path",
+
+    # Timing
+    "pauses_metrics",
+
+    # Utils
+    "compute_space_time_diff",
+    "extract_traces_by_session",
+]

pywib-0.1.0/src/pywib/constants.py

@@ -0,0 +1,54 @@
+"""
+
+"""
+
+# 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_ON_CLICK = 1
+    EVENT_ON_DOUBLE_CLICK = 2
+    EVENT_ON_MOUSE_DOWN = 3
+    EVENT_ON_MOUSE_UP = 4
+    EVENT_ON_WHEEL = 5
+    EVENT_CONTEXT_MENU = 6
+    EVENT_ON_TOUCH_MOVE = 7
+    EVENT_WINDOW_SCROLL = 11
+    EVENT_WINDOW_RESIZE = 12
+    EVENT_KEY_DOWN = 13
+    EVENT_KEY_PRESS = 14
+    EVENT_KEY_UP = 15
+    EVENT_FOCUS = 16
+    EVENT_BLUR = 17
+    EVENT_ON_CHANGE_SELECTION_OBJECT = 18
+    EVENT_ON_CLICK_SELECTION_OBJECT = 19
+    EVENT_INIT_TRACKING = 100
+    EVENT_TRACKING_END = 200
+
+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'

pywib-0.1.0/src/pywib/core/keyboard.py

@@ -0,0 +1,5 @@
+"""
+Analysis module for HCI Web Interaction Analyzer
+
+This module provides methods to analyze interaction data from DataFrames.
+"""

pywib-0.1.0/src/pywib/core/movement.py

@@ -0,0 +1,226 @@
+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
+
+def velocity(df: pd.DataFrame, traces: dict[str, list[pd.DataFrame]] = None) -> dict:
+    """
+    Calculate the velocity for the given DataFrame or traces.
+    This function computes the velocity based on the distance and time difference between consecutive points.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'x', 'y', and 'timeStamp' columns.
+        traces (dict): A dictionary with keys as (sessionId) and values as lists of DataFrames. If None, traces will be computed from df.
+    Returns:
+        dict: A dictionary with keys as (sessionId) and values as DataFrames with an additional 'velocity' column.
+    """
+
+    if traces is None:
+        validate_dataframe(df)
+        traces = extract_traces_by_session(df)
+            
+    for session_id, session_traces in traces.items():
+        for i in range(len(session_traces)):
+                validate_dataframe(session_traces[i])
+
+        for j in range(len(session_traces)):
+            session_traces[j] = _path(session_traces[j])
+            session_traces[j]['velocity'] = session_traces[j]['distance'] / session_traces[j]['dt']
+            # Fix NaN velocity for first point - set to 0
+            session_traces[j]['velocity'] = session_traces[j]['velocity'].fillna(0)
+            
+        traces[session_id] = session_traces
+    return traces
+
+def acceleration(df: pd.DataFrame,  traces: dict[str, list[pd.DataFrame]] = None) -> dict:
+    """
+    Calculate the acceleration for the given DataFrame.
+    This function computes the acceleration based on the change in velocity over time.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'velocity' and 'dt' columns.
+        traces (dict): A dictionary with keys as (sessionId) and values as lists of DataFrames. If None, traces will be computed from df.
+    Returns:
+        dict: A dictionary with keys as (sessionId) and values as DataFrames with an additional 'acceleration' column.
+    """
+    
+    if traces is None:
+        validate_dataframe(df)
+        traces = extract_traces_by_session(df)
+
+    for session_id, session_traces in traces.items():
+        for i in range(len(session_traces)):
+                validate_dataframe(session_traces[i])
+        for j in range(len(session_traces)):
+            session_traces[j]['acceleration'] = session_traces[j]["velocity"].diff().fillna(0) / session_traces[j]['dt']
+            session_traces[j]['acceleration'] = session_traces[j]['acceleration'].fillna(0)
+
+        traces[session_id] = session_traces
+    return traces
+
+def jerkiness(df: pd.DataFrame,  traces: dict[str, list[pd.DataFrame]] = None) -> dict:
+    """
+    Calculate the jerkiness for the given DataFrame.
+    This function computes the jerkiness based on the change in acceleration over time.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'acceleration' and 'dt' columns.
+        traces (dict): A dictionary with keys as (sessionId) and values as lists of DataFrames. If None, traces will be computed from df.
+
+    Returns:
+        dict: A dictionary with keys as (sessionId) and values as DataFrames with an additional 'jerkiness' column.
+    """
+
+    if traces is None:
+        validate_dataframe(df)
+        traces = extract_traces_by_session(df)
+
+    for session_id, session_traces in traces.items():
+        for i in range(len(session_traces)):
+                validate_dataframe(session_traces[i])
+        # TODO revisar
+        for j in range(len(session_traces)):
+            session_traces[j] = session_traces[j]["acceleration"].diff().fillna(0) / session_traces[j]['dt']
+            
+        traces[session_id] = session_traces
+
+    return traces
+
+def path(df: pd.DataFrame = None, traces: dict[str, list[pd.DataFrame]] = None) -> pd.DataFrame:
+    """
+    Calculate the path length for the given DataFrame.
+    This function computes the path length based on the Euclidean distance between consecutive points.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'x' and 'y' columns.
+        traces (dict): A dictionary with keys as (sessionId) and values as lists of DataFrames. If None, traces will be computed from df.
+
+    Returns:
+        pd.DataFrame: DataFrame with an additional 'distance' column representing the path length.
+    """
+
+    if traces is None:
+        validate_dataframe(df)
+        traces = extract_traces_by_session(df)
+
+    for session_id, session_traces in traces.items():
+            for i in range(len(session_traces)):
+                validate_dataframe(session_traces[i])
+
+            # Compute the distance for each trace
+            for j in range(len(session_traces)):
+                session_traces[j]['distance'] = _path(session_traces[j])['distance']
+            
+            # Store the traces with distance in the dictionary
+            df[session_id] = session_traces
+
+    return df
+
+def _path(trace: pd.DataFrame) -> pd.DataFrame:
+    """
+    Helper function to calculate the path length for a single trace.
+    This function computes the path length based on the Euclidean distance between consecutive points.
+
+    Parameters:
+        trace (pd.DataFrame): A single trace DataFrame.
+
+    Returns:
+        pd.DataFrame: DataFrame with an additional 'distance' column representing the path length.
+    """
+
+    if trace is None:
+        raise ValueError("Trace DataFrame must be provided.")
+
+    validate_dataframe(trace)
+
+    trace = compute_space_time_diff(trace)
+    trace['distance'] = np.sqrt(trace['dx'] ** 2 + trace['dy'] ** 2)
+
+    return trace
+
+def auc(df: pd.DataFrame, validation: bool = True, computeTraces: bool = True) -> float:
+    """
+    Calculate the Area Under the Curve (AUC) for the given DataFrame.
+    
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'timeStamp' and 'y' columns.
+        validation (bool): Whether to validate the DataFrame structure, by default True.
+        computeTraces (bool): Whether to compute traces by sessionId, by default True.
+    
+    Returns:
+        float: The computed AUC value.
+    """
+    
+    if(validation):
+        validate_dataframe(df)
+
+    if computeTraces:
+        df   = extract_traces_by_session(df)
+
+    df = df.sort_values(by=ColumnNames.TIME_STAMP)
+
+    df = compute_space_time_diff(df)
+
+    # Área bajo la curva real
+    area_real = np.trapezoid(df[ColumnNames.Y], df[ColumnNames.X])
+
+    return area_real
+
+def auc_optimal(df: pd.DataFrame, validation: bool = True, computeTraces: bool = True) -> float:
+    """
+    Calculate the Optimal Area Under the Curve (AUC) for the given DataFrame.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing 'timeStamp' and 'y' columns.
+    validation (bool): Whether to validate the DataFrame structure, by default True.
+    computeTraces (bool): Whether to compute traces by sessionId, by default True.
+    
+    Returns:
+    float: The computed optimal AUC value.
+    """
+    
+    if(validation):
+        validate_dataframe(df)
+
+    if computeTraces:
+        df = extract_traces_by_session(df)
+
+
+    df = compute_space_time_diff(df)
+
+    # Área bajo la línea óptima
+    x0, y0 = df[ColumnNames.X].iloc[0], df[ColumnNames.Y].iloc[0]
+    x1, y1 = df[ColumnNames.X].iloc[-1], df[ColumnNames.Y].iloc[-1]
+    x_opt = np.linspace(x0, x1, len(df))
+    y_opt = np.linspace(y0, y1, len(df))
+    area_optimal = np.trapezoid(y_opt, x_opt)
+
+    return area_optimal
+
+def auc_ratio(df: pd.DataFrame, computeTraces: bool = True) -> dict:
+    """
+    Calculate the AUC ratio for the given DataFrame.
+    
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'timeStamp' and 'y' columns.
+        computeTraces (bool): Whether to compute traces by sessionId, by default True. If False, df is assumed to be already segmented by sessionId.
+    
+    Returns:
+        auc_per_session (dict): A dictionary with sessionId as keys and a tuple (area_real, area_optimal, auc_ratio) as values.
+    """
+
+    validate_dataframe(df)
+
+    if computeTraces:
+        df = extract_traces_by_session(df)
+
+    auc_per_session = {}
+    for session_id, session_traces in df.items():
+        area_real = auc(session_traces, False, False)
+        area_optimal = auc_optimal(session_traces, False, False)
+        auc_per_session[session_id] = (area_real, area_optimal, abs(area_real - area_optimal) / (abs(area_optimal) + 1e-6))
+
+    return auc_per_session
+

pywib-0.1.0/src/pywib/core/timing.py

@@ -0,0 +1,129 @@
+import pandas as pd
+from ..utils.validation import validate_dataframe
+from ..utils.segmentation import extract_traces_by_session
+from ..utils.utils import compute_space_time_diff
+from ..constants import ColumnNames
+
+def execution_time(df: pd.DataFrame) -> float:
+    """
+    Calculate the total execution time of a session in seconds.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'timeStamp' column.
+    Returns:
+        float: Total execution time in seconds.
+    """
+    validate_dataframe(df)
+
+    start_time = df[ColumnNames.TIME_STAMP].min()
+    end_time = df[ColumnNames.TIME_STAMP].max()
+    total_time = (end_time - start_time) / 1000.0  # Convert milliseconds to seconds
+    return total_time
+
+def movement_time(df: pd.DataFrame, traces: dict[str, list[pd.DataFrame]] = None) -> float:
+    """
+    Calculate the total movement time from traces in seconds.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'timeStamp' column.
+        traces (dict): Dictionary with sessionId as keys and list of DataFrames as values.
+    Returns:
+        float: Total movement time in seconds.
+    """
+    if traces is None:
+        validate_dataframe(df)
+        traces = extract_traces_by_session(df)
+
+    total_movement_time = 0.0
+    for session_id, session_traces in traces.items():
+        for trace in session_traces:
+            trace = compute_space_time_diff(trace)  
+            total_movement_time += trace[ColumnNames.DT].sum() / 1000.0  # Convert milliseconds to seconds
+
+    return total_movement_time
+
+def num_pauses(df: pd.DataFrame, threshold: float = 100, computeTraces: bool = True) -> tuple[dict, dict]:
+    """
+    Calculate the number of pauses in the DataFrame.
+    
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'timeStamp' column.
+        threshold (float): Time threshold in milliseconds to consider a pause, by default 100 ms.
+        computeTraces (bool): Whether to compute traces by sessionId, by default True. If False, df is assumed to be already segmented by sessionId.
+    
+    Returns:
+        tuple (tuple[dict, dict]): A tuple containing two dictionaries with the number of pauses per session and the mean number of pauses per trace, with the sessionId as keys.
+    """
+
+    if computeTraces:
+        validate_dataframe(df)
+        df = extract_traces_by_session(df)
+
+    num_pauses_per_session = {}
+    mean_pause_per_trace = {}
+    for session_id, session_traces in df.items():
+        total_pauses_session = 0
+        for trace in session_traces:
+            df_pauses = _num_pauses_trace(trace, threshold)
+            total_pauses_session += df_pauses.shape[0]
+        num_pauses_per_session[session_id] = total_pauses_session
+        mean_pause_per_trace[session_id] = total_pauses_session / len(session_traces) if len(session_traces) > 0 else 0
+    return num_pauses_per_session, mean_pause_per_trace
+
+def _num_pauses_trace(df: pd.DataFrame, threshold: float) -> pd.DataFrame:
+    """
+    Helper function to calculate pauses in a single trace.
+    """
+    df = df.sort_values(by=ColumnNames.TIME_STAMP).reset_index(drop=True)
+    df[ColumnNames.DT] = df[ColumnNames.TIME_STAMP].diff().fillna(0)
+    pauses = df[df[ColumnNames.DT] > threshold]
+    return pauses
+
+
+def pauses_metrics(df: pd.DataFrame, threshold: float = 100, traces: dict[str, list[pd.DataFrame]] = None) -> dict:
+    """
+    Calculate pause metrics for the given DataFrame.
+    
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'timeStamp' column.
+        threshold (float): Time threshold in milliseconds to consider a pause, by default 100 ms.
+        traces (dict): Dictionary with sessionId as keys and list of DataFrames as values.
+
+    Returns:
+        dict: A dictionary with sessionId as keys and a dictionary of pause metrics as values.
+    """
+
+    if traces is None:
+        validate_dataframe(df)  
+        traces = extract_traces_by_session(df)
+    
+    pause_metrics_per_session = {}
+    number_pauses_session, number_pauses_trace = num_pauses(traces, threshold, computeTraces=False)
+    for session_id, session_traces in traces.items():
+        total_pauses = 0
+        total_pause_duration = 0.0
+        pause_durations = []
+
+        for trace in session_traces:
+            trace = compute_space_time_diff(trace)  
+            pauses = trace[trace[ColumnNames.DT] > threshold]
+            total_pauses += pauses.shape[0]
+            total_pause_duration += pauses[ColumnNames.DT].sum()
+            pause_durations.extend(pauses[ColumnNames.DT].tolist())
+
+        # Compute pause metrics for the session
+        if total_pauses > 0:
+            mean_pause_duration = total_pause_duration / total_pauses
+        else:
+            mean_pause_duration = 0
+
+        pause_metrics_per_session[session_id] = {
+            "total_pauses": total_pauses,
+            "mean_pause_duration": mean_pause_duration,
+            "pause_durations": pause_durations,
+            "mean_pauses_per_trace": number_pauses_trace.get(session_id, 0),
+            "max_pause": max(pause_durations) if pause_durations else 0,
+            "min_pause": min(pause_durations) if pause_durations else 0,
+        }
+
+    return pause_metrics_per_session

pywib-0.1.0/src/pywib/utils/__init__.py

@@ -0,0 +1,14 @@
+"""
+Utility functions for PyWib
+"""
+
+from .validation import validate_dataframe, validate_dataframe_keyboard
+from .segmentation import extract_traces_by_session
+from .visualization import visualize_trace
+
+__all__ = [
+    'validate_dataframe',
+    'validate_dataframe_keyboard',
+    'extract_traces_by_session',
+    'visualize_trace'
+]

pywib-0.1.0/src/pywib/utils/segmentation.py

@@ -0,0 +1,42 @@
+import pandas as pd
+from ..constants import EventTypes, ColumnNames
+from ..utils.validation import validate_dataframe
+
+def extract_trace(dt: pd.DataFrame) -> list:
+    """
+    Extracts trace from the DataFrame.
+    Each trace is considered as a sequence of consecutive ON_MOUSE_MOVE events
+    between two non-move events.
+    Returns a list of DataFrames, each corresponding to a trace.
+    """
+    validate_dataframe(dt)
+    dt = dt.sort_values(by=ColumnNames.TIME_STAMP).reset_index(drop=True)
+    is_move = (dt[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_MOUSE_MOVE) | (dt[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_TOUCH_MOVE)
+    group_id = (~is_move).cumsum()
+    traces = []
+    for _, group in dt[is_move].groupby(group_id[is_move]):
+        if len(group) > 1:
+            traces.append(group)
+    return traces
+
+def extract_traces_by_session(dt: pd.DataFrame) -> dict:
+    """
+    Extracts traces from the DataFrame, grouped by (sessionId, sceneId).
+    Each trace is considered as a sequence of consecutive ON_MOUSE_MOVE events
+    between two non-move events.
+
+    Returns:
+        dict: a dictionary with keys as (sessionId) and values as lists of DataFrames.
+    """
+    validate_dataframe(dt)
+    dt = dt.sort_values(by=ColumnNames.TIME_STAMP).reset_index(drop=True)
+    traces_by_session = {}
+    for session_id, group in dt.groupby(ColumnNames.SESSION_ID):
+        is_move = (group[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_MOUSE_MOVE) | (group[ColumnNames.EVENT_TYPE] == EventTypes.EVENT_ON_TOUCH_MOVE)
+        group_id = (~is_move).cumsum()
+        traces = []
+        for _, sub_group in group[is_move].groupby(group_id[is_move]):
+            if len(sub_group) > 1:
+                traces.append(sub_group)
+        traces_by_session[session_id] = traces
+    return traces_by_session

pywib-0.1.0/src/pywib/utils/utils.py

@@ -0,0 +1,26 @@
+import pandas as pd
+from ..constants import ColumnNames
+
+def compute_space_time_diff(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Compute space and time differences (dx, dy, dt) for the given DataFrame.
+
+    Parameters:
+        df (pd.DataFrame): DataFrame containing 'x', 'y', and 'timeStamp' columns.
+    
+    Returns:
+        pd.DataFrame: DataFrame with additional 'dx', 'dy', and 'dt' columns.
+    """
+    if(ColumnNames.X not in df.columns or
+       ColumnNames.Y not in df.columns or
+       ColumnNames.TIME_STAMP not in df.columns or
+       ColumnNames.SESSION_ID not in df.columns):
+        raise ValueError(f"DataFrame must contain '{ColumnNames.X}', '{ColumnNames.Y}', '{ColumnNames.TIME_STAMP}', and '{ColumnNames.SESSION_ID}' columns.")
+
+    df = df.copy()
+    df.sort_values(by=[ColumnNames.TIME_STAMP], inplace=True)
+    df[ColumnNames.TIME_STAMP] = pd.to_numeric(df[ColumnNames.TIME_STAMP], errors='coerce')
+    df['dt'] = df.groupby([ColumnNames.SESSION_ID])[ColumnNames.TIME_STAMP].diff().fillna(0)
+    df['dx'] = df.groupby([ColumnNames.SESSION_ID])[ColumnNames.X].diff().fillna(0)
+    df['dy'] = df.groupby([ColumnNames.SESSION_ID])[ColumnNames.Y].diff().fillna(0)
+    return df

pywib-0.1.0/src/pywib/utils/validation.py

@@ -0,0 +1,24 @@
+import pandas as pd
+from ..constants import ColumnNames
+
+required_columns = [
+    ColumnNames.SESSION_ID, ColumnNames.EVENT_TYPE, ColumnNames.TIME_STAMP, ColumnNames.X, ColumnNames.Y
+]
+
+keyboard_columns = [
+   ColumnNames.KEY_VALUE_EVENT, ColumnNames.KEY_CODE_EVENT
+]
+
+def validate_dataframe(df: pd.DataFrame):
+
+    for col in required_columns:
+        if col not in df.columns:
+            raise ValueError(f"Missing required column: {col}")
+        
+def validate_dataframe_keyboard(df: pd.DataFrame):
+
+    columns_to_check = required_columns + keyboard_columns
+
+    for col in columns_to_check:
+        if col not in df.columns:
+            raise ValueError(f"Missing required column: {col}")

pywib-0.1.0/src/pywib/utils/validator.py

@@ -0,0 +1,23 @@
+import pandas as pd
+
+required_columns = [
+    "id", "eventType", "timeStamp", "x", "y"
+]
+
+keyboard_columns = [
+   "keyValueEvent", "keyCodeEvent"
+]
+
+def validate_dataframe(df: pd.DataFrame):
+
+    for col in required_columns:
+        if col not in df.columns:
+            raise ValueError(f"Missing required column: {col}")
+        
+def validate_dataframe_keyboard(df: pd.DataFrame):
+
+    columns_to_check = required_columns + keyboard_columns
+
+    for col in columns_to_check:
+        if col not in df.columns:
+            raise ValueError(f"Missing required column: {col}")

pywib-0.1.0/src/pywib/utils/visualization.py

@@ -0,0 +1,23 @@
+import matplotlib.pyplot as plt
+
+def visualize_trace(df, stroke_indices, stroke_id):
+    stroke_data = df.loc[stroke_indices]
+    plt.figure(figsize=(10, 8))
+    plt.plot(stroke_data['x'], stroke_data['y'], 'b-o', linewidth=2, markersize=4, label='Trazo real')
+
+    x_start, y_start = stroke_data['x'].iloc[0], stroke_data['y'].iloc[0]
+    x_end, y_end = stroke_data['x'].iloc[-1], stroke_data['y'].iloc[-1]
+    plt.plot([x_start, x_end], [y_start, y_end], 'r--', linewidth=2, label='Línea óptima')
+
+    plt.plot(x_start, y_start, 'go', markersize=8, label='Inicio')
+    plt.plot(x_end, y_end, 'ro', markersize=8, label='Fin')
+
+    duration = stroke_data['timeStamp'].iloc[-1] - stroke_data['timeStamp'].iloc[0]
+    plt.xlabel('X (píxeles)')
+    plt.ylabel('Y (píxeles)')
+    plt.title(f'Trazo {stroke_id} - Duración: {duration:.0f}ms - Puntos: {len(stroke_data)}')
+    plt.legend()
+    plt.grid(True, alpha=0.3)
+    plt.gca().invert_yaxis()
+    plt.show()
+

pywib-0.1.0/test/movement.py

@@ -0,0 +1,60 @@
+import unittest
+import pandas as pd
+import numpy as np
+
+# Now you can import directly since the package is installed
+from src.pywib.core.movement import velocity, acceleration
+from src.pywib.utils.utils import compute_space_time_diff
+from utils import process_csv
+
+class TestMovement(unittest.TestCase):
+    
+    def setUp(self):
+        """Set up test data"""
+        # Create sample test data instead of relying on external CSV
+        self.test_data = process_csv('E:\\Documents\\Guille\\Uni\\2025\\HCI-Web-Interaction-Analyzer\\test_window_resize_error.csv')
+        
+    def test_velocity(self):
+        """Test velocity calculation"""
+        # Compute space-time differences
+        df = compute_space_time_diff(self.test_data.copy())
+        
+        # Calculate velocity
+        df_velocity = velocity(df)
+        
+        # Check if the velocity column is added
+        for session_id, traces in df_velocity.items():
+            for trace in traces:
+                self.assertIn('velocity', trace.columns)
+                # Check if velocity values are non-negative
+                self.assertTrue((trace['velocity'] >= 0).all())
+                self.assertGreaterEqual(trace['velocity'].mean(), 0)
+                # Verify velocity calculation
+                dt = trace.timeStamp.diff()
+                dx = trace.x.diff()
+                dy = trace.y.diff()
+                expected_velocity = np.sqrt(dx**2 + dy**2) / dt
+                expected_velocity.fillna(0, inplace=True)
+                np.testing.assert_allclose(trace['velocity'], expected_velocity, rtol=1e-5, atol=1e-8)
+                    
+    def test_acceleration(self):
+        """Test acceleration calculation"""
+        df = compute_space_time_diff(self.test_data.copy())
+        traces_velocity = velocity(df)
+        
+        # Calculate acceleration
+        df_acceleration = acceleration(None, traces_velocity)
+        
+        # Check if the acceleration column is added
+        for session_id, traces in df_acceleration.items():
+            for trace in traces:
+                self.assertIn('acceleration', trace.columns)
+                # Verify acceleration calculation
+                dt = trace.timeStamp.diff()
+                dv = trace['velocity'].diff()
+                expected_acceleration = dv / dt
+                expected_acceleration.fillna(0, inplace=True)
+                np.testing.assert_allclose(trace['acceleration'], expected_acceleration, rtol=1e-5, atol=1e-8)
+
+if __name__ == '__main__':
+    unittest.main()

pywib-0.1.0/test/utils.py

@@ -0,0 +1,43 @@
+import pandas as pd
+from collections import defaultdict
+
+def process_csv(file_path):
+    """
+    Reads a semicolon-separated CSV file and processes it into matrices grouped by sessionId and sceneId.
+    Args:
+        file_path (str): Path to the CSV file.
+    """
+    # Read the CSV file with semicolon separator
+    df = pd.read_csv(file_path, encoding='utf-8', sep=',')
+    
+    # Dictionary to store matrices for each sessionId and sceneId
+    matrices = defaultdict(list)
+
+    # Process each row in the DataFrame
+    for _, row in df.iterrows():
+        session_id = row['sessionId']
+        
+        # Create a key combining sessionId and sceneId
+        key = (session_id)
+        
+        # Extract the relevant values and append to the matrix
+        matrices[key].append([
+            row['eventType'],
+            row['timeStamp'],
+            row['x'],
+            row['y'],
+            row['keyValueEvent'],
+            row['keyCodeEvent'],
+        ])
+    
+    all_sessions = []
+    for (session_id), matrix in matrices.items():
+        df = pd.DataFrame(matrix, columns=[
+            'eventType', 'timeStamp', 'x', 'y', 'keyValueEvent', 'keyCodeEvent' ])
+        df['sessionId'] = session_id
+        all_sessions.append(df)
+
+    df_all_sessions = pd.concat(all_sessions, ignore_index=True)
+    df_all_sessions['timeStamp'] = df_all_sessions['timeStamp'].astype(str).str.replace(',', '', regex=False)
+    df_all_sessions['timeStamp'] = pd.to_numeric(df_all_sessions['timeStamp'], errors='coerce')
+    return df_all_sessions