eyeris: A flexible, extensible, and reproducible pupillometry preprocessing framework in R

本文介绍了 eyeris，一个基于 R 语言的开源、模块化且符合 FAIR 原则的瞳孔测量数据预处理框架，旨在通过提供标准化的信号处理流程、交互式质量报告及可扩展的数据库存储，解决该领域缺乏统一工具的问题并提升研究的可重复性。

要点

这篇论文介绍了一个名为 eyeris 的新工具，它就像是为“瞳孔测量学”（研究瞳孔大小变化的科学）量身打造的一套全自动、透明且智能的“数据清洗与整理工厂”。

为了让你更容易理解，我们可以把瞳孔测量研究想象成在一条繁忙的河流上收集水滴，而 eyeris 就是那条高科技的引水渠和净化系统。

以下是用通俗语言和比喻对这篇论文的解读：

1. 背景：为什么我们需要 eyeris？

现状：
瞳孔的大小会随着我们的注意力、压力、情绪甚至大脑的疲劳程度而变化。科学家想通过测量瞳孔来窥探人的内心世界。但是，收集到的原始数据（就像刚从河里舀上来的水）往往很“脏”：

• 眨眼会让数据突然中断（像河面突然被石头挡住）。
• 头动或设备抖动会产生奇怪的尖峰（像水面上突然溅起的浪花）。
• 数据缺失（像河里有几个空洞）。

问题：
以前，科学家们处理这些数据就像每个人都在用自己的方法修路。有的用铲子，有的用挖掘机，有的甚至用手挖。虽然大家都能把路修通，但修出来的路宽窄不一、材料不同，导致大家没法互相比较结果，也很难重复别人的实验。这就好比每个人都在用不同的食谱做蛋糕，最后做出来的味道千差万别，没人知道到底哪个配方才是“正宗”的。

解决方案：
eyeris 就是为了解决这个问题而生的。它就像是一个标准化的“中央厨房”，提供了一套经过科学验证的、标准的食谱，让所有科学家都能做出一样高质量、可比较的“蛋糕”（数据）。

2. eyeris 的核心功能：它是如何工作的？

eyeris 的核心是一个叫 glassbox（玻璃盒） 的流水线。这个名字非常形象，因为它不像“黑盒子”那样把数据扔进去就变魔术，而是透明的，你可以清楚地看到每一步发生了什么。

这个流水线包含几个关键步骤，我们可以用**“清洗和整理照片”**来打比方：

1. 加载数据 (load_asc)：
   • 就像把相机里的存储卡插进电脑，把原始照片导出来。
2. 去除眨眼 (deblink)：
   • 比喻：就像修图时把照片里闭眼的部分涂掉。
   • 操作：当人眨眼时，瞳孔数据会消失。eyeris 不仅把眨眼的那几毫秒删掉，还会把眨眼前后可能受影响的“模糊边缘”也切掉，防止残留的噪点。
3. 去除瞬态干扰 (detransient)：
   • 比喻：就像修图时把照片里突然出现的飞虫或手抖造成的模糊斑点抹平。
   • 操作：如果数据突然像过山车一样剧烈跳动（通常是因为头动了），系统会自动识别并把这些不正常的“尖峰”剔除。
4. 填补空缺 (interpolate)：
   • 比喻：就像用 Photoshop 的“内容识别填充”功能，把刚才切掉的眨眼部分，根据前后的样子智能地“画”回去，让照片看起来是连续的。
5. 平滑处理 (lpfilt)：
   • 比喻：就像给照片加一层柔光滤镜，去掉那些细碎的噪点，让画面更清晰流畅。
   • 操作：瞳孔的变化通常是缓慢的，所以系统会过滤掉那些高频的、无意义的噪音。
6. 标准化 (zscore)：
   • 比喻：就像把不同身高的人的身高数据，都换算成“相对于平均身高的标准分”。
   • 操作：每个人的瞳孔大小天生不同（有人大，有人小）。为了让大家的数据能放在一起比较，eyeris 会把每个人的数据都调整到同一个标准尺度上。

3. 它的三大“超能力”

A. “玻璃盒”设计：透明且可控

很多软件是“黑盒子”，你按个按钮，它给你结果，但你不知道它内部怎么算的。
eyeris 是“玻璃盒”。你可以随时停下来，看看每一步处理后的数据长什么样（就像在修图软件里看“处理前”和“处理后”的对比图）。如果你觉得某个步骤太激进，你可以随时调整参数。它既给了新手“一键处理”的便利，也给了专家“手动微调”的自由。

B. 自动生成的“体检报告”

以前，科学家处理完数据后，很难向别人证明自己的数据是干净的。
eyeris 会自动生成一份交互式 HTML 报告（就像一份详细的体检单）。这份报告里包含了：

