datastructs = startSession(datastructs [,'seed'] [,'instructions'] [,'recovery_mode'] [,'params'] [,'tokens'] [,'information'] [,'retain_exp_onset'] ['start_func'] [,'start_func_args']) [] = optional parameters '' = parameter-value pairs
STARTSESSION is for use at the beginning of any experiment: it suppresses user input, sets the random seed, presents user instructions, lets the recoveryManager know which datastructs are at large, and sets the exp_onset times of all your datastructs. It also attaches the params prepared by easyLaunch to each datastruct for later reference. Call this once you are done with all of your initEasyFunction calls, and supply the initialized datastructs to this function. Remember to also use endSession at the end of your experiment to clean up, and to alert the recoveryManager that the session is over. Datastructs should be caught from this function in the same order they are supplied. The caught datastructs will have seed values retained in their params fields.
[datastruct1, datastruct2, ...] = startSession(datastruct1,datastruct2, ...) returns datastructs updated by startSession, and logs the datastructs with the recoveryManger. [datastruct1, datastruct2, ...] = startSession(datastruct1,datastruct2, ..., param1,val1,param2,val2...) acts as above, and also sets various optional parameters. Parameters are case-insensitive, and each string parameter must be followed by a value as indicated: 'seed' String or scalar. This parameter indicates the kind of randomization you would like to initiate for this session. If left unset, the current random stream will be used. Whichever stream that is selected will be used in the first datastruct, and called to generate additional seeds for subsequent datastructs. See setRandSeed for further usage information. Default: [] 'instructions' String or char array of strings. If set to a string or cell array of strings, the string(s) will be presented as subsequent screens full of instructions. This requires both "params" and "tokens" to be provided. At the bottom of each screen will be the string set in params.strings.continue, with the final set of instructions receiving the string set in params.strings.begin. The text will be displayed using the formatting specified in params. After each screen is presented, the experiment will wait for the user to press the key params.keys.user.exit. Any instructions supplied will be retained in all of your datastructs in a field named "instructions". Default: {} 'retain_code' String or char array of strings. By default, startSession will copy all the functions in the calling stack to the participant's raw data directory. Normally, these are just short text files and won't take up much space, and you'll have a sure-fire way of knowing what code was used to generate your result. However, you can turn off this feature by setting this parameter to false. Default: true 'recovery_mode' Boolean. SPTB can resume experimental sessions that are interrupted by power failures, system crashes or other reasons by loading the in-progress files and using them to restore to the prior state. This requires a little work in your experiment code as well, to make sure that the experiment does not repeat trials for which there is already data, and that you make the same random calls you normally would so that the random stream is in the correct state. However, recovery_mode will replace the empty datastructs fed to this function with ones in progress, and even rescue resp_input_vecs, such as an essay that was not yet submitted via easyType, or drawing not yet submitted via easyCursor. This function is ideal for situations where simply starting the session over is problematic (e.g., in an fMRI memory experiment where participants are learning each stimulus through a single exposure). Requires params and tokens. When recovery_mode is set to true, the value of retain_exp_onset will be treated as true in all cases. Default: false 'params' Structure object as supplied by easyLaunch. Contains useful info about the experiment environment (e.g., display resolution). Default: [] 'tokens' Structure object as supplied by easyLaunch. Contains temporary pointers (e.g., to the main window, to a random stream, etc.). Default: [] 'information' Any variable. Any parameter you supply here will be attached to all of your datastructs in an "exp_info" field. This can be useful for storing e.g. a struct containing details about your experiment (e.g., keys, durations, instructions, etc). Default: [] 'retain_exp_onset' Boolean. The experiment onset time inside any datastructs supplied will normally be updated to match the time at which STARTSESSION exits (i.e., the moment at which the last instructions screen was cleared by the user). If you would like to keep the original exp_onset times inside the datastructs, then set this parameter to true. Default: false 'start_func' String or function handle. Run a custom function (before instructions) that is specified as a string or function handle. The function will have access to all of the included datastructs. This could be useful for, e.g., performing additional initialization steps. Any provided script must accept arguments in the form myfunc(params, tokens, datastructs, start_func_args). Default: [] 'start_func_args' Cell array. A cell array of arguments to be passed to the custom function. Default: {}