datastruct = initEasyScale(exp_name, ppt_name, input_func [,'parent'] [,'draw_func'] [,'session'] [,'default_init_val'] [,'device_poll_rate'] [,'sample_rate'] [,'record_rate'] [,'lag_window'] [,'default_draw_func_args'] [,'default_input_func_args'] [,'input_func_exit'] [,'input_keys'] [,'exit_keys'] [,'default_respmap'] [,'default_cresp'] [,'stimmap'] [,'condmap'] [,'trigger_next'] [,'prompt_dur'] [,'exp_onset'] [,'resp_buffer'] [,'input_func_device'] [,'exit_device'] [,'default_trial_bin'] [,'console'] [,'files'] [,'params'] [,'isi'] [,'feedback'] [,'break'] [,'num_trials'] [,'headless'] [,'summary_func'] [,'summary_func_args'] [,'trial_summary_func'] [,'default_trial_summary_func_args'] [,'live_score']) [] = optional parameters '' = parameter-value pairs
This is a helper function to initialize the datastructure that easyScale 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. Unlike other easyFunctions which sample some input source while you wait, easyScale bounces between an input_func and draw_func, updating the screen on every cycle. This powerful setup allows you to refresh what is shown as a trial progresses, otherwise known as an interactive experiment.
D = initEasyScale(exp_name,ppt_name,input_func) returns a datastruct filled with default values and strings exp_name and ppt_name as the experiment and participant names, and draw_func and input_func as the drawing and input functions. D = initEasyScale(exp_name,ppt_name,input_func,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 pointer. The reference window in which the easyScale visual components will reside. This pointer is needed in order to allow for incremental drawing, and to set the initial cursor position. Default: 0 'draw_func' String or function handle. A function that governs the drawing of the window display as the trial progresses. If not specified or left empty, no drawing may occur, which might be the desired behaviour if you wish to gather data during a static display, or to make use of the OS cursor (see e.g., demoEasyCursor_point). Default: [] 'default_init_val' Numeric array. Coordinates to indicate the start position of the scale. There must be an entry for each dimension of the scale. Default: 0 'device_poll_rate' Numeric scalar. When a specific device is provided to be polled for input, this parameter (specified in Hz) can be used to specify the maximum speed at which the device natively generates new poll values. Must be a positive scalar value. Default: 60 'sample_rate' Numeric scalar. Specifies the rate at which samples are requested from an input source. If the input is a specific device and the sample_rate exceeds the device_poll_rate, resampling is later performed on collected data to interpolate where necessary. This may be desirable to ensure unique samples are not missed. Must be a positive scalar value. Default: device_poll_rate * 1.25 'record_rate' Numeric scalar. Specifies the final sample rate which is stored in the final output datastruct. This value can be used to reduce demands on memory. Default: device_poll_rate 'lag_window' Numeric scalar. When specified, this parameter allows for continuous plotting of data using the draw function. Lag window must be specified in seconds, and must be a positive value. The value determines the amount of time shown on the plot at any given time. If not specified, the display is only updated in the event of valid keypresses. Default: 0 'default_input_func_args' Cell array. A cell array of optional arguments that will be passed on to each call of the input function. 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: {} '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: {} 'trial_summary_func' String or function handle. Score func is a function that can be used to generate custom statistics based on what is measured by your specific experiment. Score func receives an entire row datastruct.trials, operates on it, and stores the result in the resp_auto field of the trials table within the datastruct. This field in turn will be thoroughly evaluated when later calling easyScore. Default: [] '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: {} '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 'input_keys' Cell array of strings. Specifies the keys that will be accepted as input. 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. Default: {} 'exit_keys' Cell array of strings. Specifies the keys that will can be pressed to terminate the trial. 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. Default: {} 'default_respmap' Table. Table mapping response zones to numeric values and labels. Use makeMap to generate this map. If you do not supply a default_respmap here, you will be required to supply a respmap to easyScale each time you call it. Default: empty table 'default_cresp' Cell array of strings. The string descriptors that specify zones of the response space that will be treated as correct responses. The string entries must be a subset of the descriptors in respmap. 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. Default: {} 'stimmap' Table mapping stimuli to numeric values. When calling easyScale, 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. Default: empty table 'condmap' Table mapping conditions to numeric values. When calling easyScale, 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. 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: [] '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 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 'input_func_device' Numeric integer, string, or cell array of strings. The device that will be polled 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 'input_func_exit' Boolean. Normally, entering a zone defined by a respmap will change the value reported in the respvec and that's it. When this parameter is set to true, entering a zone will end the trial. Default: false 'exit_device' Numeric integer, string, or cell array of strings. The device that will be monitoted for info on whether to terminate a trial. 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 'default_trial_bin' Cell array. Values can be given here as a cell array. These values are then passed on to input_func and draw_func, although they remain unchanged during a trial. Values such as background canvas image and cursor image for a drawing experiment can be specified here. Default: [] '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 '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: [] '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 '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). 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 '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 easyScale. If you prefer to have the break right before the n+1 call to easyScale, 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 '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.