datastruct = initEasyKeys(exp_name, ppt_name [,'session'] [,'default_respmap'] [,'default_cresp'] [,'stimmap'] [,'condmap'] [,'trigger_next'] [,'prompt_dur'] [,'listen_dur'] [,'exp_onset'] [,'resp_buffer'] [,'device'] [,'console'] [,'files'] [,'opt_out'] [,'draw_func'] [,'draw_func_args'] [,'params'] [,'parent'] [,'isi'] [,'feedback'] [, 'break'] [,'respmap_shuffle'] [,'multiple_presses'] [,'num_trials'] [,'summary_func'] [,'summary_func_args'] [,'trial_summary_func'] [,'default_trial_summary_func_args'] [,'live_score'] [,'headless']) [] = optional parameters '' = parameter-value pairs
This is a helper function to initialize the data structure that easyKeys takes as input. Because these parameters normally stay the same for a given type of datastruct, they can be set once here and forgotten. In general, you should only need to call this function once for each type of question in your experiment. The required variable 'exp_name' is a string to identify this particular easyKeys test, and will be used for file management. The supplied 'exp_name' variable cannot be a directory. 'ppt_name' is a required non-path string and is used to uniquely identify data to a particular person. 'trial_summary_func' an optional function called during easyScore, or after each trial using the 'live_score' parameter, for customized evaluation and scoring of trial responses.
D = initEasyKeys(exp_name,ppt_name) returns a datastruct filled with default values and string exp_name as the experiment name and ppt_name as the name of the participant. D = initEasyKeys(exp_name,ppt_name,param1,val1,param2,val2...) sets various optional parameters. Parameters are case-insensitive, and each string parameter must be followed by a value as indicated: 'session' Scalar integer. This number will be used to identify the session number of the experiment. Multiple-session experiments can be analyzed and compared later on. Default: 1 'default_respmap' Table mapping keys to numeric values and labels. Defines the semantic and numerical "meaning" of each allowed key. On trials where no trial-specific respmap is provided, this one will be used instead. Respmaps are useful e.g., to facilitate interpretation of key presses, or for use with a scale where the user ultimately plans to perform computations on response values. Use makeMap to generate this map. If you do not supply a default_respmap here, you will be required to supply a respmap to easyKeys each time you call it. Note that if a parent window has been specified, any descriptor with the substring "[textbox]", when selected by a user, will trigger presentation of a text box (powered by easyType) and be scored accordingly. Optionally, four values can be inserted in the square brackets to define the desired bounds of the textbox, and a string in double-quotes can be used to present a custom prompt with the triggered textbox (default is "Please elaborate on your response"). Example syntax is [textbox 0 0 400 100 "my prompt"] or [textbox "my prompt] or [textbox 0 0 400 100]. Default: [] 'respmap_shuffle' String. Reorganizes the manner in which respmap options are mapped to the supplied input keys. This could be useful e.g., for randomizing the keys used for particular response options across participants; reversing the left/right or up/down orientation of a scale; or scrambling the position in which a target item appears within a set of items on each trial. The respmap will be adjusted at run-time, when easyKeys is called, and the position of cresp and resp values will be adjusted accordingly. This option is only used if easyKeys has been put in charge of drawing stimulus options (i.e., a "parent" has been provided; see below). Available options are 'none', 'flip', 'shuffle', and 'shuffle_trial' (flip and shuffle set the respmap order based on the participant's name/id, whereas shuffle_trial will set the respmap order differently once per trial). The randomization for this option will be determined by the seed in startSession (if set); otherwise, it will be determined by the random stream set by matlab upon startup. Default: 'none' 'default_cresp' Cell array of strings or NaN's. The key labels or keys that should be treated as being correct responses (NOT their respmap value). If there is no one correct answer, omit this parameter, and all valid responses will be treated as correct. NaN indicates that a null response is correct. If there is more than one correct key, specify cresp as a cell array of strings (with NaN as a valid element as well). Default: {} 'stimmap' Table mapping stimuli to numeric values. When calling easyKeys, you will have the option of specifying the active stimulus. If you want to better keep track of which stimulus is which across tests, it can be helpful to assign a unique id to each stimulus that you can use to sort stimuli later. If you provide this map here, it will be used as a lookup table on each easyKeys call in which you specify a stimulus. Use makeMap to generate this map. If left blank here, easyKeys will dynamically generate its own id map as stimuli are fed to it that can then be fed in here (pass in datastruct.stimmap). Default: empty table 'condmap' Table mapping conditions to numeric values. When calling easyKeys, you will have the option of specifying a condition number for each trial. If you want to better keep track of which condition is which and assemble onsets across tests with a consistent matrix size, it can be helpful to assign a unique id to each condition here. If you provide this map (use makeMap to generate it), conditions will be translated into the corresponding string (e.g., cond=2 and condmap={'on','off'} would be reported as 'off') and onset maps will be generated in a consistent way. If left empty or omitted here, the condition string will be reported as a string version of the number (e.g., '2'). For experiments with multiple condition factors, supply this argument as a cell array of condmaps. Default: empty table 'trigger_next' Boolean. Determines if easyKeys code execution will carry on as soon as a response is detected. Setting this to false can be useful in situations where it is desirable to hold stimulus presentation rate constant (e.g., in an fMRI study); whereas setting this to true might make sense in a self-paced scenario. Default: true 'prompt_dur' Numeric scalar or empty array. The maximum period, specified in seconds, for which you would like to present participants with the initial prompt screen while waiting for a response. Specify a duration of 0 to sample for a current keypress and then exit. It can be provided as an empty array if you would like to provide prompt_dur dynamically during the experiment. Default: [] 'listen_dur' Numeric scalar. Sometimes, it makes sense to listen for responses even after the initial prompt has been removed from the screen. If this parameter is set, then a flip will be executed after prompt_dur has elapsed and responses will be observed for the period specified by listen_dur (in seconds). Note that this will hold back further execution of other code (i.e., the program will linger on the second screen until the listen_dur time is up). Default: 0 'exp_onset' Numerical scalar. By default, onset times will be measured relative to the time at which this initialization function is called (i.e., the difference in GetSecs between later trials and initialization). Onsets can alternately be measured relative to a different initialization time, e.g., one passed by a trigger_next function used to synchronize the experiment with some other data source (e.g., an fMRI scanner). Default: output of GetSecs command 'resp_buffer' Numeric scalar. Time period for which trial information will be temporarily written to disk. Current trial, time remaining, and supplied EASYKEYS parameters are stored which can be used to resume a trial in case there is a program crash. If supplied as NaN, no periodic response logging is performed. Default: NaN 'device' Numeric integer, string, or cell array of strings. The device that will be monitored for responses. Can be specified explicitly as a numeric deviceID, or supplied as a full or partial device name, full serial number, or full locationID, in which cases getInputDevice will try to guess the correct deviceID. Default: arbitrary keyboard selected from available devices 'console' Boolean. Determines whether or not performance information (e.g., stim, resp, rt, cresp, acc) is printed to the screen each time a question is asked. Default: false 'files' Boolean. Determines if the datastruct is saved to a .mat and .txt file each time easyKeys is called in order to make sure the latest data is available in case of a crash. Default: true 'draw_func' String or function handle. By default, easyKeys does not do any drawing. However, if you wish easyKeys to draw its own multiple choice options, you can set this parameter to a string describing a style in which the question should be drawn. Available choices are "tall", "wide", "scale", "columns", and "navbar". Alternatively, you can specify your own function handle for drawing (it may be helpful to inspect drawSPTBchoices as a template). If set to an empty string, no drawing is done. Requires parent to be specified. Optionally, params can be specified (without it, a default drawing style is used). Default: '' 'default_draw_func_args' Cell array. A cell array of optional arguments that will be passed on to each call of the draw function. Default: {} 'feedback' Scalar or 4-cell array. By default, no feedback is presented to the user. However, if a parent is provided, you can provide a positive value here to have feedback presented for that many seconds. The default feedback values are "Correct!" in green, "Incorrect" in red, or "Too slow" in red. However, alternate strings or image filepaths can be used instead. To do so, provide a four-cell array, with feedback duration in the first position, followed by feedback for a correct answer, then for an incorrect answer, then for a null response (applied only when a null response is incorrect). Default: 0 'break' Scalar or 2-cell array. By default, the experiment is the same on every loop. However, if a parent is provided, you can provided a positive value n here to provide a 10-second break after every nth call to easyKeys. If you prefer to have the break right before the n+1 call to easyKeys, e.g., -2 in a four-trial experiment such that the experiment will provide a break after trial 2 but not right before it concludes after trial 4), you can set n to a negative value. When set to zero, no breaks are provided. For more control over breaks, provide a 2-cell array instead, with break frequency in the first position, followed in the second position by either a numeric break duration (e.g., 5) or key to press to continue (e.g., 'space'). Default: 0 'parent' Window pointer. The reference window in which multiple choice options will be presented. This pointer is only needed if you wish to make use of the draw_func parameter (see below). Default: nan 'params' Struct. Structure object as supplied by easyLaunch. These can be retained in the datastruct either for use by secondary functions or just for logging purposes. Default: [] 'opt_out' Char. Set this to any char not used within the respmap to append an invisible "Decline response" option. This option is not explicitly presented to the user when using easyKeys' draw options, but when selected is treated as a valid response, ending the trial. The value NaN is recorded in the resp field, and the trial receives an "acc" value of 0, unless cresp is set to NaN. This option is suitable when opt-out instructions are to be presented at the beginning of a session but not repeated on every trial. Default: '' 'isi' Scalar. Set this to any positive value to have easyKeys produce a centred fixation cross for that duration in seconds. If a navbar is in use (see draw_func), then it is maintained throughout the ISI period. To have the ISI period take place before a trial begins, set the value to negative (e.g., -1 would produce a one-second isi before a trial). This can help with timing, as internal SPTB preparation for the trial is able to take place during the ISI period. To have the ISI take place after the trial is complete, set the value to positive (e.g., 1 would produce a one-second isi after a trial). This may be preferred when you wish to draw the trial screen yourself, rather than having it be replaced by a fixation cross and drawn by SPTB. Requires a parent window to be set. Default: 0 'num_trials' Positive integer. When using the parent parameter, set this to a positive integer representing the total number of trials expected in the experiment to have calls to easyKeys reveal the experiment progress in the top-left corner of the screen ("trial X / num_trials"). Also prevents the goofy but usually harmless situation where you display a break right after the final trial of your experiment. This will NOT prevent you from running more trials than the number you have allotted, but warnings will be printed to the console. Therefore, this parameter can also help catch bugs in your experimental logic. Default: nan 'summary_func' String or function handle. For later scoring, you may specifiy a function to supplement the automatic scoring outputs of easyScore to analyze subsets of datastruct.trials. You may wish to summarize user responses in more sophisticated ways than e.g., just taking the mean across each trial subset. This function is called many times during analysis: once for an overall score, but also once for each condition, level of nesting, etc., so it is a good way to quickly implement your statistic for interpretation at many levels of your output. If you don't have this now, that's okay -- you can add it later or override your choice with easyScore. Default: [] 'summary_func_args' Cell array. A cell array of optional arguments that will be passed to each call of the scoring function. Default: {} 'trial_summary_func' String or function handle. Score func is a function that can be used to generate statistics measures desired by the user. The output of these statistics is stored in the resp_auto field of the trials table within the datastruct, and will be included in the basket variables analyzed by a call to easyScore. Default: [] 'default_trial_summary_func_args' Cell array. A cell array of optional arguments that will be passed on to each call of the scoring function. Default: {} 'multiple_presses' Boolean. When set to true, . Default: {} 'live_score' Boolean If set to true, trial_summary_func will be applied after each trial rather than in easyScore. Unless live feedback is required, it is recommended to leave this parameter at "false", as unforseen problems with your trial_summary_func may interrupt the experiment. Default: false 'headless' Boolean. When set to true, does not place any calls to Screen or getSPTBinput to avoid crashing SPTB when running it on a server. This is appropriate when, for example, attempting to use easyImport to import new data. Default: false
datastruct: a data structure containing the various parameters that were provided to this initialization function. Fields corresponding to absent optional parameters are set to default values.