datastruct = easyKeys(datastruct [,'onset'] [,'respmap'] [,'stim'] [,'cond'] [,'cresp'] [,'prompt_dur'] [,'nesting'] [,'next_window'] [,'info'] [,'simulated_key'] [,'draw_func_args'] [,'trial_summary_func_args']) [] = optional parameters '' = parameter-value pairs
EASYKEYS is intended as a quick way to gather and organize keypress response data. Each call to the function is a 'trial' in which more data are collected. It builds and logs a structure prepared by initEasyKeys that can be easily saved and later analyzed in matlab, and which contains much of the important information you would normally hope to collect upon prompting for a response. It also attempts to reduce the burden of gathering a response by assuming the format of your test question will remain the same across instances: most parameters are set once using initEasyKeys and can then be forgotten. The function saves all of its information after each response and is logged (to both a matlab and text file) in case disaster strikes in your matlab session. It can also optionally report helpful output to the console so you can see how your participant is doing. If you did not set a default cresp when initializing the datastruct, then this function is going to insist that you provide a trial-wise cresp here.
D = EASYKEYS(S) returns a datastruct using EASYKEYS default values. S is a test-specific data structure prepared by running initEasyKeys to specify test-related parameters like valid keys, maximum time duration, etc. D = EASYKEYS(datastruct,param1,val1,param2,val2...) sets various optional parameters. Parameters are case-insensitive, and each string parameter must be followed by a value as indicated: 'onset' Numeric Scalar. Start time of the trial. It is often best to use the time returned by, e.g., your draw command than the onset of this function for more accurate measurement. However, if you leave this field empty, the duration will begin from the time this function is launched. This may be optimal if you choose to use the draw_func_args parameter (see below). Default: output of GetSecs or Flip command 'respmap' Table mapping keys to numeric values. Defines the semantic and numerical "meaning" of each key specified in 'keys'. Use makeMap to generate this map. This could be 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. If you do not specify a respmap, keys will be described by their names and numerical values will reflect their position in "keys". If you did not provide a default_respmap during initialization, you will be required to enter one here. 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: empty table 'stim' String. A string describing the stimulus presented in this trial. Specify here to store the information in your datastruct and enhance console and text-file data-logging. If omitted or repeated, a generated string containing repeat count will be used in its place. stim is used as a row name for the trial table. Default: '---' 'cond' Scalar positive integer, NaN, string, or string cell array. Specifies the condition to which the current trial belongs. If omitted, left empty, or set to NaN, condition -1 will be recorded. It can be specified either by a positive integer, NaN, or by string name. If a condmap was specified in initEasyKeys, a corresponding condition string will be reported. When there are multiple condition factors, can be supplied as a numeric array or cell array of strings where each entry corresponds to a different condition factor; in this case, there must be an equal number of condmap entries supplied to initEasyKeys, and each entry of cond must be the same type. As a shortcut with multiple condition factors, cond can be supplied as a single string (conditions delimited by underscores) which will be compared to row names of the master condmap to determine which conditions to assign for each factor. If no condition in a condmap matches the string, the condition will be appended to the condmap. Default: -1 '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 (unless you specified a default_cresp with initEasyKeys). 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: {} 'prompt_dur' Numeric positive scalar. The maximum period, specified in seconds, for which you would like to present participants with the initial promptscreen while waiting for a response. Specify a duration of 0 to sample for a current keypress and then exit. If you did not provide a default prompt_dur during initialization, you will be required to enter one here. Default: [] 'nesting' Numeric vector of positive integers. Used to specify the nested structure of trials in an experiment. Hierarchy is represented in descending order from left to right, e.g., block 2, subblock 1, trial 4 would be represented as [2 1 4]. This information will be retained in the datastruct trials table, and is also used to create depth-specific summaries in easyScore. The supplied vector can be of any length, but the nesting vector must be of consistent length across all trials of an experiment. If the nesting structure has more than one layer (i.e. more than one element in the nesting vector), this parameter must be explicitly supplied for each trial in the experiment. If a single-element nesting vector is supplied to the first trial, this parameter does not need to be supplied with each call, and will be instead incremented by one automatically from the previous trial nesting value. Default: [trial] 'next_window' Window pointer. If a pre-drawn psychtoolbox window is supplied to the function, then easyKeys will present it immediately after the specified prompt/trial duration has elapsed. If a listen_dur was specified in initEasyKeys, then easyKeys will continue to listen for responses during that interval (while this next_window is on the screen) before exiting, and a pre-drawn window will be a required argument. Default: [] 'simulated_key' Char or NaN. A key entered using this parameter is treated as a keypress submitted immediately upon calling easyKeys. This could be useful for testing your experiment code, recording a response at a different time than it is collected, or logging things that are happening in your experiment that do not involve a user response. Default: [] 'draw_func_args' Cell array. If you would like easyKeys to draw options for you, set this parameter. You must have provided a parent window and drawing style to initEasyKeys using draw_func. This optional parameter is not needed for drawing, but can be used to control the display. When using the default draw_func drawSPTBchoices, parameter control is as follows: Params are one or more elements of a cell array, each of which can be left empty for defaults. Position (1) can contain a text label to be printed above your choices. Position (2) can contain a "drawing" respmap if the one supplied to control easyKeys is not suitable. For images, a complete filepath should be provided as each "descriptor" to the respmap (image data can also be supplied directly). For text, the complete string to be displayed should be provided as each "descriptor". The "input" char or string for each option is inscribed in a black circle near the stimulus. Position (3) of the array can control the grid display size with [rows cols]. Note that if no "onset" parameter is specified at runtime (see above), an onset value from the "flip" command generated by draw_func is used instead. 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: {} 'info' Any data type. Populate this field with any kind of meta-data about the trial. It will be associated with that trial and remain available for later reference in the datastruct. Unlike simulated_key, it will not be processed using a "key" framework (e.g., checked against valid keys, evaluated for accuracy, etc). Default: {}
datastruct: a data structure containing the various parameters that were provided to the initEasyKeys initialization function, as well as response data from each call to easyKeys. Fields corresponding to absent optional parameters are set to default values.