UXF - Unity实验框架

一套简化在Unity引擎中开发人类行为实验的组件。UXF 2.0支持VR、桌面以及基于网络的完全远程数据收集实验，并具有不同的数据输出模式。这是开发项目，如果您想下载该软件包，请不要克隆此存储库，请参阅下面的"开始使用"。

阅读行为研究方法中的开放获取论文！该论文现在略有过时，但很好地概述了这个项目的动机。由利兹大学沉浸式认知小组的Jack Brookes开发。

如果您使用UXF开发了项目，请告诉我！

使用UXF构建的项目
开始使用
功能
示例
开发
文档
新闻报道
教程：使用UXF构建实验

使用UXF构建的项目

点击上方横幅查看我们使用UXF构建的一些实验。

开始使用

阅读此README和论文以了解UXF。
将最新的UXF.unitypackage发布版本导入到您现有的Unity项目中。（将文件拖入您的项目中。）
UXF设置向导将启动（或通过顶部菜单：UXF > UXF Wizard）- 使用它来解决任何兼容性问题。
打开一个示例场景。（例如 UXF -> Examples -> 2_MoveToTarget -> MoveToTargetExample）
按下播放键，并使用用户界面输入任何详细信息。
按开始按钮开始会话。

访问Wiki以获取更多详细信息。

功能

编程风格

为常见实验概念提供类，如Session、Block和Trial
有助于创建可维护和可读的代码，符合Unity的组件系统

数据收集

UXF自动化了数据收集的过程。数据的存储方式取决于平台（PC、Web等）以及您对不同"数据处理程序"的配置。对于PC平台，您可能只想将数据存储在本地PC的文件中。在这种情况下，文件保存程序数据处理程序将以多种形式输出数据：

行为数据以每个Trial一行的形式收集，并自动记录一些值，如试验开始和结束的时间戳。开发人员可以轻松记录任何类型的观察结果，并将其与试验关联。数据以每个试验一行的形式输出到结果csv文件中。

连续数据是在试验过程中持续测量的数据。主要用例是跟踪场景中任何对象的位置和旋转，这是通过向GameObject添加PositionRotationTracker组件来捕获的，捕获频率与应用程序运行的帧率相同（在Update()循环中）。这可用于跟踪用户控制对象的位置（如虚拟现实应用中的手或头部）或场景中的任意对象（例如某种刺激）。然而，这个系统是通用的，开发人员可以创建自己的Tracker类，在试验期间测量任何变量。

数据存储在CSV文件中，自动处理文件和目录命名。

UXF还以.csv和.json文件的形式存储其他数据（详细信息请参见Wiki）。使用UXF运行会话将导致存储多种形式的数据：

文件	文件夹	描述
`trial_results.csv`	(无)	主要行为结果文件，每个试验一行。它还包含对其他试验级数据文件（如跟踪器文件）的引用（相对路径），因此您可以读取数据并将其与试验关联。
`participant_details.csv`	/session_info	参与者详细信息的副本（通常是使用UI与参与者ID一起收集的数据）。存储为单行。
`log.csv`	/session_info	会话期间所有`Debug.Log`调用的副本，以及在SessionLog数据类型下保存的任何其他自定义数据。
`settings.json`	/session_info	会话开始时应用的所有设置的副本。
跟踪器，例如`head_movement_T001.csv`	/trackers	跟踪器数据的副本，每个试验存储一个文件。跟踪器数据是连续数据，最常见的是使用`PositionRotationTracker`组件跟踪对象（例如头部/手部）的移动。
其他数据	/other	任何其他手动存储的自定义数据，与试验或会话相关联。

示例输出 您可以在此存储库的example_output文件夹中查看UXF输出的数据结构示例。

网络和数据库

对于Web平台，数据无法存储在参与者的PC上。相反，数据可以上传到数据库。只要您使用Amazon Web Services设置DynamoDB数据库，UXF就会为您处理所有繁重的工作，并自动上传数据文件。

事件

在Trial开始和结束时会调用UnityEvent，允许您轻松触发试验开始时呈现刺激（例如）。

设置系统

设置是级联的，允许在Session、Block或Trial级别设置独立变量。设置配置文件可以存储为.json文件，并通过UI选择。这允许实验者部署单个实验版本，其中包含在设置配置文件中定义的多个子实验。这些子实验的数据独立存储。

用户界面

可选地提供可定制的用户界面，用于收集人口统计数据并向用户或实验者呈现说明。可以自定义收集的变量，并可在实验中使用（例如，可以使用参与者年龄参数来改变实验难度）。

示例

UXF 的构建理念是将实验的规范（"做什么"）和实验的实现（"如何做"）分开。

实验规范：构建/描述实验结构，包括试次、区块及其相关设置。
实验实现：根据自变量呈现刺激，收集因变量。

1. 实验规范

public class ExperimentBuilder : MonoBehaviour
{
    // 在检查器中将此项设置为引用您的 UXF 会话
    public UXF.Session session;
    
    // 在检查器中将此方法分配给 Session OnSessionBegin UnityEvent
    public void GenerateAndRun() 
    {       
        // 创建一个包含 10 个试次的区块
        var myBlock = session.CreateBlock(10);

        // 向第一个试次添加新设置，这里仅作示例，我们将"color"设置为"red"
        myBlock.FirstTrial.settings.SetValue("color", "red");

        ...

        // 开始会话！
        session.FirstTrial.Begin();
    }

    ...

}

2. 实验实现

public class SceneManipulator : MonoBehaviour
{

    // 在检查器中将此项设置为引用您的 UXF 会话
    public UXF.Session session;

    ...

    // 在检查器中将此方法分配给 Session OnTrialBegin UnityEvent
    public void ShowStimulus(UXF.Trial trial)
    {
        // 提取我们为此试次应用的颜色
        // 在第一个试次中输出将为"red"
        string colorManipulation = trial.settings.GetString("color");

        // 使用新设置通过自定义方法操作场景的示例
        ManipulateSceneColor(colorManipulation);
    }

    // 这可能会在某些用户行为（如按钮响应）时触发，收集他们在任务中的得分
    public void RecordResultsAndEnd(int score)
    {
        // 存储他们的得分
        session.CurrentTrial.result["score"] = score;
        // 结束此试次
        session.CurrentTrial.End();
    }

}

包中和 Wiki 上包含更多示例，包括一个完整的书面教程。