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.

Settings from .json files

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 settings

// set the setting called "example" to the value 100
settings.SetValue("example", 100);

Get settings

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");

Cascading requests

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.

---

Settings from .json files (legacy)

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"])