User Guide

This user guide introduces the core concepts, data structures, and workflows used in pymovements for processing and analyzing eye-tracking data. It is intended for students, researchers, and practitioners who want to move from raw recordings to analysis-ready and reusable datasets.

The guide focuses on conceptual understanding and transparent data processing, rather than step-by-step recipes. Throughout this guide, we emphasize that there is no single “correct” eye-tracking pipeline. Processing choices depend on research goals and data quality, and each transformation introduces assumptions that should be made explicit for reproducible analysis.

• Getting Started
  • Installation Options
  • Understanding Eye-Tracking Data
    • What are Eye-Tracking Data?
    • The Gaze Object
    • Good To Know
• Experiment Configuration
  • Screen
    • Variable Viewing Distance
    • Coordinate Origin
  • EyeTracker
    • Sampling Rate
  • The Experiment Object
  • Loading Experiment from a Dictionary
  • Saving Experiment Settings
• Loading Gaze Data
  • CSV Files
    • Time Information
    • Defining Gaze Components
    • Pixel vs. Position Coordinates
    • Using an Experiment
    • Automatic Column Detection
    • from_csv()
  • EyeLink ASC Files
  • BeGaze Exports
  • IPC (Feather) Files
• Working with Raw Gaze Samples
  • Inspecting Raw Samples with Plots
  • Transforming Raw Samples
    • pix2deg(): From Pixels to Degrees of Visual Angle
    • pos2vel(): From Position to Velocity
• Inspecting Data Quality
• Detecting Occumotoric Events
  • Fixations
  • Saccades
  • Completing Event Segmentation with fill()
  • The Events Object
• Working with Datasets