datastruct = initEasyType(exp_name, ppt_name, [,'parent'] [,'session'] [,'default_respmap'] [,'default_dim'] [,'margin'] [,'back_colour'] [,'font_type'] [,'font_size'] [,'font_colour'] [,'char_limit'] [,'exit_keys'] [,'default_cresp'] [,'default_resp_type'] [,'case_sensitive'] [,'stimmap'] [,'condmap'] [,'trigger_next'] [,'prompt_dur'] [,'exp_onset'] [,'resp_buffer'] [,'device'] [,'console'] [,'files'] [,'params'] [,'isi'] [,'feedback'] [,'break'] [,'num_trials'] [,'draw_func'] [,'draw_func_args'] [,'summary_func'] [,'summary_func_args'] [,'headless'] [,'trial_summary_func'] [,'live_score'] [,'default_trial_summary_func_args']) [] = optional parameters '' = parameter-value pairs


This is a helper function to initialize the data structure that easyType takes as input. These parameters normally stay the same for a given type of datastruct, so 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 easyType 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 = initEasyType(exp_name,ppt_name) returns a datastruct filled with default values and string exp_name as the experiment name and ppt_name as the participant name. D = initEasyType(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 'parent' Window or screen pointer. The reference window for which the input box coordinates will refer to. This is always required, as a parent window is needed to draw the text box and print updates. Default: 0 'default_dim' 4-vector of positive numbers: [X1 Y1 X2 Y2]. [X1 Y1] specifies the upper-left boundary of the input text box, and [X2 Y2] specifies the lower-right boundary. The boundaries are pixel coordinates with respect to the supplied window or screen pointer. Y2-Y1 is the height of the box, and X2-X1 is the width. Both height and width must be greater than zero. If you do not supply a default_dim here, you will be required to supply a box to easyType each time you call it. Default: entire screen 'margin' Positive numeric scalar. Specifies the margin in pixels to leave between the text and the top-left corner of the input text box. Default: 4 'back_colour' Unsigned integer [R G B] triplet or grayscale scalar. Specifies the desired colour for the input text box background. R, G, and B must be unsigned integers in the range [0, 255]. and denote colour levels of red, green, and blue respectively, with 0 being none, and 255 being full saturation. Alternatively, back_colour can be specified as a single positive integer in the range [0, 255], which would specify a grayscale intensity with 0 being black, and 255 being white. Default: 255 (white) 'font_type' String specifying font type. This is the font that will be used for the input text box. If a font is selected that doesn't exist, no error is raised and the font will be set to the default value. Default: 'Courier New' 'font_size' Scalar positive integer in the range [1, 72]. Specifies the size of the font being input by the user. Note: If box dimensions are not specified, the supplied font_size may be too large for the input box. Default: 14 'font_colour' Unsigned integer [R G B] triplet. Specifies the desired font colour of text being input into the input box. R, G, and B must be unsigned integers in the range [0, 255], and denote colour levels of red, green, and blue respectively, with 0 being none, and 255 being full saturation. Alternatively, back_colour can be specified as a single positive integer in the range [0, 255], which would specify a grayscale intensity with 0 being black, and 255 being white. Default: [0 0 0] (black) 'char_limit' Two-element vector of positive integers: [MIN MAX]. Specifies the required range of characters that needs to be input for the experiment to proceed. MIN and MAX must both be 0 or greater, and MIN must be equal to or less than MAX. If the number of input characters violates these restrictions, a warning message will be displayed in the input box. Default: [0 10000] 'exit_keys' Cell array of strings. Specifies the keys that terminate collection of text by easyType. Use KbName('KeyNames') to see a list of all keynames. The command KbName('UnifyKeyNames') is recommended at the top of your script to ensure maximum portability between operating systems. Note: an exit key press doesn't automatically trigger the next trial (unless trigger_next is set to true), but waits for the duration to time out. If exit_keys is set to empty, the user is forced to wait for the duration to time out before the experiment continues. Default: {'Return'} 'default_cresp' Cell array of strings or NaN's. The strings that should be treated as being correct responses. 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 response, specify cresp as a cell array of strings (with NaN as a valid element as well). Default: {} 'default_resp_type' 2-element cell array of strings. Determines the type of response expected by easyType when an exit key is pressed. If not provided or set to an empty string, all types of responses are accepted. When an exit key is pressed, the response string is stored in two variables: 'num' which is a numeric value obtained by using str2double on the response string, and 'text' which is a character array. The first cell must be a string that will be evaluated as a boolean, and can incorporate the 'num' and 'text' variables mentioned above. The second cell is a string message that will be displayed to the user if the condition in the first cell does not evaluate to true. For example, to ensure the user input is a number greater than 0, the default_resp_type can be given as, {'~isnan(num) && num>0', 'must be number greater than 0'}; Default: {} 'default_respmap' Table mapping strings to numeric values and labels. Defines the semantic and numerical "meaning" of a set of anticipated input strings. On trials where no trial-specific respmap is provided, this one will be used instead. Case insensitive matching is used against strings in the "input" field and then mapped to the descriptors and values fields, as appropriate. Although freeform easyType responses are less likely on average to exactly match prepared inputs, this respmap is also displayed by easyCode, and may facilitate manual response scoring. Use makeMap to generate this map. Default: [] 'case_sensitive' Boolean. Determines whether or not the string comparisons between user input and the correct response are case-sensitive. Default: false 'stimmap' Table mapping stimuli to numeric values. When calling easyType, 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 easyType call in which you specify a stimulus. Use makeMap to generate this map. If left blank here, easyType 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 easyType, 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 easyType code execution will carry on as soon as a response is detected. If set to false, easyType will wait after a response until the specified duration has elapsed, which could be useful in situations where it is desirable to hold stimulus presentation rate constant (e.g. in an fMRI study); whereas setting it 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. Must be greater than 0. It can be provided as an empty array if you would like to provide prompt_dur dynamically during an experiment. Default: [] 'exp_onset' Numeric 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 response information will be written to disk as temporary files. This can be used to backup responses for long trials 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 keyboard 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 easyType is called in order to make sure the latest data is available in case of a crash. Default: true '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: [] 'isi' Boolean. Set this to any positive value to have easyKeys produce a centred fixation cross for that duration in seconds. 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). Requires a parent window to be set. Default: 0 '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 easyType. If you prefer to have the break right before the n+1 call to easyType, 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 'num_trials' Positive integer. Set this to a positive integer representing the total number of trials expected to supply your drawFunc with information about experiment progress (which you may optionally draw). 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, although 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: [] 'draw_func' String or function handle. By default, easyType just draws a textbox on the screen that you yourself prepare. However, if you wish easyType to draw its own presentation of your stimuli, you can set this parameter to a string describing a position in which the question should be drawn relative to the textbox ('above', 'below', 'left', 'right', 'behind'). Alternatively, you can specify your own function handle for drawing (it may be helpful to inspect drawSPTBtextbox 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. The default function, drawSPTBtextbox, can be supplied as follows: draw_func_args are expected in a three-cell array. easyType will supplement any drawing you have done before calling easyType by drawing (in order of cell position) a label, stimulus, position, and the provided initialization text (disappears when typing begins). The label may be any text. Stimulus may be any text, image, audio file, or video; by default, it is the stimulus provided to easyType. Start text can be any string and by default designates the exit key, if any. Default: {[], stimulus, ... 'Begin typing, and press when finished'} '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: {} '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. datastruct contains a field 'box' which contains parameters specific to the input box such as font size, background colour, etc.