Settings system
The settings system allows researchers to assign parameters (e.g. independent variables) to the Session, a Block, or a Trial. The settings system is handled with a dedicated class: Settings.
Instances of a Session, Block, or Trial each contain a .settings field which is initially populated with an empty settings object.
When we begin the Session, we optionally pass a Settings object to be then used as the settings for the Session. If we are using the UI, the UI does this step for us - passing to the session the settings found in the selected .json file.
By default the Session is started using the UI, with a selected .json file ("Experiment profile") is deserialized. The deserialization is performed by the popular MiniJSON script. Example .json file:
{ "a_number": 1, "a_string": "hello", "a_boolean": true, "an_array": [1, 2, 3], "another_array": ["hi", 1, false], "an_object": { "num": 1, "text": "hello" } }Note: Even on systems where , is used as a decimal point (i.e. non English language locales) you should still use . as a decimal separator. This is a limitation of the JSON spec.
When deserializing from .json, care must be taken when converting the type of the objects in our settings file. JSON is just a string - so MiniJSON interprets each value and attempts to deserialize it into an appropriate C# type. As of March 2019, the syntax for getting and setting settings values uses .Get* and .SetValue methods.
// set the setting called "example" to the value 100 settings.SetValue("example", 100);| Example JSON | JSON type | Desired C# type | Access example |
|---|---|---|---|
{"example": 123} | int | int | settings.GetInt("example") |
{"example": 123} | int | float | settings.GetFloat("example") |
{"example": 3.14} | float | float | settings.GetFloat("example") |
{"example": true} | bool | bool | settings.GetBool("example") |
{"example": {"sub_key": 1}} | object | Dictionary<string, object> | settings.GetDict("example") |
{"example": [1, "red", true]} | array | List<object> | settings.GetObjectList("example") |
{"example": [1, 2, 3]} | array | List<int> | settings.GetIntList("example") |
{"example": [1, 1.5, 2]} | array | List<float> | settings.GetFloatList("example") |
If you have issues you can check validity of your JSON files with an online validator tool.
An example getting a setting called size from a trial, which you can use however you like (e.g. scale up an object):
float size = trial.settings.GetFloat("size");The setting system is set up such that, if a settings is unavailable, the request will cascade up the experiment hierarchy. For example, if a settings is not available for the Trial, it will look inside the Block, and then inside the Session. This means you can easily apply, for example, a setting to a whole block but have specific trials within that block that have a different value for that setting.
Previous versions of UXF (before March 2019) required the use of the below syntax for accessing settings. Now the above method is recommended.
| Example JSON | JSON type | C# cast example |
|---|---|---|
{"example": "hello"} | string | (string) settings["example"] |
{"example": 123} | int | (long) settings["example"] |
{"example": 3.14} | float | (double) settings["example"] |
{"example": [1, 2, 3]} | array | (List<object>) settings["example"] |
{"example": {"a": 1, "b": "hello"}} | Dictionary<string, object> | (Dictionary<string, object>) settings["example"] |
{"example": true} | bool | (bool) settings["example"] |
Note: Add using System; to the top of your script to gain access to the Convert.To*() methods.
| Example JSON | JSON type | Desired C# type | C# Conversion example |
|---|---|---|---|
{"example": 123} | int | int | Convert.ToInt32(settings["example"]) |
{"example": 123} | int | float | Convert.ToSingle(settings["example"]) |
{"example": 3.14} | float | float | Convert.ToSingle(settings["example"]) |