Elements that receive and record responses from the subject are called response handlers. There are various response handler element types. Each allows response by a different method, e.g. key press, mouse click, button box press, etc. Additionally, there are some options that all response handler elements have, based on input properties below—e.g. translating responses, scoring responses, etc. Response handlers can only record responses when they are running, so you can control when a subject can respond by that.
A response handler records each response as a value in record property response. What response values can be depends on the element type. For example, keyPress elements record response values that are numbers corresponding to keys pressed. You can also translate response values into other values that are more meaningful in the experiment using property translateResponse.
For a prompt for response, set another element to run at the same time as the response handler. For feedback, set other elements to start from response, possibly depending on response score. See properties start/end fields response/responseBy and and but some basic examples:
element.start.response = true
→ feedback at any response
element.start.response = true
element.start.and = <cdsm>"responseScore = true"<cdsm>
→ feedback at any response scored true
element.start.response = true
element.start.and = <cdsm>"responseScore = false"<cdsm>
→ feedback at any response scored false
See the response tutorial in <PsychBench folder>/docs/tutorials.
Default: use raw response values
Translated response values can be any data type and size. If all raw values and all translated values are numbers, you can use a 2-column matrix with raw values in column 1 and values to translate to in column 2. Otherwise you can use a 2-column cell array and the response handler will match raw values it receives to values in column 1 using MATLAB isequaln (basically if they are the same regardless of data type). If you don’t set a translation for a given raw value, it will stay unchanged.
element.translateResponse = [
→ translate raw response 37 → 1, 39 → 2. Leave any other responses unchanged.
If you need more flexibility, you can set translateResponse to a string that is any MATLAB expression for PsychBench to evaluate during the experiment to return translated response values. The expression can use the variable response, which will be the raw response value. If you need multiple lines of code, the string can be the name of a script that makes a variable ans containing the translated value.
Default: scoreResponse = don't score response
Default: correctResponse = <cd><cd>
Default: scoreResponseForStaircase = <cd>false<cd> but automatic if only one response handler scores a response in the trial
correctResponse: If scoreResponse = <cd>true<cd>, set the correct response value here. Note if you use translateResponse above, correct response is in translated terms.
scoreResponseForStaircase: If an element in the trial is staircased, the staircase object needs to get whether response was correct. It does this automatically from any response handler in the trial that scores a response <cd>true<cd>/<cd>false<cd>. In the common case that there is only one, you can leave scoreResponseForStaircase at default. Otherwise set scoreResponseForStaircase = <cd>true<cd> for one or more of them to mark which one(s) the staircase looks to.
element.scoreResponse = true
element.correctResponse = 2
→ score response <cdm>true<cdm> if = 2, else <cdm>false<cdm>.
If you need more flexibility, you can set scoreResponse to a string that is any MATLAB expression for PsychBench to evaluate during the experiment to return response scores. The expression can use variables response and correctResponse. It can evaluate to anything (not just <cd>true<cd>/<cd>false<cd>). If you need multiple lines of code, the string can be the name of a script that makes a variable ans containing score.
element.scoreResponse = <cdsm>"ismember(response, correctResponse)"<cdsm>
element.correctResponse = [4 5 6]
→ score response <cdm>true<cdm> if = any of 4, 5, 6, else <cdm>false<cdm>.
Default: maximum 1 response
Note: for a time limit, just set the response handler to end at duration using property end field duration.
Default: don't record default response
<cd>true<cd>/<cd>false<cd>: generate a response = <cd>NaN<cd> if no response has been recorded by element end. This allows you to represent “no response” so you can apply the usual functionality to it, e.g. score “no response” as incorrect (scoreResponse above), start/end elements at no response (start/end fields response/responseBy), etc.
Default: record inputs as responses, not triggers
If you set registerTrigger = <cd>true<cd>, all other core response handler properties are ignored (response translation, scoring, default response). The exception is maxNumResponses, which becomes maximum number of triggers.
Note some elements that aren’t response handlers can register triggers too, e.g. portSender/Receiver elements. Only response handlers have this property to switch from responses to triggers, so you only need to set it for them.
Defaults: generate response(s) = 1 immediately when the response handler runs in auto-response mode
autoResponse is one or more possible response values to generate. Response values can be any data type and size. Note if you use translateResponse above, auto responses are raw responses generated before translation. Options:
autoResponseLatency is a number setting the latency for generated responses (sec). Or you can set a 1×2 vector <cd>[l1 l2]<cd> for a random latencies between <cd>l1<cd> and <cd>l2<cd>.
PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results by listing them input property report.
response is response value, either raw or translated using translateResponse above.
responseScore: If you turn on response scoring using scoreResponse above, score is recorded here.
responseTime is time the response was received relative to trial 1 start (sec).
responseLatency is response time relative to response handler start for first response, or to previous response for subsequent responses (sec). Basically this is response time from the earliest time the subject could have responded for that response.
d_responseTime is uncertainty in response time (sec). Range = ± d_responseTime. This is > 0 in the common case of a response handler that checks for response once per frame, giving uncertainty = 1/2 the interval between checks (≈ 8 msec at 60 frames/sec with no dropped frames). Otherwise this property reports 0, but note this doesn’t include other sources of uncertainty which may be present in your system. For more information on frames and timing precision see Timing precision.
If the response handler records multiple responses then these properties become row vectors or cell arrays.
It’s common to include some or all of these record properties in experiment results output (input property report).
numResponses is number of responses recorded. 0 = no response (unless you set recordDefaultResponse = <cd>true<cd>, in which case the default response will count as 1).