Python心理学实验工具aepsych-client使用指南

1. 项目概述

aepsych-client是一个用于心理学实验设计和数据分析的Python包，它基于主动实验心理学（Active Experimental Psychology）框架开发。这个包特别适合需要高效设计实验、收集数据并进行复杂分析的研究场景。

我在最近的一个认知心理学研究项目中首次接触这个工具包，当时我们需要设计一个关于视觉感知阈值的实验。传统方法需要预先设计大量实验条件，而aepsych-client提供的自适应实验设计功能让我们能够动态调整实验参数，大大提高了研究效率。

2. 核心功能解析

2.1 自适应实验设计

aepsych-client的核心价值在于其自适应实验设计能力。它采用贝叶斯优化算法，能够根据被试者的实时反应动态调整实验参数。这种设计方式相比传统固定实验流程有几个显著优势：

1. 实验效率提升：只需要传统方法1/3到1/2的试次就能达到相同精度
2. 数据质量改善：自动聚焦于被试者的阈值附近区域
3. 灵活性增强：支持多种心理物理测量范式

2.2 主要组件架构

这个包主要由三个核心组件构成：

1. 实验设计器(Designer)：负责生成实验试次和参数
2. 模型管理器(Model)：实时更新心理测量函数
3. 客户端接口(Client)：处理与实验程序的通信

3. 安装与基础配置

3.1 安装步骤

安装aepsych-client非常简单，可以通过pip直接安装：

bash复制pip install aepsych-client

对于需要最新开发版本的情况，可以从GitHub仓库安装：

bash复制pip install git+https://github.com/facebookresearch/aepsych

3.2 基础配置参数

首次使用时需要进行一些基础配置：

python复制from aepsych.client import AEPsychClient

client = AEPsychClient(
    server_port=5555,  # 默认通信端口
    config_path="default.cfg",  # 配置文件路径
    database_name="experiment.db"  # 数据存储位置
)

注意：在Windows系统上可能需要额外安装pyzmq库，可以通过pip install pyzmq安装

4. 核心API详解

4.1 实验设置接口

创建实验时需要定义关键参数：

python复制config = {
    "experiment_type": "2AFC",  # 实验类型
    "stimulus_dim": 1,  # 刺激维度
    "outcome_type": "binary",  # 结果类型
    "min_stimulus": 0.0,  # 最小刺激值
    "max_stimulus": 1.0,  # 最大刺激值
    "target_threshold": 0.75  # 目标阈值
}

client.configure_experiment(config)

4.2 数据收集接口

运行实验时的主要方法：

python复制# 获取下一个试次的刺激参数
next_stimulus = client.ask()

# 提交被试者反应
client.tell(stimulus=next_stimulus, response=1)  # 1表示正确，0表示错误

4.3 结果分析接口

实验完成后可以获取分析结果：

python复制# 获取阈值估计
threshold = client.get_threshold()

# 获取完整心理测量函数
psychometric_function = client.get_mean()

# 获取置信区间
confidence_interval = client.get_confint()

5. 实际应用案例

5.1 视觉对比敏感度测量

下面是一个完整的视觉对比敏感度测量实验实现：

python复制from aepsych.client import AEPsychClient
import numpy as np

# 初始化客户端
client = AEPsychClient()

# 配置实验参数
config = {
    "experiment_type": "2AFC",
    "stimulus_dim": 1,
    "outcome_type": "binary",
    "min_stimulus": 0.001,  # 最小对比度
    "max_stimulus": 0.5,    # 最大对比度
    "target_threshold": 0.75,
    "n_trials": 100         # 试次数量
}

client.configure_experiment(config)

# 模拟实验流程
for _ in range(config["n_trials"]):
    contrast = client.ask()
    # 模拟被试者反应(这里用随机数据代替实际实验)
    response = 1 if contrast > np.random.uniform(0, 0.3) else 0
    client.tell(contrast, response)

# 分析结果
threshold = client.get_threshold()
print(f"估计的对比敏感度阈值为: {threshold:.4f}")

5.2 听觉频率辨别实验

另一个常见应用是听觉频率辨别实验：

