眼动数据处理新利器:PupEyes开源Python库全面解析
- 2026-02-06 19:25:30
眼动追踪技术作为认知心理学、人机交互、神经科学等领域的重要研究工具，近年来随着开源工具的普及而变得更加易于获取。
然而，眼动数据处理中存在着显著的变异性，尤其是在瞳孔大小和注视数据处理方面。尽管已有文献提出了数据预处理的最佳实践，但在Python环境中实现这些实践的工具仍然有限。
今天，我们为您详细介绍一款名为 PupEyes 的开源Python库——这是一个专门用于瞳孔大小和注视数据预处理与可视化的强大工具。
本文将为您揭示PupEyes如何帮助研究人员遵循最佳实践、确保数据处理的可重复性，并通过交互式可视化工具深入了解数据质量。
技术细节：
GitHub仓库：https://github.com/HanZhang-psych/pupeyes
可执行教程：https://pupeyes.readthedocs.io/
Python要求：3.10或更高版本
推荐环境：Jupyter Notebook
01 / PupEyes的核心特性
1. 基于最佳实践的数据处理流程
PupEyes的瞳孔预处理功能基于当前文献中的最佳实践开发，确保瞳孔大小数据以原则性、透明且可重复的方式进行预处理。这一特性对于确保研究结果的可靠性至关重要。
图1：使用PupEyes进行瞳孔大小预处理的典型步骤流程图
2. 强大的交互式可视化
PupEyes提供多种交互式可视化工具，使研究人员能够：
探索数据并检查单个试次
识别潜在异常值
在预处理管道的任何阶段检查数据质量
图2：Pupil Viewer界面截图，允许用户交互式检查每个预处理步骤的瞳孔追踪
3. 与pandas无缝集成
PupEyes使用pandas数据结构，为研究人员提供Python生态系统中强大的数据操作、分析和可视化工具。
这种集成不仅提高了数据处理效率，还使得PupEyes能够与其他常用Python包（如statsmodels和MNE）无缝协作。
02 / 数据读取与预处理流程
1. 支持多款眼动仪数据
PupEyes支持从多款眼动仪收集的数据，以及任何符合最小格式标准的通用数据集。此外，PupEyes可以读取从EDF格式转换而来的ASC格式数据。
图3：某 .asc数据片段，以"MSG"开头的行表示标记试验事件的自定义消息
2. 完整的瞳孔预处理管道
PupEyes的预处理流程包括以下关键步骤：
(1) 去眨眼处理
使用Hershman等人（2018）开发的眨眼检测算法，有效去除眨眼期间以及眼睑开合期间的样本。
图4：去眨眼后的数据，新创建的"pp_db"列表示去眨眼后的瞳孔大小
(2) 伪迹剔除
PupEyes实现artifact_rejection()方法，提供两种伪迹剔除方法：
瞳孔大小快速变化检测：基于瞳孔速度阈值
极端瞳孔大小检测：基于z分数和变异系数阈值
(3) 注视位置过滤
允许用户定义瞳孔测量的有效区域，任何落在该区域外的样本都被设置为缺失值，有助于减轻瞳孔远视误差（PFE）。
图5：瞳孔远视误差表面图，显示记录样本随注视坐标变化的二维直方图
(4) 平滑处理
提供多种平滑方法，包括Hann窗口、滚动平均值和Butterworth低通滤波器。
(5) 插值
支持线性插值和三次样条插值两种常用方法，允许设置最大缺失值比例阈值。
(6) 基线校正
提供减法和除法两种基线校正方法，默认使用减法方法以避免产生异常值追踪。
图6：使用check_baseline_outliers()生成的基线直方图，虚线标注异常值阈值
03 / 数据质量检查与诊断工具
1. 交互式瞳孔查看器
Pupil Viewer允许用户交互式检查每个预处理步骤的瞳孔追踪。用户可以使用悬停、拖拽和缩放等交互功能探索数据，通过下拉菜单选择任何试验进行检查。
2. 追踪spaghetti plot
在追踪意大利面图中，所有瞳孔追踪都作为时间的函数被绘制。高质量数据通常表现为密集的线条缠结。
图7：使用check_trace_outliers()生成的追踪spaghetti plot，基于包含10个试验的示例数据集
3. 试验排除标准定义
summary()方法返回一个pandas数据框，提供应用于数据的预处理步骤的概述，包括check_baseline_outliers()和check_trace_outliers()方法标记为异常值的试验信息。
图8：由summary()返回的每个试验的预处理摘要
04 / 注视数据处理功能
除了瞳孔数据，PupEyes还包括：
1. 注视查看器
Fixation Viewer允许交互式可视化注视数据，提供三种可视化：
扫描路径回放
注视密度图（热图）
AOI（兴趣区域）图
图9：Fixation Viewer界面截图
2. AOI绘图工具
AOI Drawer工具允许用户绘制AOI，支持自由形状、矩形或圆形，并可编辑现有AOI以调整其大小或形状。
图10：AOI Drawer界面截图
3. AOI基础指标计算
compute_aoi_statistics()函数根据AOI分配计算摘要指标，包括每个AOI的注视次数和总注视持续时间。
图11：由PupEyes计算的AOI基础指标
五、与其他工具的比较
根据文献中的比较分析（表1），PupEyes在多个方面具有独特优势：
表 1：PupEyes 与其他几种眼动追踪分析软件包的比较
与pypillometry相比：PupEyes提供更全面的交互式可视化，支持注视数据处理和AOI指标计算
与PyTrack相比：PupEyes提供可定制的预处理管道，而非硬编码的处理流程
与R包（gazeR、pupillometry等）相比：PupEyes提供交互式瞳孔和注视数据可视化
与MATLAB包（CHAP、PuPl）相比：PupEyes设计为同时处理瞳孔大小和注视数据
在眼动研究日益普及的今天，选择正确的数据处理工具至关重要。PupEyes作为一款开源Python库，为眼动数据处理带来了革命性的改进。
