Unity plugin: logging data
A primary feature of the VERA Unity plugin is the ability to log data during XR experiments. This logged data is periodically synced to the VERA web interface, associated with a particular participant session, where it can be viewed and analyzed.
Before beginning this section, it may be useful to review the Unity plugin: overview section, which provides an overview of the VERA Unity plugin and its features.
Key takeaways
For each CSV file type defined on the VERA portal, a corresponding C# class is automatically generated in the VERA Unity plugin.
This class is named VERAFile_[FileTypeName].
This class contains a CreateCsvEntry() method, which can be used to log data to that file type during the experiment.
There is a single preprocessor directive for each file type, which can be used to conditionally compile code related to that file type.
All data logged will automatically record locally and sync to the web portal.
// EXAMPLE USAGE OF DATA LOGGING WITH VERA
// This code conditionally compiles only if the "ParticipantPositions" file type is being used in the experiment
#if VERAFile_ParticipantPositions
// Create a new CSV entry for the "ParticipantPositions" file type
// This function is strictly typed according to the columns defined for this file type on the web interface
// I.e., the parameters you provide here must match the columns you defined for this file type on the web interface, in both type and order
VERAFile_ParticipantPositions.CreateCsvEntry(1.23f, 4.56f, 7.89f);
#endif
Understanding VERA files and logs
For research purposes, data is often recorded to a variety of different file formats. VERA uses a common format known as CSV (comma-separated values) to store tabular data. CSV files are simple text files where each line represents a single record, and each record is made up of multiple fields separated by commas. CSV files are common in research contexts, as they can be easily opened and analyzed using a variety of tools, such as spreadsheet software (e.g., Microsoft Excel, Google Sheets) or programming languages (e.g., Python, R).
Here’s an example of what a simple CSV file might look like:
Timestamp |
Event Type |
Position X |
Position Y |
|---|---|---|---|
0.125 |
Button Press |
1.23 |
4.56 |
0.250 |
Object Pickup |
2.34 |
5.67 |
0.375 |
Button Release |
1.45 |
4.78 |
On the VERA web interface, you can define multiple File Types for each experiment. Each of these file types represents a single file you will be logging data to during the experiment. These file types are not strictly limited to CSV files - you can define other file formats as well, such as TXT or PNG. However, VERA provides special out-of-the-box tools for logging to CSV file types, which are the focus of this section.
For each file type, you can define the format (txt, png, csv, etc.). If you choose to create a CSV file type, you can then define the columns that will be present in that CSV file. Each of these columns often represents a single piece of data you wish to log during the experiment. For example, if you wanted to log the position of the player every frame, you might define columns for the X, Y, and Z position of the player. Every row then represents a single Log to that file - a single record of data containing values for each of the defined columns. For example, a log might represent the player’s position at a specific timestamp during the experiment.
You can have multiple file types for a single experiment, allowing you to log different types of data to different files. For example, you might have one file type for logging controller interactions, another for logging object interactions, and another for logging participant actions. The file types you define will depend on the specific needs of your experiment.
In summary, a File Type in VERA represents a single file you will be logging data to during an experiment. A Column is a single field in that file, representing a specific piece of data you are logging. A Log is a single entry (row) in that file, representing a single record of data.
VERAFiles in Unity
Any File Types you define for your experiment on the VERA web interface will be accessible in the VERA Unity plugin. For more information on defining file types for your experiment, see the Web interface: overview section.
When you select an active experiment in the VERA Unity plugin, C# code is automatically generated for each of the experiment’s CSV file types. This code is stored in the Assets > VERA > FileTypes > GeneratedCode folder in your Unity project.
There will always be a single C# class generated for each CSV file type defined in your experiment. These classes can be used to log data to the corresponding CSV file during the experiment.
Each of these generated files is named according to its corresponding file type. The class is prefixed by “VERAFile_”, followed by the name of the particular file type as defined on the VERA portal. For example, if you have a CSV file type named “MyFile”, the generated class will be named “VERAFile_MyFile”.
Preprocessor directives
Preprocessor directives are used to conditionally compile code based on certain conditions. This can be useful for ensuring that code related to a specific feature, version, or configuration is only compiled when that feature, version, or configuration is being used.
In the VERA Unity plugin, every generated C# class for a CSV file type comes with a single preprocessor directive. In this way, you can ensure that code related to a specific file type is only compiled when you are using that file type in your experiment. This can be useful if you plan to swap experiments often, to prevent compiler errors related to missing file types.
These preprocessor directives are named according to their corresponding file type. For example, if you have a VERAFile named “VERAFile_MyFile”, the generated directive will be named “VERAFile_MyFile”.
// Example usage of a preprocessor directive for a VERA file type
#if VERAFile_MyFile
// Code related to the "MyFile" file type goes here
// This code will only be compiled if the "MyFile" file type is being used
#endif
Logging data with VERA files
To log data to a particular CSV file type in your Unity experiment, you can use the generated C# class for that file type. Each generated class contains a static method named CreateCsvEntry(), which can be used to make a single new log entry to that CSV file.
This function requires you to provide values for every column you have defined for that file in the web interface. The function parameters will be strictly typed according to these columns, ensuring you provide the correct data types for each column.
VERA handles several default columns automatically for every CSV file type. You do not need to provide values for these columns when calling the CreateCsvEntry() method. These default columns are as follows:
pID: The unique short identifer for the participant session (“1”, “2”, “3”, etc.).
conditions: The current experimental conditions the participant is under (see the Unity plugin: managing conditions section for more details).
ts: The timestamp of when the data was logged, recorded in seconds since application start.
For example, say you had a CSV file type named “ParticipantPositions”, and you have defined 3 float columns for logging the X, Y, and Z position of the participant. You could log a new entry to this file type using the following code:
// First, ensure the preprocessor directive for this file type is defined
// This will ensure the code only compiles if the file type is being used
#if VERAFile_ParticipantPositions
// Log a new entry to the "ParticipantPositions" CSV file
// The three columns represent the X, Y, and Z position of the participant
VERAFile_ParticipantPositions.CreateCsvEntry(1.23f, 4.56f, 7.89f);
#endif
This example would log a single new entry to the “ParticipantPositions” CSV file. VERA would automatically handle the first three columns (participant ID, conditions, and timestamp). Then, the last three columns would be the X, Y, and Z position values we provided (1.23, 4.56, and 7.89 respectively).
Submitting and viewing logs
Any logs you create using your VERAFiles in Unity are automatically uploaded to the VERA web interface periodically every 3 seconds during your experiment. They are additionally saved to a local file as a backup in case of network issues. These local files will be synced to the web interface automatically once the network connection is restored.
You do not need to make any additional calls to submit or upload your logs - VERA handles this automatically for you.
You can view any uploaded logs by navigating to the VERA web interface, selecting your experiment, and then selecting the desired participant session. From there, you should see a single tab for each file type defined in your experiment, which can be selected to view the logged data. The data can then be downloaded as a CSV file for further analysis.
Next steps
Next, consider exploring the Unity plugin: managing conditions section, which explains how to set up and manage experimental conditions in your Unity experiments using the VERA plugin. Additionally, consider exploring the Unity plugin: managing sessions section, which explains how to manage participant sessions in your Unity experiments using the VERA plugin.
For a quick reference guide to using the VERA Unity plugin, which includes a list of the functions outlined above, see the Unity plugin: quick reference section.