python复制# 频率辨别实验配置
freq_config = {
    "experiment_type": "oddity",
    "stimulus_dim": 1,
    "outcome_type": "binary",
    "min_stimulus": 100,  # 最低频率(Hz)
    "max_stimulus": 8000, # 最高频率(Hz)
    "target_threshold": 0.75,
    "n_trials": 80,
    "stimulus_scale": "log"  # 使用对数尺度
}

client.configure_experiment(freq_config)

# 实验流程(同上)
# ...

# 获取JND(最小可觉差)
jnd = client.get_jnd()
print(f"频率辨别JND为: {jnd:.2f} Hz")

6. 高级功能与技巧

6.1 多维度实验设计

aepsych-client支持多维刺激空间的设计。例如，同时研究亮度和对比度的影响：

python复制multi_dim_config = {
    "experiment_type": "2AFC",
    "stimulus_dim": 2,
    "outcome_type": "binary",
    "stimulus_names": ["brightness", "contrast"],
    "min_stimulus": [0, 0.001],
    "max_stimulus": [100, 0.5],
    "target_threshold": 0.75
}

6.2 自定义模型参数

可以调整底层高斯过程的超参数：

python复制advanced_config = {
    # ...基础配置...
    "gp_mean": "constant",
    "gp_covar": "matern",
    "gp_lengthscale_prior": "gamma(2,0.5)",
    "gp_outputscale_prior": "gamma(2,0.5)"
}

6.3 实时可视化

虽然aepsych-client本身不提供可视化功能，但可以结合Matplotlib实现：

python复制import matplotlib.pyplot as plt

def plot_psychometric(client):
    x = np.linspace(client.min_stimulus, client.max_stimulus, 100)
    y = client.get_mean(x)
    plt.plot(x, y)
    plt.xlabel("Stimulus Intensity")
    plt.ylabel("Response Probability")
    plt.title("Estimated Psychometric Function")
    plt.show()

7. 常见问题与解决方案

7.1 通信连接问题

如果遇到连接错误，可以尝试以下步骤：

1. 检查服务器是否正常运行
2. 验证端口号是否正确
3. 确保防火墙设置允许通信

7.2 模型收敛问题

当模型无法很好拟合数据时：

1. 增加试次数量
2. 检查刺激范围是否合适
3. 考虑调整GP超参数先验

7.3 性能优化技巧

对于大规模实验：

1. 使用strategy="minimize"减少计算开销
2. 定期保存进度
3. 考虑使用更强大的硬件

8. 最佳实践建议

根据我的使用经验，以下建议可以提高实验效果：

1. 预测试阶段：先用少量试次(20-30)测试参数设置是否合理
2. 刺激范围：初始范围应覆盖可能阈值的宽范围
3. 试次数量：通常100-200试次可获得稳定估计
4. 被试者休息：长时间实验应安排适当休息间隔
5. 数据备份：定期保存原始数据和模型状态

一个更健壮的实施示例：

python复制from datetime import datetime
import json

def run_experiment(config, n_trials, save_path):
    client = AEPsychClient()
    client.configure_experiment(config)
    
    results = {
        "config": config,
        "trials": [],
        "start_time": str(datetime.now())
    }
    
    try:
        for trial in range(n_trials):
            stimulus = client.ask()
            # 这里连接实际的实验呈现和反应收集
            response = collect_response(stimulus)  
            client.tell(stimulus, response)
            
            # 记录每个试次数据
            results["trials"].append({
                "trial_num": trial+1,
                "stimulus": stimulus,
                "response": response,
                "time": str(datetime.now())
            })
            
            # 每20个试次保存一次进度
            if (trial+1) % 20 == 0:
                with open(save_path, "w") as f:
                    json.dump(results, f)
    
    except Exception as e:
        print(f"Experiment interrupted: {str(e)}")
    finally:
        # 最终保存
        with open(save_path, "w") as f:
            json.dump(results, f)
        
        return client, results

这个包在实际研究工作中展现了强大的灵活性，特别是在需要精确测量感知阈值的实验中。通过合理配置和正确使用，可以显著提高心理物理实验的效率和数据质量。