speed-analyzer 3.6.0__tar.gz

speed_analyzer-3.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Laboratorio di Scienze Cognitive e del Comportamento
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

speed_analyzer-3.6.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: speed-analyzer
+Version: 3.6.0
+Summary: A package for processing and extracting eye-tracking data.
+Home-page: https://github.com/danielelozzi/SPEED
+Author: Daniele Lozzi, LabSCoC
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: opencv-python
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Requires-Dist: moviepy
+Requires-Dist: ultralytics
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# SPEED v3.6 - Desktop App & Analysis Package
+
+*An Advanced Eye-Tracking Data Analysis Software*
+
+SPEED is a Python-based project for processing, analyzing, and visualizing eye-tracking data. Version 3.6 introduces a major restructuring, offering two distinct components:
+
+1.  **SPEED Desktop App**: A user-friendly GUI application for running a full analysis pipeline, designed for end-users and researchers.
+2.  **`speed-analyzer`**: A programmatic Python package for developers who want to integrate the analysis logic into their own scripts.
+
+This version also supports GPU acceleration for YOLO analysis.
+
+---
+
+## 1. SPEED Desktop Application (For End Users)
+
+An application with a graphical user interface (GUI) for a complete, visually-driven analysis workflow.
+
+### How to Use the Application
+1.  **Download the latest version**: Go to the [Releases page](https://github.com/danielelozzi/SPEED/releases) and download the `.zip` file for your operating system (Windows or macOS).
+2.  **Extract and Run**: Unzip the file and run the `SpeedApp` executable.
+3.  **Follow the Instructions**: Use the interface to select your data folders (RAW, Un-enriched, etc.), manage events with the interactive editors, and run the analysis.
+
+---
+
+## 2. `speed-analyzer` (Python Package for Developers)
+
+The core analysis engine of SPEED, now available as a reusable package. It's designed for automation and integration into custom data pipelines.
+
+### Installation from PyPI
+You can install the package directly from the Python Package Index (PyPI) using pip:
+```bash
+pip install speed-analyzer
+```
+### How to Use the Package
+The package exposes a main function, `run_full_analysis`, that takes paths and options as arguments. See the `example_usage.py` file for a complete demonstration.
+
+Here is a basic snippet:
+
+```python
+import pandas as pd
+from speed_analyzer import run_full_analysis
+
+# 1. Define paths and parameters
+raw_path = "./data/raw"
+unenriched_path = "./data/unenriched"
+output_path = "./analysis_results"
+
+# 2. Create an events DataFrame
+events_df = pd.DataFrame({
+    'name': ['Task_Start', 'Task_End'],
+    'timestamp [ns]': [1672531201000000000, 1672531215000000000]
+})
+
+# 3. Run the full analysis programmatically
+run_full_analysis(
+    raw_data_path=raw_path,
+    unenriched_data_path=unenriched_path,
+    output_path=output_path,
+    subject_name="participant_01",
+    events_df=events_df,
+    run_yolo=True,
+    yolo_model_path="yolov8n.pt"
+)
+```
+
+---
+
+## The Modular Workflow (GUI)
+SPEED v3.6 operates on a two-step workflow designed to save time and computational resources.
+
+### Step 1: Run Core Analysis
+This is the main data processing stage. You run this step only once per participant for a given set of events. The software will:
+
+- Load all necessary files from the specified input folders (RAW, Un-enriched, Enriched).
+- Dynamically load events from `events.csv` into the GUI, allowing you to select which events to analyze.
+- Segment the data based on your selection.
+- Calculate all relevant statistics for each selected segment.
+- Optionally run YOLO object detection on the video frames, saving the results to a cache to speed up future runs.
+- Save the processed data (e.g., filtered dataframes for each event) and summary statistics into the output folder.
+
+This step creates a `processed_data` directory containing intermediate files. Once this is complete, you do not need to run it again unless you want to analyze a different combination of events.
+
+### Step 2: Generate Outputs On-Demand
+After the core analysis is complete, you can use the dedicated tabs in the GUI to generate as many plots and videos as you need, with any combination of settings, without re-processing the raw data.
+
+- **Generate Plots**: Select which categories of plots you want to create.
+- **Generate Videos**: Compose highly customized videos with various overlays.
+- **View YOLO Results**: Load and view the quantitative results from the object detection.
+
+---
+
+## Environment Setup (For Development) ⚙️
+To run the project from source or contribute to development, you'll need Python 3 and several libraries.
+
+1. **Install Anaconda**: [Link](https://www.anaconda.com/)
+2. *(Optional)* Install CUDA Toolkit: For GPU acceleration with NVIDIA. [Link](https://developer.nvidia.com/cuda-downloads)
+3. **Create a virtual environment**:
+```bash
+conda create --name speed
+conda activate speed
+conda install pip
+```
+4. **Install the required libraries**:
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## How to Use the Application from Source 🚀
+### Launch the GUI:
+```bash
+# Navigate to the desktop_app folder
+cd desktop_app
+python GUI.py
+```
+### Setup and Analysis:
+- Fill in the Participant Name and select the Output Folder.
+- Select the required Input Folders: RAW and Un-enriched.
+- Use the Advanced Event Management section to load and edit events using the table or interactive video editor.
+- Click **"RUN CORE ANALYSIS"**.
+- Use the other tabs to generate plots, videos, and view YOLO results.
+
+---
+
+## 🧪 Synthetic Data Generator (`generate_synthetic_data.py`)
+Included in this project is a utility script to create a full set of dummy eye-tracking data. This is extremely useful for testing the SPEED software without needing Pupil Labs hardware or actual recordings.
+
+### How to Use
+Run the script from your terminal:
+```bash
+python generate_synthetic_data.py
+```
+The script will create a new folder named `synthetic_data_output` in the current directory.
+
+This folder will contain all the necessary files (`gaze.csv`, `fixations.csv`, `external.mp4`, etc.), ready to be used as input for the GUI application or the `speed-analyzer` package.
+
+---
+
+## ✍️ Authors & Citation
+This tool is developed by the Cognitive and Behavioral Science Lab (LabSCoC), University of L'Aquila and Dr. Daniele Lozzi.
+
+If you use this script in your research or work, please cite the following publications:
+
+- Lozzi, D.; Di Pompeo, I.; Marcaccio, M.; Ademaj, M.; Migliore, S.; Curcio, G. SPEED: A Graphical User Interface Software for Processing Eye Tracking Data. NeuroSci 2025, 6, 35. https://doi.org/10.3390/neurosci6020035
+- Lozzi, D.; Di Pompeo, I.; Marcaccio, M.; Alemanno, M.; Krüger, M.; Curcio, G.; Migliore, S. AI-Powered Analysis of Eye Tracker Data in Basketball Game. Sensors 2025, 25, 3572. https://doi.org/10.3390/s25113572
+
+It is also requested to cite Pupil Labs publication, as requested on their website https://docs.pupil-labs.com/neon/data-collection/publication-and-citation/
+
+- Baumann, C., & Dierkes, K. (2023). Neon accuracy test report. Pupil Labs, 10. https://doi.org/10.5281/zenodo.10420388
+
+If you also use the Computer Vision YOLO-based feature, please cite the following publication:
+
+- Redmon, J., Divvala, S., Girshick, R., & Farhadi, A. (2016). You only look once: Unified, real-time object detection. In Proceedings of the IEEE conference on computer vision and pattern recognition (pp. 779-788). https://doi.org/10.1109/CVPR.2016.91
+
+---
+
+## 💻 Artificial Intelligence disclosure
+This code is partially written using Google Gemini 2.5 Pro

speed_analyzer-3.6.0/README.md

@@ -0,0 +1,159 @@
+# SPEED v3.6 - Desktop App & Analysis Package
+
+*An Advanced Eye-Tracking Data Analysis Software*
+
+SPEED is a Python-based project for processing, analyzing, and visualizing eye-tracking data. Version 3.6 introduces a major restructuring, offering two distinct components:
+
+1.  **SPEED Desktop App**: A user-friendly GUI application for running a full analysis pipeline, designed for end-users and researchers.
+2.  **`speed-analyzer`**: A programmatic Python package for developers who want to integrate the analysis logic into their own scripts.
+
+This version also supports GPU acceleration for YOLO analysis.
+
+---
+
+## 1. SPEED Desktop Application (For End Users)
+
+An application with a graphical user interface (GUI) for a complete, visually-driven analysis workflow.
+
+### How to Use the Application
+1.  **Download the latest version**: Go to the [Releases page](https://github.com/danielelozzi/SPEED/releases) and download the `.zip` file for your operating system (Windows or macOS).
+2.  **Extract and Run**: Unzip the file and run the `SpeedApp` executable.
+3.  **Follow the Instructions**: Use the interface to select your data folders (RAW, Un-enriched, etc.), manage events with the interactive editors, and run the analysis.
+
+---
+
+## 2. `speed-analyzer` (Python Package for Developers)
+
+The core analysis engine of SPEED, now available as a reusable package. It's designed for automation and integration into custom data pipelines.
+
+### Installation from PyPI
+You can install the package directly from the Python Package Index (PyPI) using pip:
+```bash
+pip install speed-analyzer
+```
+### How to Use the Package
+The package exposes a main function, `run_full_analysis`, that takes paths and options as arguments. See the `example_usage.py` file for a complete demonstration.
+
+Here is a basic snippet:
+
+```python
+import pandas as pd
+from speed_analyzer import run_full_analysis
+
+# 1. Define paths and parameters
+raw_path = "./data/raw"
+unenriched_path = "./data/unenriched"
+output_path = "./analysis_results"
+
+# 2. Create an events DataFrame
+events_df = pd.DataFrame({
+    'name': ['Task_Start', 'Task_End'],
+    'timestamp [ns]': [1672531201000000000, 1672531215000000000]
+})
+
+# 3. Run the full analysis programmatically
+run_full_analysis(
+    raw_data_path=raw_path,
+    unenriched_data_path=unenriched_path,
+    output_path=output_path,
+    subject_name="participant_01",
+    events_df=events_df,
+    run_yolo=True,
+    yolo_model_path="yolov8n.pt"
+)
+```
+
+---
+
+## The Modular Workflow (GUI)
+SPEED v3.6 operates on a two-step workflow designed to save time and computational resources.
+
+### Step 1: Run Core Analysis
+This is the main data processing stage. You run this step only once per participant for a given set of events. The software will:
+
+- Load all necessary files from the specified input folders (RAW, Un-enriched, Enriched).
+- Dynamically load events from `events.csv` into the GUI, allowing you to select which events to analyze.
+- Segment the data based on your selection.
+- Calculate all relevant statistics for each selected segment.
+- Optionally run YOLO object detection on the video frames, saving the results to a cache to speed up future runs.
+- Save the processed data (e.g., filtered dataframes for each event) and summary statistics into the output folder.
+
+This step creates a `processed_data` directory containing intermediate files. Once this is complete, you do not need to run it again unless you want to analyze a different combination of events.
+
+### Step 2: Generate Outputs On-Demand
+After the core analysis is complete, you can use the dedicated tabs in the GUI to generate as many plots and videos as you need, with any combination of settings, without re-processing the raw data.
+
+- **Generate Plots**: Select which categories of plots you want to create.
+- **Generate Videos**: Compose highly customized videos with various overlays.
+- **View YOLO Results**: Load and view the quantitative results from the object detection.
+
+---
+
+## Environment Setup (For Development) ⚙️
+To run the project from source or contribute to development, you'll need Python 3 and several libraries.
+
+1. **Install Anaconda**: [Link](https://www.anaconda.com/)
+2. *(Optional)* Install CUDA Toolkit: For GPU acceleration with NVIDIA. [Link](https://developer.nvidia.com/cuda-downloads)
+3. **Create a virtual environment**:
+```bash
+conda create --name speed
+conda activate speed
+conda install pip
+```
+4. **Install the required libraries**:
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## How to Use the Application from Source 🚀
+### Launch the GUI:
+```bash
+# Navigate to the desktop_app folder
+cd desktop_app
+python GUI.py
+```
+### Setup and Analysis:
+- Fill in the Participant Name and select the Output Folder.
+- Select the required Input Folders: RAW and Un-enriched.
+- Use the Advanced Event Management section to load and edit events using the table or interactive video editor.
+- Click **"RUN CORE ANALYSIS"**.
+- Use the other tabs to generate plots, videos, and view YOLO results.
+
+---
+
+## 🧪 Synthetic Data Generator (`generate_synthetic_data.py`)
+Included in this project is a utility script to create a full set of dummy eye-tracking data. This is extremely useful for testing the SPEED software without needing Pupil Labs hardware or actual recordings.
+
+### How to Use
+Run the script from your terminal:
+```bash
+python generate_synthetic_data.py
+```
+The script will create a new folder named `synthetic_data_output` in the current directory.
+
+This folder will contain all the necessary files (`gaze.csv`, `fixations.csv`, `external.mp4`, etc.), ready to be used as input for the GUI application or the `speed-analyzer` package.
+
+---
+
+## ✍️ Authors & Citation
+This tool is developed by the Cognitive and Behavioral Science Lab (LabSCoC), University of L'Aquila and Dr. Daniele Lozzi.
+
+If you use this script in your research or work, please cite the following publications:
+
+- Lozzi, D.; Di Pompeo, I.; Marcaccio, M.; Ademaj, M.; Migliore, S.; Curcio, G. SPEED: A Graphical User Interface Software for Processing Eye Tracking Data. NeuroSci 2025, 6, 35. https://doi.org/10.3390/neurosci6020035
+- Lozzi, D.; Di Pompeo, I.; Marcaccio, M.; Alemanno, M.; Krüger, M.; Curcio, G.; Migliore, S. AI-Powered Analysis of Eye Tracker Data in Basketball Game. Sensors 2025, 25, 3572. https://doi.org/10.3390/s25113572
+
+It is also requested to cite Pupil Labs publication, as requested on their website https://docs.pupil-labs.com/neon/data-collection/publication-and-citation/
+
+- Baumann, C., & Dierkes, K. (2023). Neon accuracy test report. Pupil Labs, 10. https://doi.org/10.5281/zenodo.10420388
+
+If you also use the Computer Vision YOLO-based feature, please cite the following publication:
+
+- Redmon, J., Divvala, S., Girshick, R., & Farhadi, A. (2016). You only look once: Unified, real-time object detection. In Proceedings of the IEEE conference on computer vision and pattern recognition (pp. 779-788). https://doi.org/10.1109/CVPR.2016.91
+
+---
+
+## 💻 Artificial Intelligence disclosure
+This code is partially written using Google Gemini 2.5 Pro

speed_analyzer-3.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

speed_analyzer-3.6.0/setup.py

@@ -0,0 +1,30 @@
+# setup.py
+from setuptools import setup, find_packages
+
+setup(
+    name="speed-analyzer",
+    version="3.6.0",
+    author="Daniele Lozzi, LabSCoC",
+    description="A package for processing and extracting eye-tracking data.",
+    long_description=open('README.md').read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/danielelozzi/SPEED", # Sostituisci con l'URL del tuo repo
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.10',
+    install_requires=[
+        "pandas",
+        "numpy",
+        "matplotlib",
+        "opencv-python",
+        "scipy",
+        "tqdm",
+        "moviepy",
+        "ultralytics"
+    ]
+)

speed_analyzer-3.6.0/src/speed_analyzer/__init__.py

@@ -0,0 +1,112 @@
+# src/speed_analyzer/__init__.py
+import pandas as pd
+from pathlib import Path
+import json
+import shutil
+import logging
+from typing import Optional, Dict
+
+# Importa i moduli di analisi dalla sottocartella
+from .analysis_modules import speed_script_events
+from .analysis_modules import yolo_analyzer
+from .analysis_modules import video_generator
+
+# Esporta la funzione principale per renderla accessibile con "from speed_analyzer import run_full_analysis"
+__all__ = ["run_full_analysis"]
+
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+
+def _prepare_working_directory(output_dir: Path, raw_dir: Path, unenriched_dir: Path, enriched_dir: Optional[Path], events_df: pd.DataFrame):
+    working_dir = output_dir / 'eyetracking_files'
+    working_dir.mkdir(parents=True, exist_ok=True)
+    logging.info(f"Preparing working directory at: {working_dir}")
+    try:
+        external_video_path = next(unenriched_dir.glob('*.mp4'))
+    except StopIteration:
+        raise FileNotFoundError(f"No .mp4 file found in {unenriched_dir}")
+    file_map = {
+        'internal.mp4': raw_dir / 'Neon Sensor Module v1 ps1.mp4',
+        'external.mp4': external_video_path,
+        'fixations.csv': unenriched_dir / 'fixations.csv',
+        'gaze.csv': unenriched_dir / 'gaze.csv',
+        'blinks.csv': unenriched_dir / 'blinks.csv',
+        'saccades.csv': unenriched_dir / 'saccades.csv',
+        '3d_eye_states.csv': unenriched_dir / '3d_eye_states.csv',
+        'world_timestamps.csv': unenriched_dir / 'world_timestamps.csv',
+    }
+    if enriched_dir:
+        file_map.update({
+            'surface_positions.csv': enriched_dir / 'surface_positions.csv',
+            'gaze_enriched.csv': enriched_dir / 'gaze.csv',
+            'fixations_enriched.csv': enriched_dir / 'fixations.csv',
+        })
+    for dest, source in file_map.items():
+        if source and source.exists():
+            shutil.copy(source, working_dir / dest)
+        else:
+            logging.warning(f"Optional file not found and not copied: {source}")
+    if not events_df.empty:
+        events_df.to_csv(working_dir / 'events.csv', index=False)
+    return working_dir
+
+def run_full_analysis(
+    raw_data_path: str, unenriched_data_path: str, output_path: str, subject_name: str,
+    enriched_data_path: Optional[str] = None, events_df: Optional[pd.DataFrame] = None,
+    run_yolo: bool = False, yolo_model_path: str = 'yolov8n.pt',
+    generate_plots: bool = True, plot_selections: Optional[Dict[str, bool]] = None,
+    generate_video: bool = True, video_options: Optional[Dict] = None
+) -> Path:
+    raw_dir = Path(raw_data_path)
+    unenriched_dir = Path(unenriched_data_path)
+    output_dir = Path(output_path)
+    enriched_dir = Path(enriched_data_path) if enriched_data_path else None
+    output_dir.mkdir(parents=True, exist_ok=True)
+    un_enriched_mode = enriched_dir is None
+
+    if events_df is None:
+        logging.info("No events DataFrame provided, loading 'events.csv' from un-enriched folder.")
+        events_file = unenriched_dir / 'events.csv'
+        events_df = pd.read_csv(events_file) if events_file.exists() else pd.DataFrame()
+
+    working_dir = _prepare_working_directory(output_dir, raw_dir, unenriched_dir, enriched_dir, events_df)
+    selected_event_names = events_df['name'].tolist() if not events_df.empty else []
+
+    logging.info(f"--- STARTING CORE ANALYSIS FOR {subject_name} ---")
+    speed_script_events.run_analysis(
+        subj_name=subject_name, data_dir_str=str(working_dir), output_dir_str=str(output_dir),
+        un_enriched_mode=un_enriched_mode, selected_events=selected_event_names
+    )
+    logging.info("--- CORE ANALYSIS COMPLETE ---")
+
+    if run_yolo:
+        logging.info("--- STARTING YOLO ANALYSIS ---")
+        yolo_analyzer.run_yolo_analysis(
+            data_dir=working_dir, output_dir=output_dir, subj_name=subject_name, model_path=yolo_model_path
+        )
+        logging.info("--- YOLO ANALYSIS COMPLETE ---")
+
+    if generate_plots:
+        logging.info("--- STARTING PLOT GENERATION ---")
+        if plot_selections is None:
+            plot_selections = { "path_plots": True, "heatmaps": True, "histograms": True, "pupillometry": True, "advanced_timeseries": True, "fragmentation": True }
+        config = {"unenriched_mode": un_enriched_mode, "source_folders": {"unenriched": str(unenriched_dir)}}
+        with open(output_dir / 'config.json', 'w') as f: json.dump(config, f)
+        speed_script_events.generate_plots_on_demand(
+            output_dir_str=str(output_dir), subj_name=subject_name,
+            plot_selections=plot_selections, un_enriched_mode=un_enriched_mode
+        )
+        logging.info("--- PLOT GENERATION COMPLETE ---")
+
+    if generate_video:
+        logging.info("--- STARTING VIDEO GENERATION ---")
+        if video_options is None:
+            video_options = { "output_filename": f"video_output_{subject_name}.mp4", "overlay_gaze": True, "overlay_event_text": True }
+        video_generator.create_custom_video(
+            data_dir=working_dir, output_dir=output_dir, subj_name=subject_name,
+            options=video_options, un_enriched_mode=un_enriched_mode,
+            selected_events=selected_event_names
+        )
+        logging.info("--- VIDEO GENERATION COMPLETE ---")
+
+    logging.info(f"Analysis complete. Results saved in: {output_dir.resolve()}")
+    return output_dir