在Builder中自动化PsychoPy实验

介绍

当使用PsychoPy的GUI Builder构建参与者间实验时，可能会出现以下两个问题

1. 需要根据参与者所属的组调整刺激物以适应不同的条件。
2. 自动将参与者分配到实验条件，以确保各组参与者数量均衡。

这些问题可以通过向Builder中可用的代码块添加大量的Python代码来解决。autopsypy的目标是简化这项任务，只需添加极少的Python代码到实验中。

安装

autopsypy模块可在PyPI上找到。它可以在Linux系统上轻松安装，命令如下，在用于PsychoPy的同一天虚拟环境中执行

python -m pip install autopsypy

在Windows系统上，您可能尝试从PsychoPy安装它，在菜单项工具⇒插件/包管理器中。如果不起作用，请从PyPI下载最新版本的wheel文件，解压缩它，并将目录autopsypy-<version>.dist-info和文件autopsypy.py复制到您的PsychoPy安装的site-packages目录中（可能是C:\Program Files\PsychoPy3\lib\site-packages）

该模块已在PsychoPy版本2023.1.2、2024.1.4和2024.2.1上进行了测试。它可能与其他版本一起工作。

如果您使用的是独立版本的PsychoPy autopsypy.py，可能是因为通过pip安装的模块没有找到。在这种情况下，将autopsypy.py所在的路径添加到首选项的通用部分。有关详细信息，请参阅PsychoPy的文档。

工作原理

示例

让我们通过一个非常简单的示例来说明模块是如何工作的。假设我们想要研究参与者对两张图片（例如，向日葵和松树）的偏好。我们将在3秒钟内同时将两张图片显示在屏幕上，并使用例如眼动测量来确定每张图片的注视时间。为了避免左右偏好，我们将参与者分为两组。对于第一组，向日葵在左侧，松树在右侧；对于第二组则相反，如下所示

在PsychoPy的Builder中，可以这样设置一个最简实验，其中包含两个Image组件和一个Code组件

指定条件

必须放置在实验非常开始的单独流程中的Code组件，在其“Begin Experiment”部分必须包含以下代码

from autopsypy import AutoPsyPy
x = AutoPsyPy()

还必须在“End Experiment”部分包含以下代码

x.finish()

这将创建一个名为x的类为AutoPsyPy的变量。可以给变量取任何名字，这里的x只是一个示例。然后autopsypy模块将打开当前目录中必须存在的逗号分隔值（CSV）文件conditions.csv。可以通过AutoPsyPy()的conditions参数使用任何其他文件名。CSV文件的字段分隔符可以通过csv_delimiter参数指定，默认为分号";"。还有一个可选参数desired_group_size，通过这个参数，实验者声明每个组中期望的参与者数量。这个参数的默认值是无限大（∞），它只有信息价值（即不影响autopsyy的行为），并在实验结束时显示。这有助于实验检查他们离研究结束还有多远。

条件文件必须在第一行包含列名（稍后使用，见下文），接下来的每一行将代表一个实验条件。在我们的示例中，条件文件将如下所示

left;right
daisy.jpg;pine.png
pine.png;daisy.jpg

列名将在Image块设置中使用，更确切地说是在Image流程属性的“Image”字段中。在当前示例中，必须在标记为“left”的组件中设置为$x["left"]，在标记为“right”的组件中设置为$x["right"]。

指定组

组通过在属性窗口的“Experiment info”部分（通过单击PsychoPy Builder中的齿轮图标访问）中引入变量来定义。autopsypy模块要求存在一个名为“participant”的字段（精确的名称）。如果该字段不存在，实验将停止。带有“condition”或“keep”名称的字段是禁止的（在这种情况下，实验将停止并显示错误消息）。创建的任何其他字段都将用于定义组。

假设在“Experiment info”部分创建了一个名为“age”的字段，并且参与者将要么在“young”组中，要么在“old”组中，这些信息将在会话开始时由实验者提供。

在实验首次运行时，会创建一个CSV文件sessions.csv（或通过AutoPsyPy()的sessions参数指定的任意名称）。此文件始终包含名为participant、datetime、condition和keep的列。在我们的示例中，将添加一个名为age的第四列。如果会话文件已存在，则由autopsypy模块读取，不会重新创建。该文件记录了每个参与者选择的条件。可以在连续两个会话之间随意编辑，例如移除掉队的参与者。

condition列包含整数，表示条件文件中选中的行。在我们的例子中，值将是1或2（分别代表左侧或右侧的雏菊）。假设已经有三位参与者已经运行了实验，其中两位“年轻”和一位“年长”。会话文件将如下所示

participant;datetime;age;condition;keep
1;2023-09-05_10h53.01.058;young;1;yes
2;2023-09-06_12h33.38.161;old;1;yes
3;2023-09-06_16h56.26.312;young;2,yes

如果第四位参与者是“年轻”，则将运行条件1。否则，如果第四位参与者是“年长”，则将运行条件2。

可以在实验信息部分添加额外字段，这有助于参与者的分层。例如，如果创建了一个新的字段“gender”，其可能值为“male”（男性）和“female”（女性），那么autopsypy将考虑存在四个组（“young female”（年轻女性）、“old female”（年长女性）、“young male”（年轻男性）和“old male”（年长男性）），并将平衡每个组中条件1和2的数量。

会话结束时，将向用户展示所选条件。同时也会展示每个实验组的大小信息，以及期望的组大小（在实例化AutoPsyPy变量时使用的desired_group_size参数，见上文）。

在任何研究阶段，实验者都可以决定排除某些参与者（例如，会话中出现问题）。有两种排除参与者的方式

1. 从文件sessions.csv（或任意名称i）中删除相应的行
2. 将keep列中相应的yes值更改为其他任何值（例如，no）。

演示

在demo/目录中提供了一个与上述示例相关的演示。请随意尝试，以更好地理解autopsypy的用法。在Linux和MacOS系统上，可以从该目录使用以下命令运行演示

$ psychopy daisy-pine.psyexp

致谢

感谢Jonathan Parente在设计和测试autopsypy模块中的帮助，以及Cristina-Ioana Galusca提出的改进建议。

作者

版权所有 © 2023 Rafael Laboissière (rafael@laboissiere.net)

autopsypy是在GNU通用公共许可证版本3或更高版本下分发的。