Specify trials with CSV file

In UXF version 2.3.0, you can specify trials using a CSV file stored in StreamingAssets, rather than generating the trials programmatically.

To do this, instead of writing a script to generate your experiment trials, you can add a provided component called CSV Experiment Builder to a GameObject:

Then you can assign the BuildExperiment method to the On Session Begin event on your [UXF_Rig]:

Then, your Session settings must contain the name of a CSV file with the key provided in the Csv File Key field (default: trial_specification_name). The easiest way to do this is to add an entry to your Experiment Settings Profile .json file.

{
    "trial_specification_name": "my_csv_file.csv",
    "example": "hello!"
}

If you select this profile, it will look for a file named my_csv_file.csv in your StreamingAssets folder, and then use it to build your trials.

Each row will become a new trial. The columns you specify will go into settings. For example, a CSV file like this:

size	delay	message
12	1.50	"Reach for the target!"
15	1.75	"Stay still!"
7	1.25	"Reach for the target!"
19	1.50	"Stay still!"

Will create 4 trials with settings size, delay, and message on each trial. You can then of course use these settings in your application (see settings system):

Blocks

You can specify which block the trial should belong to with a special column named block_num. For example, this would create 2 blocks with 2 trials each:

block_num	size	delay	message
1	12	1.50	"Reach for the target!"
1	15	1.75	"Stay still!"
2	7	1.25	"Reach for the target!"
2	19	1.50	"Stay still!"

CSVs without the UI system

It is possible to specify the location of the CSV programmatically, without specifying it in the Experiment Settings Profile selected in the UI. You can write a method to assign the required setting. Assign this to the On Session Begin, but make sure it is before (i.e. placed above) the CSV Experiment Builder. This may be done automatically in the future.

using UXF;

...

public void SpecifyCSVName(Session session) // assign further up in On Session Begin
{
    // assign the name of the CSV file that is stored in StreamingAssets
    session.settings.SetValue("trial_specification_name", "my_csv_file.csv");
}

Blank entries

If an entry is left blank in a CSV file, it will be ignored, and no setting will be set. For example:

size	delay	message
12	1.50	"Reach for the target!"
15		"Stay still!"
7	1.25	"Reach for the target!"
19	1.50	"Stay still!"

This would mean on trial 2 no delay is set, and so the cascading system would look for any setting that has been applied in the session or the block. You could assign a "default" value in your Experiment Settings Profile .json, then use the CSV to specify deviations from default.

Or, you could use the valueIfNotFound argument in settings.Get*():

trial.settings.GetFloat("delay", valueIfNotFound: 1f);

Shuffling / reordering

You can still shuffle you trials blocks if you want, you would just need to write another script that gets called after the CSV Experiment Builder script (i.e. is assigned lower in the On Session Begin event). For example, to shuffle block 2:

using UXF;

...

public void ShuffleBlock2(Session session) // assign lower down in On Session Begin
{
    var block2 = session.GetBlock(2);
    block2.trials.Shuffle();
}

You can also apply any function to re-order the trials/blocks however you like.

Selecting different CSVs

Perhaps you have multiple conditions in your experiment, and require different CSVs to be selected for each condition. To do this, you can point to a different file in StreamingAssets in multiple Experiment Settings Profile .json files. For example, imagine 2 conditions:

my_experiment_condition_1.json

{
    "example": "hello!",
    "trial_specification_name": "condition_1_trials.csv"
}

my_experiment_condition_2.json

{
    "example": "hello!",
    "trial_specification_name": "condition_2_trials.csv"
}

The experimenter can then either select my_experiment_condition_1 or my_experiment_condition_2 in the UI as they need to.