All adjuster elements

In a method of adjustment experiment the subject adjusts one or more stimulus parameters in real time, typically until at their threshold for the task.

Target element + Adjuster element

An adjustment experiment is the interaction of target elements and adjuster elements. Any adjuster element can adjust any target element(s)—this modular approach allows a lot of flexibility.

1. Target element

You can allow the subject to adjust one or more numeric properties of an element when it is running. You can only allow the subject to adjust properties that are adjustable. Which properties are adjustable depends on the element type—see its documentation (or just try it and PsychBench will tell you). However, if you need to make other properties adjustable you can copy the element type and edit the copy (Element Type Programming Manual).

Initial value for an adjusted property is just the value you set for the property when you build the experiment (or its default value if you don't set one).

2. Adjuster element

You need a separate adjuster element to run at the same time. The adjuster receives input from the subject and adjusts the target element based on it. There are various adjuster element types, each allowing a different method, e.g. key press, mouse click & drag, etc. Adjustments are always numeric (not necessarily scalar). Often there are type-specific adjuster properties where you specify how input translates to adjustments (e.g. Left key → +10), and you can assign different inputs to adjustments in different directions and/or magnitudes. All adjuster elements have property adjust where you specify the target(s) it adjusts and other options for how it applies adjustments—see below.

Response (done adjusting) and experiment results output

All adjusters are also response handlers and have the properties and functionality all response handlers have. Generally the subject makes many adjustments (e.g. with arrow keys), then inputs that they are done adjusting (e.g. with the Space key). The “done adjusting” input is the response, not the adjustments. The value recorded in the adjuster’s record property response is the adjusted property value(s) of target element(s) running at the time. If you set an adjuster to record multiple responses, it just means the subject makes adjustments, responds done, makes more adjustments, responds done again, etc.—each response adds to the record as usual.

Input properties all adjuster elements have

adjust

Default: adjuster doesn't adjust any elements

Use this property to specify which other element and property to apply adjustments to, and further options. adjust is a struct that can have the following fields. Omit fields (or leave them = <cd>[]<cd>) to leave them at default. In unusual cases to adjust multiple elements and/or properties, make adjust a struct array, e.g. <cd>adjust(1).target = <cd> ..., <cd>adjust(2).target = <cd>....

Note you will get an error during the experiment if the subject adjusts a property to a value that is impossible for it (e.g. a negative value for a property that must be positive). You need to set the adjuster parameters so this can’t happen.

.target

A string pointing to another element object and input property. Specify the element by variable name and possibly index you use in the experiment script, and the property using dot notation. Or you can adjust part of a property by including index in the expression. Target must be numeric (not necessarily scalar). e.g.

<cdsm>"picture.size"<cdsm>
<cdsm>"pictures(2).size"<cdsm>
<cdsm>"pictures(1).size(2)"<cdsm>

If you want to adjust a visual element property that you set in units other than deg using <cd>{val, <cd><cds>"unit"<cds><cd>}<cd> form, target the numeric value in <cd>{1}<cd>.

Tip: If you have an index in a numeric variable you can use it in an <cdsm>"x"<cdsm> string (but not an <cdsm>'x'<cdsm> string) like this:

<cdsm>"pictures("<cdsm><cdm> + n + <cdm><cdsm>").size"<cdsm>

.setExpr

Default: set target = current value + adjustment

You can set setExpr to a string that is any MATLAB expression for PsychBench to evaluate to set the target. The expression must use variables val and delta which will contain current target value and adjustment. val and delta are always numeric (not necessarily scalar).

e.g.
Target must be an integer (and adjustments might not be)
→ <cdsm>"round(val+delta)"<cdsm>

If you need multiple lines of code, the string can be the name of a script that makes a variable ans containing value to set.

min
max

Default: no minimum/maximum target value

You can use these fields to set minimum and/or maximum target values which the subject cannot adjust past. Size of min/max must be single numbers or = size of target.

Example

This would make a trial where the subject is able to adjust number of dots in a linearDotMask element. Initial value = 500. Minimum value = 0. Adjustments are made by key press with a keyAdjuster element: Left = −10, Right = +10. Space = record a response (key numbers are for Windows—see Psychtoolbox KbShow). Both elements end when the adjuster records a response (done adjusting).

mask = linearDotMaskObject;
mask.numDots = 500;
mask.start.t = 0;
mask.end.response = true;
mask.report = <cdsm>"numDots"<cdsm>;

adjuster = keyAdjusterObject;
adjuster.deltas = {
    37 -10
    39 +10
    44 <cdsm>"r"<cdsm>
    };
adjuster.adjust.target = <cdsm>"mask.numDots"<cdsm>;
adjuster.adjust.min = 0;
adjuster.start.t = 0;
<cdcm>% By default keyAdjuster ends on its own when it records a response<cdcm>

addTrial(mask, adjuster);

Input properties all objects have

report
info

Record properties all adjuster 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.