Getting Started

If you are looking for a hands-on approach to getting started quickly, have a look at the Demo scripts. They are described here.

The logic of the OTG toolbox

In this toolbox, you will find that two structures are constantly referred to: AllData and exp_settings. Almost all functions require one of these structures to be inserted. The first, unsurprisingly, is coded so as to make a single structure that contains all collected data. The second structure contains all the settings that are required when using OTG - there are very few fixed values in all of the scripts and functions in the toolbox, so you can customize a great deal about the experiment by editing this structure. Make sure you browse through the settings and see if the defaults are suited for your experiment.
The idea behind these structures is to be as comprehensive as possible, so that only few specifications are required as input to most functions in the toolbox - this keeps things oversightly. Below, more elaborate information about these two structures is given.

The toolbox' functions that have the purpose of presenting something on screen, produce the variable exitflag. Its default value is 0, but when equal to 1, the ESCAPE key was pressed and the experiment must be terminated. You want termination to happen properly, which means: AllData is saved, the Psychtoolbox screen is closed, and any connected hardware (e.g., the eyetracker, or other plugins) is shut down. For this purpose, enter the following line of code after each time you call a presentation function:

if exitflag; BEC_ExitExperiment(AllData); return; end

It is good practice to do this systematically, to make sure you do not lose any data when the experiment needs to be ended prematurely.

The AllData structure

This structure is created at the beginning of the experiment and should have the following main fields from the beginning:

• exp_settings: the first thing you do when using OTG, is calling this structure (see elaboration below). Enter it in the AllData structure, because some functions will require experimental settings as well as other fields from AllData as input in order to work.

• savedir: specify the directory where your data will be saved. This will be a folder inside the data directory defined in exp_settings.datadir (by default, this is the Experiment Data folder within the toolbox directory). Scroll down to the example code below, where the initials of the participant and a date/time string are used to create an ID used to make the individual directory. AllData.savedir is currently used in functions BEC_Calibration (where you can opt to save a summary image of the choice calibration procedure) and BEC_ExitExperiment (see explanation above). Frequent saving during your experiment, e.g. after every trial, is advised. The following command saves the structure as a file AllData.mat: save([AllData.savedir filesep 'AllData'],'AllData');

• triallist: this field is optional. The function BEC_MakeTriallist_Mood shows how the trial list is made for an experiment featuring mood induction and economic choice. Note:

  • AllData.triallist can be called when presenting moods or emotions if the list of affective stimuli is predefined, although you can choose to define the stimuli at a trial-by-trial basis, too.
  • AllData.triallist can also be called by the choice trial generation functions, BEC_OnlineTrialGeneration and BEC_OnlineTrialGeneration_VBA if the order of choice trials to be presented is predefined, but if it is not, an algorithm inside these functions will present each subsequent choice trial automatically in a fully counterbalanced manner.

See the example code below for a convenient way of creating and saving the AllData structure when you start your experiment.

%Start the experiment from the beginning, or at an arbitrary point. This depends on whether AllData exists.
    if ~exist('AllData','var') %Make new dataset
        AllData = struct; %Data structure
        AllData.exp_settings = BEC_Settings; %Settings structure
        AllData.initials = input('Initials: ','s'); %Participant data
        savename = [AllData.initials '_' datestr(clock,30)]; %Directory name where the dataset will be saved
        AllData.savedir = [exp_settings.datadir filesep savename]; %Directory path where the data will be saved      
        mkdir(exp_settings.datadir,savename); %Create the directory where the data will be stored
        disp('Dataset and directory created.')
    else %A dataset already exists
        clearvars -except AllData %Keep only the data structure
    end

The exp_settings structure

This structure is produced by calling exp_settings = BEC_Settings. It contains almost all settings that you'll need, and more. If you want to modify anything, you just have to scroll to the section that is relevant for your present purposes and make the changes there. The sections are:

• Setup: (please leave untouched)

• Directories: defaults for the directories that contain stimuli and experiment data. Modifying is not recommended.

• Graphics defaults: allows you to set the fonts and colors. Current default settings are optimized for computer experiments. You will want to make some changes when using a tablet (e.g., make your fonts appear larger when using the a Windows Surface, which has a higher PPI).

• Choice screen configuration: please verify that these settings are suited for your experiment.

  • Cost and reward features: select the fixed reward and fixed loss (in euros), and the maximum cost level for each of the 4 choice types. These values are associated with the costly choice option. The current defaults have been successful for modelling economic discounting in multiple studies, both in labs and online.
  • Timings: choose the minimum and maximum response time, the time during which the selected choice is shown (confirmed) on screen, and the [min max] fixation time between choices, between which a jittered value will be drawn.
  • Choice screen visual parameters: here, all the visual features of the choice screen are constrained, mostly as "rects" with the idiosyncrasies of Psychtoolbox (i.e. [x1 y1 x2 y2] with the origin in the top left corner). Note especially the variable called costbox, which is an imaginary rectangular box within which the costs are visualized on screen. Again, default settings are optimized for desktop computer screens, but when using a laptop or a Windows Surface for example, consider making the cost box larger.

• Choice trial generation settings: please verify that these settings are suited for your experiment.

  • Choice triallist creation settings: (optional) these are the settings that were used in most previous experiments.
  • Example choice trials: 12 suggested choices that would give a participant a good impression of the range of costs/rewards in the experiment.
  • Online trial generation: please verify that these settings are suited for your experiment, if you are using the online trial generation procedure.
    • Choice types: specify the choice types that you want to include, but leave the names untouched (e.g., if you want to include choice types 1, 2, and 4, the four type names must exist.)
    • Sampling grid: (please leave untouched - the current default is to bin the cost spectrum, which consists of 50 cost levels, into 5 bins and to fit the value function as broken down into 5 linear segments)
    • Parameter settings: (please leave untouched, these settings are optimized for model fitting - see the dedicated page of the algorithm for more information)
    • Calibration settings: these settings are only useful if you have a choice calibration phase in your experiment. Agnostic priors are specified here, as well as the number of calibration trials and four burn trials (these are optional, can be set empty: [ ]).
    • Algorithm settings: the value max_n_inv is important because it specifies how many past trials of the given choice type to take into account in the online trial generation. If you have an experiment where you anticipate episodes where choice behavior will be altered (e.g., mood experiments), you want to allow the algorithm to reflect those drifts. If this is not of interest to you, simply set this variable to a very high value. The other variables in this section are relevant specifically to the Gauss-Newton algorithm that is used in the non-VBA version of the online trial generation procedure, and should be left untouched.
    • VBA: Dimensions and Options: please leave untouched; the online trial generation procedure contains all the settings for a version with 5 bins (i.e. 6 parameters).