• 原始数据长什么样？
• 每一步处理后变成了什么样？
• 哪些数据被剔除了？
• 甚至还能让你像浏览相册一样，快速检查成千上万次实验的数据质量。
  这让科学研究变得极其透明，任何人都可以复查你的工作。

C. 像图书馆一样管理海量数据

随着研究规模变大，数据文件多得像图书馆里的书，用 Excel 表格（CSV 文件）管理会非常混乱且慢。
eyeris 引入了一个数据库系统（DuckDB）。

• 比喻：以前是把几千本书散乱地堆在地上（CSV 文件），找一本书要跑断腿。现在 eyeris 把这些书整齐地放进一个智能图书馆里。
• 好处：你可以瞬间搜索到所有参与者的特定数据，不需要把几百万行数据全部加载到内存里。这让处理大规模研究变得像查字典一样快。

4. 总结：为什么这很重要？

这篇论文不仅仅是在介绍一个软件，它是在制定行业标准。

• 以前：做瞳孔研究就像每个人都在用不同的方言说话，很难互相理解，也很难重复验证。
• 现在：有了 eyeris，大家开始用同一种“普通话”说话。它让数据处理变得标准化、透明化、可重复。

这就好比在 fMRI（核磁共振）和 EEG（脑电图）领域已经有了像 fMRIPrep 这样的黄金标准工具一样，eyeris 让瞳孔测量研究也拥有了自己的“黄金标准”。它让科学家能更专注于发现大脑的奥秘，而不是浪费时间在清洗和整理数据的繁琐工作中。

一句话总结：
eyeris 是一个让瞳孔数据从“脏乱差”变成“干净、标准、可信赖”的智能管家，它让科学研究变得更加透明、高效和公平。

技术摘要

这是一份关于 eyeris 的详细技术总结，该论文介绍了一个用于瞳孔测量（pupillometry）数据预处理的灵活、可扩展且可重现的 R 语言框架。

1. 研究背景与问题 (Problem)

瞳孔测量学作为一种非侵入性的心理生理指标，能够反映自主神经和认知过程（如唤醒度、注意力、压力和情绪状态）。然而，该领域在数据处理方面面临以下关键挑战：

• 缺乏标准化框架：与功能性磁共振成像（fMRI）和脑电图（EEG）领域拥有如 fMRIPrep、EEGLAB 等公认的“金标准”工具不同，瞳孔测量研究缺乏统一、标准化的预处理框架。
• 可重复性危机：现有的预处理工具往往缺乏基于 FAIR 原则（可查找、可访问、可互操作、可重用）的设计。许多现有方案流程僵化，或者将预处理步骤从分析项目中剥离，导致研究人员难以在预处理选择上保持透明，也难以直观对比原始数据与处理后的数据。
• “分叉路径”问题 (Garden of Forking Paths)：由于缺乏标准化的预处理流程，研究人员在数据处理步骤（如滤波、缺失值处理、伪影去除）上拥有过多的自由度。这种灵活性可能导致微小的调整显著改变分析结果，增加 I 类错误（假阳性）的风险，从而损害科学结论的可靠性。
• 质量控制困难：现有的工具缺乏针对单个试次（trial-level）的交互式质量检查（QC）报告，使得研究人员难以高效地审查大量数据。

2. 方法论 (Methodology)

为了解决上述问题，作者开发了 eyeris，一个完全用 R 语言编写的开源软件包。其核心设计理念是“玻璃盒”（Glass-box）原则，即既提供预设的最佳实践流程，又保持每一步的透明度和可配置性。

核心架构与流程

eyeris 的主要入口函数是 glassbox()，它执行一个严格定义的、顺序执行的预处理流水线。该流程包含以下关键步骤：

1. 数据加载与解析 (load_asc)：解析 SR Research EyeLink 的 .asc 文件，提取原始时间序列、事件消息、眨眼事件及元数据。支持双目记录的处理（平均或独立处理）。
2. 眨眼伪影去除 (deblink)：通过 NA 填充（NA-padding）移除眨眼期间的数据。为了掩盖眨眼前后的部分遮挡伪影，默认将缺失数据向前后各延伸 50ms（可配置）。
3. 瞬态伪影去除 (detransient)：基于速度阈值检测并移除非生理性的瞬态尖峰（如跟踪不稳定或头部移动引起）。使用中位数绝对偏差（MAD）计算速度分布的阈值（默认设为中位数速度 + 16 倍 MAD）。
4. 线性插值 (interpolate)：使用线性插值填补因眨眼和伪影去除产生的缺失值，恢复连续的时间轨迹。
5. 低通滤波 (lpfilt)：应用巴特沃斯低通滤波器（Butterworth filter）平滑数据。默认截止频率为 4Hz（通带）和 8Hz（阻带），自动确定滤波器阶数以确保数值稳定性。
6. 下采样 (downsample)：在应用抗混叠低通滤波后降低采样率，保留原始时间动态，避免频谱混叠。
7. 分箱 (bin)：提供替代方案，将时间序列划分为固定时间间隔并计算均值或中位数（注意：分箱可能会衰减快速瞳孔动态）。
8. 去趋势 (detrend)：可选步骤，移除随时间缓慢变化的线性漂移（如“任务时间效应”）。默认关闭，因为基线校正通常已处理此问题，且线性去趋势可能引入偏差或移除有意义的生理信号。
9. Z 分数标准化 (zscore)：默认开启。将瞳孔数据标准化为均值为 0、标准差为 1。这有助于消除个体间瞳孔大小绝对值的生理差异，使不同被试的数据具有可比性，专注于相对动态变化。

