prpip

Overview

prpip is a Python package that reconstructs pupil size during blinks in eye-tracking data using a physiologically inspired approach. It addresses a common challenge in eye-tracking studies where blinks cause missing pupil data, potentially disrupting analyses of pupillary responses.

Features

• Automatically detects blink intervals in eye-tracking data
• Reconstructs pupil size during blinks using logarithmic recovery with dynamic adjustment of the recovery time constant (τ)
• Incorporates Gaussian noise to mimic natural variability in pupil size measurements
• Validates input data to ensure compatibility and provides clear error messages for invalid inputs
• Supports multiple input formats: CSV, Excel, JSON, Parquet, and TXT
• Flexible output options: add a new column for reconstructed data or replace the original pupil size column

Installation

Install the latest version of prpip from PyPI:

pip install prpip

Quick Start

1. Import the Package

from prpip import process_pupil

2. Process an Entire Dataset

import pandas as pd

data = pd.read_csv("input.csv")
processed_data = process_pupil(data)
processed_data.to_csv("reconstructed.csv", index=False)

3. Process Data from Other Formats

processed_data = process_pupil("input.parquet")
processed_data.to_excel("reconstructed.xlsx", index=False)

4. Plot the Results

import matplotlib.pyplot as plt

plt.figure(figsize=(14, 7))
plt.plot(processed_data['Trial Time'], processed_data['Pupil Size'], 
         label='Original Pupil Size (with Blinks)', alpha=0.6)
plt.plot(processed_data['Trial Time'], processed_data['Reconstructed Pupil Size'], 
         label='Reconstructed Pupil Size', linestyle='--')
plt.xlabel('Time (ms)', fontsize=14)
plt.ylabel('Pupil Size (AU)', fontsize=14)
plt.title('Original vs Reconstructed Pupil Size', fontsize=16)
plt.legend(fontsize=12)
plt.grid(True)
plt.show()

Input Requirements

The input data must be in one of the following formats: CSV, Excel, JSON, TXT, or Parquet. It should contain the following columns:

• Trial: Identifies the trial number
• Pupil Size: The measured pupil size

Output

The output DataFrame includes a new column:

• Reconstructed Pupil Size: Contains the reconstructed values during blinks

Alternatively, you can replace the original Pupil Size column with the reconstructed values.

Advanced Parameters

You can customize reconstruction behavior by adjusting the following optional parameters:

• blink_threshold: Threshold for detecting blinks. Default is 1000
• tau_base: Base recovery time constant for logarithmic reconstruction. Default is 50
• noise_scale: Scale of Gaussian noise added to reconstructions. Default is 0.05

processed_data = process_pupil(
    "input.json",
    blink_threshold=1200,
    tau_base=60,
    noise_scale=0.1
)