All response handler elements

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.

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 representing keys. It’s common to translate response values into values that are more meaningful in the experiment using property translateResponse.

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. See properties start/end fields response/responseBy and and but some basic examples:

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

Input properties all response handler elements have

translateResponse

Default: use raw response values

You can tell the response handler to translate “raw” response values like key numbers into values that are more meaningful in the experiment. It will then record and use translated values for all purposes, including scoring (below). <cd>[]<cd> = 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.

Example

element.translateResponse = [
    37  1
    39  2
    ]

→ translate raw response 37 → 1, 39 → 2. Leave any other responses 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 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.

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.

Example

element.scoreResponse   = true
element.correctResponse = 2

→ score response <cdm>true<cdm> if = 2, else <cdm>false<cdm>.

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

Example

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

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. <cd>[]<cd> = 1.

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. If = <cd>true<cd>, the element records inputs in record properties trigger, triggerTime, etc. instead of response. You can set elements in the same trial to start/end from either responses or triggers (element properties start/end). However, for triggers you can also set later trials to start at fixed times from trigger with zero drift (trial object property start). A common example is using keyPress elements to receive sync 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.

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

Input properties all objects have

report
info

Record properties all response handler elements have

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.

response
responseScore
responseTime
responseLatency
d_responseTime
numResponses

response is response value, e.g. a key number or translated value 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).