datastruct = initEasyVoice(exp_name, ppt_name [,'session'] [,'record_quality'] [,'threshold'] [,'latency_class'] [,'export_audio'] [,'groupscore_audio'] [,'default_cresp'] [,'stimmap'] [,'condmap'] [,'default_respmap'] [,'trigger_next'] [,'prompt_dur'] [,'listen_dur'] [,'exp_onset'] [,'resp_buffer'] [,'device_key'] [,'device_audio'] [,'console'] [,'files'] [,'params'] [,'parent'] [,'isi'] [,'feedback'] [,'break'] [,'num_trials'] [,'draw_func'] [,'draw_func_args'] [,'summary_func'] [,'summary_func_args'] [,'trial_summary_func'] [,'headless'] [,'default_trial_summary_func_args'] [,'live_score'] [] = optional parameters '' = parameter-value pairs
This is a helper function to initialize the data structure that easyVoice 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 easyVoice 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. '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 = initEasyVoice(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 = initEasyVoice(exp_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 'record_quality' String. One of {'low', 'medium', 'high', 'extreme'}. The fidelity of the audio recording captured during each trial. Specify as "low" (default), "medium", "high" or "extreme". "Low" quality corresponds to 8000Hz, 8-bit mono sampling and is sufficient to understand human speech. "Medium" corresponds to 22050Hz, 16-bit mono. "High" corresponds to 44100Hz, 16-bit stereo, is CD-quality and covers the complete human frequency spectrum. "Extreme" corresponds to 88200Hz, 24-bit stereo and is used in some audio mastering applications. Higher quality settings lead to larger file sizes and consume more disk space; "Low" is recommended for most uses. Inputs are case-insensitive. Default: 'low' 'threshold' Numeric scalar in the range [0,1]. The amplitude threshold used to measure RTs and to trigger code continuation (if specified by trigger_next parameter). RTs are measured as the time from onset to the time at which this amplitude of audio is detected. Default: 0.5 'latency_class' Integer in the range [0, 4] Specifies how aggressive PsychPortAudio should be about minimizing sound latency and getting good deterministic timing. Level 0 means: Don't care about latency, this mode works always and with all settings, plays nicely with other sound applications. Level 1 means: Try to get the lowest latency that is possible under the constraint of reliable playback, freedom of choice for all parameters and interoperability with other applications. Level 2 means: Take full control over the audio device, even if this causes other sound applications to fail or shutdown. Level 3 means: As level 2, but request the most aggressive settings for the given device. Level 4: Same as 3, but fail if device can't meet the strictest requirements. Default: 3 'export_audio' Boolean or String. If set to true, raw audio from each trial will be saved to the disk as a WAVE file. The files will be stored in a directory sharing the same name as this datastruct but with '_audio' appended. Alternatively, this parameter can be supplied as one of the following strings: {'wav', 'oga', 'ogg', 'flac'} (all systems), or {'m4a', 'mp4'} (Windows and Mac). Supplied strings are case-insensitive. Default: false 'groupscore_audio' Boolean. If set to true, audio data are transferred to groupstructs during scoring. In general, this is not necessary or desirable, as it will greatly increase the size of your aggregate dataset, and scoring is typically done on individual participant audio data before groupScore is called. Default: false '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 default_cresp as a cell array of strings (with NaN as a valid element as well). Default: {} 'default_respmap' Table mapping strings to numeric values and labels. Defines the semantic and numerical "meaning" of a set of anticipated vocal responses. On trials where no trial-specific respmap is provided, this one will be used instead. Although auditory easyVoice responses cannot be matched to text inputs (at least not without future-tech text recognition that we don't have at our disposal), this respmap is also displayed by easyCode, and may facilitate manual response scoring. Use makeMap to generate this map. Default: [] 'stimmap' Cell array mapping stimuli to numeric values. When calling easyVoice, 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, easyVoice 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: {} 'condmap' Cell array mapping conditions to numeric values When calling easyVoice, 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: {} 'trigger_next' Boolean or cell array of strings. By default, trigger_next is set to 'true' and easyVoice will return once the audio amplitude specified in 'threshold' is reached. Alternatively, if you set trigger_next to a cell array with strings naming keys, code execution will carry on as soon as a keypress response is detected on any of the keys (e.g., {'a','2','Space'}). In this way, you can trigger events with a keypress or vocal response. 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 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_key' Numeric integer, string, or cell array of strings. If you have specified a keypress trigger, device_key is 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 'device_audio' Numeric integer, string, or cell array of strings. The device from which audio data will be sampled. The device that will be monitoted 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 audio device selected from those available '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 easyVoice is called in order to make sure the latest data is available in case of a crash. Note that if there is a large amount of audio recorded or your audio settings are set to a high resolution, setting this option to true may introduce an undesirable delay while the audio is written to disk on every trial. 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 the easyVoice visual components will reside. This pointer is needed in order to support, e.g., ISI and/or feedback presentation. Default: 0 'isi' Boolean. 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 '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 easyVoice. If you prefer to have the break right before the n+1 call to easyVoice, 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. 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 easyVoice 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, although warnings will be printed to the console. Therefore, this parameter can also help catch bugs in your experimental logic. Default: nan '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", 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: {} '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: {} '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 as specified above.