E06 · NIMH MonkeyLogic: Behavioral control and data acquisition in MATLAB
Hwang, J., Mitz, A.R., & Murray, E.A. (2019). Journal of Neuroscience Methods, 323, 13–21. doi:10.1016/j.jneumeth.2019.05.002
NIMH MonkeyLogic重写了行为控制、数据采集与图形模块，提出按视频帧组织的scene framework。指定硬件上的基准测试显示延迟和吞吐改善，但时间戳分辨率、采样间隔和闭环反应延迟仍是不同指标。
核对版本：Zotero VR 集合中的本地 PDF（2026-09-18）；Zotero 条目 · 打开原文。图下页码均为该 PDF 的文件页序，从 1 开始，可能不同于期刊印刷页码。
背景
行为控制软件需要协调刺激呈现、信号采集和事件记录。旧版MonkeyLogic面临兼容性与数据传输延迟问题，本文报告其重写及基准测试。
研究思路
研究以自定义采集和图形组件配合scene framework，在指定计算机、显示器和输入输出设备上与旧版比较。回环与光电测量分别检查信号时序，任务初始化及绘图测试评估吞吐；这些历史配置数据需在复现实验中重新验证。
方法
测试平台是一台普通办公机：Dell OptiPlex 7050，i5-7600 3.50 GHz，16 GB 内存，1 TB SSD，64-bit Windows 10，AMD Radeon R5 430 显卡；被试屏幕是 1024×768@75 Hz 的 17 寸 CRT，主试屏是 3840×2160@60 Hz 的 32 寸 LCD。对照实验在同一台机器上跑两个版本：ML1 用它还能运行的最后一版 MATLAB（R2014a 32-bit），需要 MATLAB DAQ Toolbox、Image Processing Toolbox 和两块 NI PCIe-6323；ML2（2018 年 6 月 build 139）不依赖额外的商业MATLAB工具箱，但仍需要MATLAB，只用一块 PCIe-6323，另测了 USB-6008 以比较 PCIe 与 USB 总线。行为信号来自 220 Hz 的 Arrington ViewPoint 眼动仪，event marker 以 16-bit 数字量经 NI 卡输出，屏幕角上贴光电二极管标定视觉 onset，任务自动以 Windows 的 high process priority 运行。性能测试任务是标准的注视随机点范式：1 s 注视后呈现 1 s 随机点运动（相干度 25% 或 40%，方向 0° 或 180°），随后左右两个选择靶出现，注视指示选择，答对触发外部奖励装置。延迟测量做得讲究：event marker 延迟用数字输出回环到同一块卡的模拟输入来测，刺激延迟则把 marker 输出和端设备（光电二极管、扬声器、模拟输出通道）的信号同时用 40 kHz 记到另一台电脑上比对。
主要结果
第一项核心能力是新的脚本模型。ML1 里刺激呈现（toggleobject()）和行为追踪（eyejoytrack()）是两个割裂的函数：追踪期间刺激不能改，eyejoytrack() 还得以毫秒为单位空转拉样本，没有时间做复杂计算或画复杂刺激。ML2 的 scene framework 把两者合并进一个 run_scene()：以视频帧为节拍，每帧开头统一分析上一帧攒下的行为样本（60 Hz 刷新、1 kHz 采集时约 16-17 个），在下一帧前完成重画与呈现，"分析-绘制-呈现"每帧循环。任务逻辑由 adapter（MATLAB 类对象）串成链，论文所述发行版内置40多个adapter，用户可从模板自造并公开分享。第二项是 NIMH DAQ Toolbox。MATLAB DAQ 在 logging 模式下约每 15 ms 才把缓冲区数据交给应用，等效的行为监视频率只有约 67 Hz，ML1 被迫双卡并用——一块持续记录、一块单点直读做实时监视；NIMH DAQ Toolbox 靠弹性缓冲结构和多线程，让 logging 模式下也能随时取到新样本，1 kHz 甚至更快，32 个模拟通道以内不丢 1 ms 的截止时间。USB 设备也翻了身：USB-6008 在 MATLAB DAQ 下最高 360-380 Hz，换 NIMH DAQ Toolbox 后能以 1.8-2.2 kHz 取到独立样本，用笔记本加 USB 卡组一套便携系统从此可行。不经过 DAQ 卡的设备（触摸屏、USB 摇杆、TCP/IP 眼动仪）用操作系统软件定时器轮询补齐，实测间隔 0.99±0.22 ms。
时间精度上，Windows QueryPerformanceCounter 在这台 3.5 GHz 机器上的分辨率是 0.29 μs，tic/toc 的误差通常在 20 μs 以内。event marker 从命令到信号翻转的延迟中位数，ML1 是 0.81 ms，ML2 缩到 0.18 ms；模拟刺激和视觉刺激相对 event marker 的延迟中位数分别为 −0.05 和 −0.03 ms——负号意味着刺激经常先于 marker 到达端设备，同步基本贴着命令执行瞬间。声音是遗留短板：板上声卡延迟 39.92 ms（USB 声卡 40.98 ms），绝对值不小，但已是 ML1（323.13/326.23 ms）的八分之一，且落在人类视听同步知觉的融合窗之内。整体吞吐同样可观：trial 进出（初始化加存盘）合计约 22 ms，比 ML1 的约 199 ms 快 9 倍；随机点电影从文件加载的 ITI 是 159.65 ms（ML1 为 1895.38 ms，差一个数量级），userloop 预载后只剩 66.26 ms，RandomDotMotion adapter 逐帧在线画也只要 92.47 ms 的准备时间。
逐图解读
来源：原文 Fig. 1，PDF 第 14 页。
图 1 · 旧脚本模型与 scene framework 的时序对比。 理解 ML2 设计动机的一张图。A 面板是 ML1 的串行世界：注视点由 toggleobject() 开关，眼动行为由 eyejoytrack() 每毫秒查一次；eyejoytrack() 检测到注视后立刻结束，但注视点可能要拖到下一帧结束才熄灭——刺激控制和行为追踪互相卡脖子。B 面板是 scene framework：run_scene() 把两件事并行塞进每个帧周期，上一帧采集的全部样本在下一帧开头统一分析，后台缓冲画好后按时呈现。代价是事件的发生可能要等下一帧才被"知道"，但正文强调事件发生的时刻仍可在线精确算出——用帧节拍换并行能力，同时不牺牲时间戳精度，这是该框架最关键的承诺。
来源：原文 Fig. 2，PDF 第 15 页。
图 2 · Scene framework 示范：Fixation Timer 任务。 一个可直接运行的教学例子，演示新框架到底解锁了什么。A 是猴子看到的画面：7 个环形计数器从右往左每秒点亮一格，但只在注视中央白方块时才走字，注视丢失后 4 s 内重新抓住还能续上——这种"刺激随行为实时变化"的东西在 ML1 的脚本结构里写起来非常别扭。B 是任务脚本：三个 adapter（EyeTracker、SingleTarget、TimerDemo）串成链，每个都可以通过属性单独调参，整条链由 create_scene() 和 run_scene() 执行。C 画的是运行循环：每个 adapter 有 analyze() 和 draw() 两个成员函数，从顶层 adapter 开始迭代调用整条链，直到顶层 analyze() 返回 false。读这张图的要点是模块化分工——底层 adapter 从 DAQ 取眼动样本，中层判注视，上层计秒，复杂任务就这样一层层搭出来。
来源：原文 Fig. 3，PDF 第 16 页。
图 3 · 采样性能对决：MATLAB DAQ vs NIMH DAQ Toolbox。 用于评估采集性能的图，输入是 20 Hz 正弦波、采样率 1 kHz。A 面板里 MATLAB DAQ 由于样本转移延迟，logging 模式下实际只能以约 67 Hz 检查新样本，20 Hz 信号被混叠出低频假象；B 面板 NIMH DAQ Toolbox 随要随取，正弦波完好；C 面板给出机理——NIMH DAQ 的可用样本数每毫秒加一，MATLAB DAQ 是每 15 ms 一次性加十五。D 面板把"查询当前输入状态"的开销画成通道数的函数，说明多通道下依然负担得起。这张图论证的正是 ML2 敢于砍掉第二块 DAQ 卡的底气：单卡 logging 模式就能同时喂饱数据记录和实时行为监视。
来源：原文 Fig. 4，PDF 第 17 页。
图 4 · Windows 软件定时器的采样间隔分布。 ML2 有相当一部分输入设备根本不经过 DAQ 卡——触摸屏、USB 摇杆、TCP/IP 眼动仪——只能靠操作系统的软件定时器按 1 ms 间隔轮询。这张直方图（100 次采集、0.1 ms 分箱）用于评估这一实现：间隔分布紧紧围绕 1 ms（0.99±0.22 ms），尾部虽受系统负载影响偶尔拖长，但是否满足具体闭环任务，还需验证完整设备链路和负载下的延迟。它和图 3 是一对：图3检验DAQ采集与应用读取性能，图 4 管卡外设备的软实时，两张图分别展示硬件采集和软件轮询的测试，不能替代每类设备的端到端验证。
来源：原文 Fig. 5，PDF 第 18 页。
图 5 · ML2 的双屏监控界面。 A 是猴子看到的屏幕，B 是主试屏幕。MGL 把刺激按比例复制到两块屏上并行渲染，但只把注视窗、眼动轨迹、按键状态、用户文本这些监控信息叠加在主试屏；两屏渲染在现代显卡上只花几毫秒，且只有被试屏的呈现与刷新率严格同步，文中测试显示双屏渲染可在所用配置下完成，实际任务仍需检查漏帧。图上还能看到透明色的用法——多个带透明背景的对象可以叠在同一位置而不互相遮挡，配合任意形状多边形和从 AVI/MPG 文件或 MATLAB 矩阵直接生成的流式电影，构成 ML2 在刺激种类上的扩展。这张图本身谈不上"科学"，但做过实验的人都懂，一块信息量大的主试屏在日常操作里值多少钱。
讨论与解读边界
本文展示软件架构如何支持刺激随行为更新，并用回环、光电二极管和外部采集验证部分时序。scene按帧分析样本，能够保留事件发生时刻的信息，但动作触发仍可能等待下一帧；精确记录不等于即时响应。
测试对应2018年的软件版本、Windows与指定设备，不能直接作为当前安装的性能保证。无需额外商业工具箱不等于无需MATLAB。视觉和模拟信号的负延迟是相对事件标记定义的先后顺序，不是负的物理传输时间。软件轮询约1 ms也不能提高眼动仪自身的220 Hz采样率，或证明整个系统具备硬实时保证。声音延迟对实验是否可接受，需按范式实测。
思考问题
- 从眼动或手部事件发生到屏幕实际变化，端到端延迟分布及最坏情况是多少？
- 在同时记录多通道、绘制复杂VR场景和写盘时，漏帧与事件标记误差会怎样改变？