[acc, resp, resp_input_vec, rt, accString, respString, respKey, rtString, exit_code] = multiChoice(duration, keys [,respmap] [,cresp] [,onset] [,inputDevice] [,simulated_key]) [] = optional parameters
This function will collect a response in a test-like way: wait for a little while, then return some info about the response it got, if any. Notes about behavior: the function can be told to wait for up to a certain duration to get a response, or to check the keyboard once and exit. In both cases, it will clear the key buffer before sampling. If you ask it to wait for a response (by setting duration to longer than zero), it will wait until all keys are unpressed before sampling (up to the duration) to help prevent residual keypresses to prior events from spilling over into new events. Also, it will consider only single key presses - if you somehow press all the keys simultaneously, you will not get a correct answer, even if the correct answer is among the keys you are mashing.
duration: the maximum period, specified in seconds, for which you would like to wait for a response. Specify a duration of 0 to sample for a current keypress and then exit. keys: keys that will count as responses. Only these keys will exit the function. You should specify the allowed keys as a cell array (e.g., {'a','2','Space'}). Note that multiChoice is not case sensitive, but will nonetheless detect keys that would otherwise require a modifier (e.g., 'h' will match 'H', '4' will match '$') as well as special keys such as 'Return', 'Space' and 'LeftControl'. respmap (optional): 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". cresp (optional): the key or keys that should be treated as being correct responses (NOT their respmap value). If there is no one correct answer, don't specify this variable or leave it empty, and all responses will be treated as correct. Or, if a null response is correct, specify nan. If there is more than one correct key, specify cresp as a cell array. onset (optional): when did the trial begin? It is better 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. inputDevice (optional): the device that KbCheck will poll for responses. If you don't know what this is, or you just want to sample from the keyboard, then skip this variable, leave it empty or specify "-1". If you want to limit response collection to a specific device (e.g., a response pad or an fMRI scanner), you will need to figure out the device ID.
accuracy: if the keypress outcome satisfied the conditions specified by 'cresp', this will contain a 1, or otherwise a 0. resp: if no key was pressed during the duration of multipleChoice, then nan will be returned. Otherwise, the respmap value of the first key pressed will be returned. resp_input_vec: a log of keypresses in the form of a 3xN table displaying key-down timestamps, key-up timestamps, and the character. rt: if no key was pressed during the duration of multipleChoice, then a nan will be returned. Otherwise, the period between onset and the keypress (expressed in ms). accString, respString, rtString: string versions of the above outputs, provided for your reporting convenience. Note that respString will contain the descriptor corresponding to the respmap code of the pressed key, and 'NR' will be returned for null responses. respKey: string version of resp (eg. 'c' rather than 3). For a null response, NaN is returned.