辅助功能

• 试次提取 (epoch)：支持基于事件消息字符串（Event Messages）灵活提取试次数据。支持通配符（如 PROBE_START_*）和结构化语法（如 PROBE_{trial}_{stimulus}），自动解析元数据并生成整洁的数据框。支持固定时长或动态时长（基于起止事件）的提取。
• BIDS 风格导出 (bidsify)：将预处理后的数据、原始数据、诊断图表和元数据自动组织成类似 BIDS（Brain Imaging Data Structure）的目录结构，便于共享和归档。
• 交互式诊断报告 (plot)：生成包含每个预处理步骤前后对比图、直方图和元数据的 HTML 报告，支持逐试次浏览，用于质量控制。
• 数据库存储：集成 DuckDB 后端，支持将大规模数据集（数百至数千名被试）存储为单一数据库文件（.eyerisdb），支持高效查询、聚合和分块导出（CSV/Parquet），解决了传统 CSV 文件管理在大规模研究中的扩展性瓶颈。

3. 主要贡献 (Key Contributions)

1. 首个标准化的瞳孔测量预处理流水线：eyeris 填补了该领域的空白，提供了一个类似于 fMRIPrep 的“一站式”解决方案，强制实施最佳实践步骤顺序，减少分析中的任意性。
2. “玻璃盒”设计：不同于黑盒工具，eyeris 允许用户理解并评估每一步处理对数据的影响。它提供交互式模式（逐步确认参数）和无头模式（批量处理），平衡了易用性与透明度。
3. 增强的质量控制 (QC)：通过自动生成包含数千个试次诊断图的交互式 HTML 报告，极大地降低了研究人员进行端到端数据审查的门槛，有助于在统计分析前剔除低质量数据。
4. 可扩展性与模块化：基于模块化设计，高级用户可以编写自定义预处理函数（如自定义去噪算法），并通过 pipeline_handler 无缝集成到主流程中，同时保持元数据追踪。
5. 大规模数据管理：引入 DuckDB 数据库后端，解决了大规模瞳孔测量研究中的数据组织、存储效率和 I/O 瓶颈问题，支持云部署和高效的数据共享。
6. FAIR 原则支持：通过标准化的文件结构、自动化的元数据记录和可重现的预处理历史，显著提升了数据的可查找性、可访问性、互操作性和可重用性。

4. 结果与功能展示 (Results & Features)

• 代码简洁性：用户仅需约三行代码即可将原始 EyeLink 数据转换为完全预处理、带有诊断报告的数据集。
• 元数据解析：成功演示了从复杂的事件消息字符串中自动提取试次编号、刺激类型等元数据，并将其与瞳孔数据整合。
• 可视化报告：生成的 HTML 报告不仅包含时间序列图，还记录了所有预处理参数和步骤历史，确保了分析的可追溯性。
• 数据库性能：展示了在大规模数据集上，使用 DuckDB 进行查询和聚合比处理数千个独立 CSV 文件更高效，且 Parquet 格式显著减少了文件大小（50-80%）并提高了读取速度。

5. 意义与影响 (Significance)

• 提升科学严谨性：通过标准化预处理流程，eyeris 有助于减少“分叉路径”问题，提高瞳孔测量研究的可重复性和统计推断的可靠性。
• 降低技术门槛：为不同编程水平的研究人员（从新手到专家）提供了易于使用的工具，使高质量的数据预处理不再依赖于复杂的自定义脚本。
• 推动开放科学：通过内置的 FAIR 原则支持和透明的数据管理，eyeris 促进了数据的共享和协作，有助于建立更稳健的瞳孔测量研究社区。
• 跨模态整合：其设计思路（如 BIDS 结构、数据库存储）使得瞳孔测量数据更容易与 fMRI、EEG 等其他神经影像数据进行多模态整合分析。

综上所述，eyeris 不仅是一个软件工具，更是推动瞳孔测量研究向标准化、透明化和可重复化方向发展的基础设施，有望成为该领域事实上的标准预处理框架。