generate_foreshortening_data#

pypillometry.signal.generate_foreshortening_data(experimental_setup=None, duration=120, fs=1000, eye='left', A0_mean=750, A0_amplitude=100, A0_freq=0.5, fixation_duration_mean=500, fixation_duration_std=100, measurement_noise=5.0, seed=None, **kwargs)[source]#

Generate complete synthetic dataset for testing foreshortening correction algorithm.

Orchestrates: 1. Generate true pupil size A0(t) with slow fluctuations (~0.5 Hz by default) 2. Generate fixation-based gaze positions (x, y) 3. Apply foreshortening: measured_pupil = A0 * cos(alpha(x,y)) 4. Package into FakeEyeData with all metadata and ground truth

Uses algorithm-specific names (A0, cos_alpha) since this function is specifically designed for testing the foreshortening correction algorithm.

Parameters:

  • experimental_setup (ExperimentalSetup) – Experimental setup containing screen geometry (resolution, physical size), eye-to-screen distance (d), and camera position (theta, phi, r). If None, uses defaults: 1920x1080 screen (52x29 cm), d=60cm, camera at theta=20°, phi=-90°, r=70cm.

  • duration (float) – Duration in seconds

  • fs (float) – Sampling rate in Hz

  • eye (str) – Which eye (‘left’ or ‘right’)

  • A0_mean (float) – Mean true pupil size in arbitrary units (typical EyeLink range: 500-1000 AU). Corresponds to area-proportional measurements, not diameter.

  • A0_amplitude (float) – Amplitude of pupil fluctuations (standard deviation of slow variations)

  • A0_freq (float) – Frequency of pupil fluctuations in Hz (controls speed of baseline changes)

  • fixation_duration_mean (float) – Mean fixation duration in ms

  • fixation_duration_std (float) – Standard deviation of fixation duration in ms

  • measurement_noise (float) – Standard deviation of Gaussian measurement noise added to pupil signal (in AU)

  • seed (int) – Random seed for reproducibility

  • **kwargs – additional parameters passed to FakeEyeData

Returns:

data (FakeEyeData) – Synthetic eye-tracking data with:

  • sim_fct: reference to this function

  • sim_fct_name: ‘generate_foreshortening_data’

  • sim_params: all generation parameters

  • sim_data: EyeDataDict with ‘{eye}_A0’ and ‘{eye}_cosalpha’ ground truth

Examples

>>> from pypillometry.signal.fake import generate_foreshortening_data
>>> 
>>> # Use defaults
>>> data = generate_foreshortening_data(duration=60, seed=42)
>>> 
>>> # Or provide custom setup
>>> from pypillometry.eyedata import ExperimentalSetup
>>> setup = ExperimentalSetup(
...     screen_resolution=(1920, 1080),
...     physical_screen_size=("52 cm", "29 cm"),
...     eye_to_screen_center="60 cm",
...     camera_spherical=("20 deg", "-90 deg", "70 cm"),
... )
>>> data = generate_foreshortening_data(setup, duration=60, seed=42)
>>> 
>>> # Access ground truth
>>> A0_true = data.sim_data['left_A0']
>>> cos_alpha_true = data.sim_data['left_cosalpha']