Data collection

UXF handles data collection for you. It can collect data at several levels:

• Behavioural data, i.e. a single observation of several dependent variables on each trial.
• Time-series data, i.e. the value of one or more parameters over time within each trial (such as the x, y position of a user's hand or cursor). This is performed with the Tracker system system.
• Event logging, i.e. recording a message at a given time. This is performed by the Logging system.
• DIY data output: If you want to, you can easily use UXF to store data on a per-trial or per-session basis.

Data Handlers

As of UXF 2.0, data output is performed in a "modular" fashion. This means, data are handled by one or more "Data Handlers". You can select which data handlers are appropriate for your project, or even create your own for some specific means of data output.

UXF currently comes with three Data Handlers:

• File Saver: This data handler saves data to files locally on your device, as a mix of CSV, JSON, or TXT files, depending on the data. This is compatible only with PC & Android (including Oculus Quest) based studies. The files are automatically named for you and optionally sorted into folders. CSVs are formatted according to locale (i.e. ;-delimited and , for decimal places in non English locales).
• Download/Copy Data Handler: This data handler displays a user interface element at the end of the session, which allows users to download their data, or copy the data text directly. This is useful for classroom data collection, and is compatible with web-based studies. Students have access to their own data and so provides a low-tech means of them analysing their own data.
• Web AWS DynamoDB Data Handler: This Data Handler will upload the session's data to an AWS DynamoDB database, if configured correctly. This is only compatible with Web-based studies, but allows for fully remote data collection.
• HTTP POST Data Hander: This data handler sends POST requests to a URL, with a filepath and data (formatted as a string). The web server needs to accept this POST request and write the data to a file. See the here for more details.
• Custom Data Handler: You could make your own Data Handler which uploads data to a different cloud service, streams over LabStreamingLayer, or anything! You need to extend the Data Handler class, see one of the other Data Handler scripts as a base. Then just attach it as a sibling to the other data handlers, and reference it in your UXF Session inspector.

See the Compatibility article to see which Data Handlers can be used on different platforms.

To select or configure the data handlers, go to the Data Handling tab in the UXF Session component.

You can create your own data handler if you need an alternative way of storing data.

Typical session output

If we are using the File Saver Data Handler with the built-in UI, we will use that to select a data storage location. If we are not using the UI, we can assign a constant save location in the File Saver component. Running a session with UXF will result in output structure that contains a main results file as well as other files sorted into folders, stored inside the selected data save directory.

Path: .../experiment_name/participant_id/session_number/

Data files are sorted into folders by default. As of version 2.3.2, these are the files and folder stored for a typical session.

File(s)	Folder	Description
trial_results.csv	(none)	The main behavioural results file, with one row per trial. It also contains references (relative paths) to other trial-level data files such as tracker files, so you can read in the data and associate it with a trial.
participant_details.csv	/session_info	A copy of the participant's details (typically the data that are collected along with participant ID using the UI). Stored as a single row.
log.csv	/session_info	A copy of all Debug.Log calls during the session, as well as any other custom data saved under datatype SessionLog.
settings.json	/session_info	A copy of all settings applied as the session begins.
Trackers e.g head_movement_T001.csv	/trackers	A copy of tracker data, stored with one file per trial. Tracker data is continuous data, the most common will be tracking the movement of an object (e.g. head/hands) with the PositionRotationTracker component.
Other data	/other	Any other custom data stored manually, associated with a trial or a session.

Behavioural data

For each Session, a single .csv file will be created within the session folder, called trial_results.csv. The trial results are formatted with any columns the researcher desires, always with one row per trial (aka "long" format).

The column headers are a combination of base headers, custom headers, settings to log, & tracking headers:

Base headers

These include a set of standard, non-customisable variables:

• directory: The relative location of the Session directory.
• experiment: The name of the experiment, with the default setup this is the same as the name of the settings json file selected via the UI.
• ppid: A unique Participant ID, with the default setup this is entered from the UI.
• session_num: A number indicating the session, with the default setup this is selected using the UI.
• trial_num: The number for the trial, starting at 1.
• block_num: The number for the block, starting at 1.
• trial_num_in_block: The number of the trial within the block, starting at 1.
• start_time: The timestamp of the start of the trial (using Unity's Time.time function).
• end_time: The timestamp of the end of the trial (using Unity's Time.time function).

experiment, ppid and session_num will be the same value repeated for each row - this makes things much easier when, during data analysis, we potentially concatenate all the data together into a large dataframe.

Settings to log

The Settings system allows researchers to pre-define parameters at the Session, Block or Trial level. These can be thought of as our independent variables. The settings to log is a list of settings that you wish to be recorded on each trial and added to the trial results output, specified using the Session component's inspector.

Results (dependent variables)

We can also record any variable from the task, for example a user's response to a stimulus. These can be thought of as the dependent variables, or our "results". Then, we can assign the value to the results dictionary on any given trial. For example:

public class Example : MonoBehaviour
{
    // Reference to our Session component
    public Session session;

    // An example method to be called when a user gives a response
    public void UserResponse(int selection)
    {
        // in this example, a user has selected a number, and we want to record it.
        session.CurrentTrial.result["selected_number"] = selection;

        // in our trial_results output, the selected_number column will now be filled in with the selection for each trial.

        // we can assign results either before or after we end the trial.
        session.CurrentTrial.End();
    }

}

Trackers

The tracker system handles collecting data in real-time on each trial. It can be used to measure, for example, the position of a user-controlled gameobject over time. The measurement is performed on each frame (by default in Unity's LateUpdate() loop). With the File Saver data handler, tracker data are logged to a .csv on each trial. The file name of this .csv is then stored as a column in the behavioural data file trial_results.csv, making association from tracking data with behavioural data much easier.

More info on the headers in the Session documentation.