Data collection

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

• Participant list (feature of the UI).
• 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 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 write any type of data as a .json or .csv file at any time.

Typical session output

Running a session with UXF will result in an output like this (assuming three trials with a tracked object called object)

Path: /experiment_name/participant_id/session_number/

Filename                   Description
------------------------ | ----------------------------------------------------------
log.csv                  | Copy of all Debug.Log calls during the Session
notes.csv                | Notes collected by the Notes UI
participant_details.json | Copy of participant details (e.g. info entered via the UI)
object_movement_T001.csv | Position and rotation of "object" within trial 1
object_movement_T002.csv | Position and rotation of "object" within trial 2
object_movement_T003.csv | Position and rotation of "object" within trial 3
settings.json            | Copy of the settings applied to the Session
trial_results.csv        | Main results file (behavioural data)

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:

• 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.

Custom headers

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". We do this by first adding the name of the parameter we wish to measure in the Session component's inspector. 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.
        // this assumes "selected_number" has been added to our session's "Custom Headers" list.
        session.currentTrial.results["selected_number"] = selection;

        // in our trial_results.csv 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();
    }

}

Tracking headers

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 an logged to a .csv per trial. The relative path 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.

DIY data collection

See WriteDictToSessionFolder in Session methods.