Factorial design

We might want to generate trials where we have a trial for each combination of several factors. For example, say we have two factors, distance (with levels 1 and 2) and reward (with levels 100, 200 and 300). We want to generate (for example) 5 trials for each combination of these two factors.

	distance = 1	distance = 2
reward = 100	5x trials	5x trials
reward = 200	5x trials	5x trials
reward = 300	5x trials	5x trials

We can do this in UXF using nested for loops. First, we must define the levels of each factor. We can do this by creating arrays in our experiment settings profile .json file, and accessing them at runtime. In this example however, we will define them as constants in our C# Script. We will then use the built-in UXF Shuffle method to shuffle the order of the trials within the block (requires adding using UXF; at the top of your script).

using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using System.IO;

// add the UXF namespace
using UXF;

public class SessionGenerator : MonoBehaviour
{     
    // assign this as the first element in the "On Session Begin" event in the Session component inspector
    public void GenerateExperiment(Session session)
    {
        // define the two factors as C# arrays
        int[] distances = new int[]{ 1, 2 }; // <-- or access from (e.g.) session.settings.GetIntList(...)
        int[] rewards = new int[]{ 100, 200, 300 }; // <-- or access from (e.g.) session.settings.GetIntList(...)
        
        // create empty block - we will add trials one by one
        Block block1 = session.CreateBlock();

        // generate trials for each combination
        int numRepeats = 5; // <-- or access from (e.g.) session.settings.GetInt(...)
        foreach (int distance in distances) // each distance level
        {
            foreach (int reward in rewards) // each reward level
            {
                for (int i = 0; i < numRepeats; i++) // 5 times
                {
                    Trial newTrial = block1.CreateTrial();
                    // apply the settings to the new trial
                    // the setting names inside quotes can be anything we want
                    newTrial.settings.SetValue("stimulus_distance", distance);
                    newTrial.settings.SetValue("stimulus_reward", reward);
                }
            }
        }

        // put the trials in a random order
        block1.trials.Shuffle();
        
    }
}

Later in our code, we can then use these values to set up our scene at the start of a trial (for example). The script below could create an object and set its "distance" and "reward" to the values for that trial.

using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

// UI needed for Text component
using UnityEngine.UI; 

// add the UXF namespace
using UXF;

public class ObjectSpawner : MonoBehaviour
{     

    public GameObject objectPrefab; // some kind of stimulus that has a Text component attached

    // assign this as the first element in the "On Trial Begin" event in the Session component inspector
    public void SpawnObject(Trial trial)
    {
        int distance = trial.settings.GetInt("stimulus_distance");
        int reward = trial.settings.GetInt("stimulus_reward");

        // below is just standard Unity stuff - not UXF

        // create the object 
        GameObject spawnedObject = Instantiate(objectPrefab);

        // apply our settings to the new object
        spawnedObject.transform.position = new Vector3(0, 0, distance);
        spawnedObject.GetComponentInChildren<Text>().text = reward.ToString();

    }
}