Session

`UXF.Session`

The Session represents a single "run" of an experiment, and contains all information about that run.

Fields

endOnQuit: Enable to automatically safely end the session when the application is quitting.

endOnDestroy: Enable to automatically safely end the session when this object is destroyed.

endAfterLastTrial: Enable to automatically end the session when the final trial has ended.

setAsMainInstance: If enabled, you do not need to reference this session component in a public field, you can simply call "Session.instance".

dontDestroyOnLoadNewScene: If enabled, this GameObject will not be destroyed when you load a new scene.

blocks: List of blocks for this experiment

storeSessionSettings: Enable to save a copy of the session.settings dictionary to the session folder as a .json file. This is written just as the session begins.

storeParticipantDetails: Enable to save a copy of the session.participantDetails dictionary to the session folder as a .csv file. This is written just as the session begins.

customHeaders: List of dependent variables you plan to measure in your experiment. Once set here, you can add the observations to your results dictionary on each trial.

settingsToLog: List of settings (independent variables) you wish to log to the behavioural file for each trial.

trackedObjects: List of tracked objects. Add a tracker to a GameObject in your scene and set it here to track position and rotation of the object on each Update().

onSessionBegin: Event(s) to trigger when the session is initialised. Can pass the instance of the Session as a dynamic argument

onTrialBegin: Event(s) to trigger when a trial begins. Can pass the instance of the Trial as a dynamic argument

onTrialEnd: Event(s) to trigger when a trial ends. Can pass the instance of the Trial as a dynamic argument

preSessionEnd: Event(s) to trigger just before the session has ended. If you wish to perform any summary statistics or write any final session data this is the time to do it. Do not use this event to quit the application.

onSessionEnd: Event(s) to trigger when the session has ended and all jobs have finished. It is safe to quit the application beyond this event. You cannot perform data operations in this event.

experimentName: Name of the experiment. Data is saved in a folder with this name.

ppid: Unique string for this participant (participant ID)

number: Current session number for this participant

currentTrialNum: Currently active trial number. Be careful of modifying this.

currentBlockNum: Currently active block number.

participantDetails: Dictionary of objects for datapoints collected via the UI, or otherwise.

instance: A reference to the main session instance that is currently active.

baseHeaders: The headers that are always included in the trial_results output.

dataHandlers: Reference to the associated DataHandlers which handles saving data to the cloud, etc.

Properties

isEnding: Returns true when the session is in the process of ending. It is useful to query this in On Trial End events, since you may not need to perform some behaviour if the session is ending.

hasInitialised: Returns true if session has been intialised

settings: Settings for the experiment. These are provided on initialisation of the session.

InTrial: Returns true if current trial is in progress

CurrentTrial: Returns the current trial object.

NextTrial: Returns the next trial object (i.e. trial with trial number currentTrialNum + 1 ).

PrevTrial: Get the trial before the current trial.

FirstTrial: Get the first trial in the first block of the session.

LastTrial: Get the last trial in the last block of the session.

CurrentBlock: Returns the current block object.

Trials: Returns a list of trials for all blocks. Modifying the order of this list will not affect trial order. Modify block.trials to change order within blocks.

BasePath: The path in which the experiment data are stored.

ExperimentPath: Path to the folder used for reading settings and storing the output.

ParticipantPath: Path within the experiment path for this particular particpant.

Headers: Stores combined list of headers for the behavioural output.

ActiveDataHandlers: Get the currently selected dataHandlers for this session.

Methods

UXF.Session.Awake()

Provide references to other components

Parameters

None

UXF.Session.CheckSessionExists(string, string, string, int)

Checks if there is a risk of overwriting data for this participant and session number

Parameters

experimentName:

participantId:

baseFolder:

sessionNumber:

UXF.Session.Begin(string, string, int, System.Collections.Generic.Dictionary<string, object>, UXF.Settings)

Initialises a Session

Parameters

experimentName: A name for the experiment

participantId: A unique ID associated with a participant

baseFolder: Location where data should be stored

sessionNumber: A number for the session (optional: default 1)

participantDetails: Dictionary of information about the participant to be used within the experiment (optional: default null)

settings: A Settings instance (optional: default empty settings)

UXF.Session.CreateBlock()

Create and return 1 Block, which then gets automatically added to Session.blocks

Parameters

None

UXF.Session.CreateBlock(int)

Create and return block containing a number of trials, which then gets automatically added to Session.blocks

Parameters

numberOfTrials: Number of trials. Must be greater than or equal to 1.

UXF.Session.GetTrial()

Get currently active trial. When not in a trial, gets previous trial.

Parameters

None

UXF.Session.GetTrial(int)

Get trial by trial number (non zero indexed)

Parameters

None

UXF.Session.GetNextTrial()

Get next Trial

Parameters

None

UXF.Session.EndCurrentTrial()

Ends currently running trial. Useful to call from an inspector event

Parameters

None

UXF.Session.BeginNextTrial()

Begins next trial. Useful to call from an inspector event

Parameters

None

UXF.Session.BeginNextTrialSafe()

Begins next trial (if one exists). Useful to call from an inspector event

Parameters

None

UXF.Session.EndIfLastTrial(UXF.Trial)

Ends the session if the supplied trial is the last trial.

Parameters

None

UXF.Session.GetPrevTrial()

Get previous Trial.

Parameters

None

UXF.Session.GetFirstTrial()

Get first Trial in this session.

Parameters

None

UXF.Session.GetLastTrial()

Get last Trial in this session.

Parameters

None

UXF.Session.GetBlock()

Get currently active block.

Parameters

None

UXF.Session.GetBlock(int)

Get block by block number (non-zero indexed).

Parameters

None

UXF.Session.SaveDataTable(UXF.UXFDataTable, string, UXF.UXFDataType)

Saves a DataTable to the storage locations(s).

Parameters

table: The data to be saved.

dataName: Name to be used in saving.

dataType:

UXF.Session.SaveJSONSerializableObject(System.Collections.Generic.List<object>, string, UXF.UXFDataType)

Saves a JSON Serializable Object to the storage locations(s).

Parameters

serializableObject: The data to be saved.

dataName: Name to be used in saving.

dataType:

UXF.Session.SaveJSONSerializableObject(System.Collections.Generic.Dictionary<string, object>, string, UXF.UXFDataType)

Saves a JSON Serializable Object to the storage locations(s).

Parameters

serializableObject: The data to be saved.

dataName: Name to be used in saving.

dataType:

UXF.Session.SaveText(string, string, UXF.UXFDataType)

Saves a string of text to the storage locations(s).

Parameters

text: The data to be saved.

dataName: Name to be used in saving.

dataType:

UXF.Session.SaveBytes(System.Byte[], string, UXF.UXFDataType)

Saves an array of bytes to the storage locations(s).

Parameters

bytes: The data to be saved.

dataName: Name to be used in saving.

dataType: