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. (To vary a stimulus on a fixed time-dependent course, use property vary instead of an adjuster.)

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 input 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 the top of the property list in its documentation. If you need to make other properties adjustable, you can edit the element type code—see 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 + input property to apply adjustments to, and further options. adjust is a struct that can have the following fields. You can omit fields (or leave them = <cd>[]<cd>) to leave them at default. In unusual cases to adjust multiple elements and/or properties, you can 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

No default

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. You can also let the subject adjust part of a property by including further indexes/field names. Target must be numeric (not necessarily scalar). e.g.

<cdsm>"mask.size"<cdsm>
<cdsm>"masks(2).size"<cdsm>
<cdsm>"masks(1).size(2)"<cdsm>

For a visual element property that you set in units other than deg using <cdm>{val, <cdm><cdsm>"unit"<cdsm><cdm>}<cdm> form, just target the numeric part of the property here, e.g. <cdsm>"pictures(2).height{1}"<cdsm>.

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 values which the subject cannot adjust past. min/max can be single numbers to apply to all numbers in target, or numeric arrays with size = size of target. If you target part of a property, min/max applies only to that part.

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 arrow = −10, right arrow = +10. space = record a response. 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 = {
    <cdsm>"left"<cdsm>  -10
    <cdsm>>"right"<cdsm> +10
    };
adjuster.responseKeyName = <cdsm>"space"<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);

Tutorial

See the adjustment tutorial in <PsychBench folder>/docs/tutorials.

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 by listing them input property report.