Response handler element objects

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.—all documented below. Response handlers can only record responses when they are running, so you can control when a subject can respond by that.

Response values

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 below.

Prompt and feedback

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. Use properties start/end fields response/responseBy and and. See demo in <><PsychBench folder><>/docs/demos, and some quick examples:

translateResponse

Default: don't translate response values

You can tell the response handler to translate “raw” response values into other values that are more meaningful in the experiment. It will then record and use translated values for all purposes, including scoring (below).

Translated response values can be any data type and size. If all raw values and 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 checks 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.

Custom translation

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 reference a 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.

scoreResponse
correctResponse
scoreResponseForStaircase

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

If scoreResponse = <cd>true<cd> then for each response, the response handler records <cd>true<cd>/<cd>false<cd> in record property responseScore by comparing response and correct response using MATLAB isequaln (basically checks if they are the same regardless of data type).

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.

Custom scoring

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 reference 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.

maxNumResponses

Default: maximum 1 response

Most response handlers can record more than one response. If so, maxNumResponses is number of responses limit. Usually a response handler ends on its own then, but see element type documentation for more information. <cd>inf<cd> = no limit.

Note: for a time limit, just set the response handler to end at duration using property end field duration.

recordDefaultResponse

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.

registerTrigger

Default: record inputs as responses, not triggers

<cd>true<cd>/<cd>false<cd>: register inputs as triggers instead of responses from subject. In PsychBench a trigger is a "flag" an element raises that you can set timing from. Most commonly also set syncExperiment = <cd>true<cd> to tell the element to synchronize the experiment at trigger. You can then set the timing of any element in the trial (element property start/end field t_sync) and/or subsequent trial timing (trial object property start field t_sync‍) from sync. A common example is using keyPress elements to receive synchronization signals from a scanner that arrive as keyboard inputs.

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. The element then records inputs in record properties trigger, triggerTime, ... instead of response, responseTime, ... below.

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.

autoResponse
autoResponseLatency

Defaults: generate response(s) = 1 immediately when the response handler runs in auto response mode

If you input flag <cds>"-a"<cds> to runExperiment, the experiment runs in auto response mode to simulate a subject. All response handler elements then generate responses automatically, so you can just leave the experiment to run and come back later to check the complete results. By default response value = 1 and response is immediate when the response handler runs (or if you set maxNumResponses above for multiple responses then responses = 1 in rapid succession when it runs). For any response handler you can change this here:

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:

• number
  → response values = the number
• row vector
  → response values = numbers randomly sampled from the vector
• matrix
  → response values = row vectors randomly sampled from the matrix
• string or string array (<cds>"<cds> or <cds>'<cds>)
  → response values = strings randomly sampled from the array
• cell array
  → response values = values randomly sampled from cell contents
• anything else
  → response values = members randomly sampled from the array

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>.

response
responseScore
responseTime
responseLatency
d_responseTime
numResponses

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).