fake_pupil_baseline#

pypillometry.signal.fake_pupil_baseline(duration, fs, mean=750, amplitude=100, freq=0.5, filter_order=4, seed=None)[source]#

Generate smooth baseline pupil size via filtered noise.

Creates pupil size time series by: 1. Generating white noise 2. Low-pass filtering at specified frequency with edge handling 3. Scaling to desired amplitude and mean

Parameters:

  • duration (float) – Duration in seconds

  • fs (float) – Sampling rate in Hz

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

  • amplitude (float, default 100) – Amplitude of slow fluctuations (standard deviation of baseline variations)

  • freq (float, default 0.5) – Cutoff frequency for low-pass filter (Hz), controls fluctuation speed. Typical values: 0.1-0.5 Hz for spontaneous fluctuations, 0.5-1 Hz for cognitive load changes, 1-3 Hz for fast responses.

  • filter_order (int, default 4) – Order of Butterworth filter. Higher order = sharper cutoff. Roll-off is (filter_order * 6) dB/octave.

  • seed (int, optional) – Random seed for reproducibility

Returns:

  • t (np.ndarray) – Time vector (ms)

  • true_pupil (np.ndarray) – True pupil size time series

  • params (dict) – Parameters used for generation

Examples

>>> t, pupil, params = fake_pupil_baseline(duration=10, fs=1000, seed=42)
>>> print(f"Mean: {pupil.mean():.2f}, Std: {pupil.std():.2f}")
Mean: 743.57, Std: 100.00