expyfun.stimuli.TrackerUD

class expyfun.stimuli.TrackerUD(callback, up, down, step_size_up, step_size_down, stop_reversals, stop_trials, start_value, change_indices=None, change_rule='reversals', x_min=None, x_max=None, repeat_limit='reversals')

Up-down adaptive tracker

This class implements a standard up-down adaptive tracker object. Based on how it is configured, it can be used to run a fixed-step m-down n-up tracker (staircase), or it can implement a weighted up-down procedure.

Parameters:

callbackcallable | ExperimentController | None

The function that will be used to print the data, usually to the experiment .tab file. It should follow the prototype of ExperimentController.write_data_line. If an instance of ExperimentController is given, then it will take that object’s write_data_line function. If None is given, then it will not write the data anywhere.

upint

The number of wrong answers necessary to move the tracker level up.

downint

The number of correct answers necessary to move the tracker level down.

step_size_upfloat | list of float

The size of the step when the tracker moves up. If float it will stay the same. If list of float then it will change when change_indices are encountered. See note below for more specific information on dynamic tracker parameters specified with a list.

step_size_downfloat | list of float

The size of the step when the tracker moves down. If float it will stay the same. If list of float then it will change when change_indices are encountered. See note below for more specific information on dynamic tracker parameters specified with a list.

stop_reversalsint | np.inf

The minimum number of reversals before the tracker stops. If stop_trials is also specified, the tracker will stop when either condition is satisfied.

stop_trialsint | np.inf

The minimum number of trials before the tracker stops. If stop_reversals is also specified, the tracker will stop when either condition is satisfied. Only use np.inf if you are sure that the tracker will reach the reversal stopping criteria without getting stuck on either x_min or x_max.

start_valuefloat

The starting level of the tracker.

change_indiceslist of int | None

The points along the tracker to change its step sizes. Has an effect where step_size_up and step_size_down are lists. The length of change_indices must be the same as the length of step_size_up and step_size_down minus 1. See note below for more specific usage information. Should be None if static step sizes are used.

change_rulestr

Whether to change parameters based on ‘trials’ or ‘reversals’.

x_minfloat

The minimum value that the tracker level (x) is allowed to take.

x_maxfloat

The maximum value that the tracker level (x) is allowed to take.

repeat_limitstr

How to treat trials that try to exceed either x_min or x_max. reversals will consider these trials as reversals while staying at the same level. ignore does not consider these trials as reversals.

Attributes:

down

n_reversals

The number of reversals so far

n_trials

The number of trials so far

repeat_limit

responses

The response history

reversal_inds

The trial indices which had reversals

reversals

The reversal history (0 where there was no reversal)

start_value

step_size_down

step_size_up

stop_reversals

stop_trials

stopped

Has the tracker stopped

up

x

The staircase

x_current

The current level

x_max

x_min

Methods

check_valid(n_reversals)	If last reversals contain reversals exceeding x_min or x_max.
plot([ax, threshold, n_skip])	Plot the adaptive track.
plot_thresh([n_skip, ax])	Plot a line showing the threshold.
respond(correct)	Update the tracker based on the last response.
threshold([n_skip])	Compute the track's threshold.

Returns:

trackerinstance of TrackerUD

The up-down tracker object.

Notes

It is common to use dynamic parameters in an adaptive tracker. For example: the step size is often large for the first couple reversals to get in the right general area, and then it is reduced for the remainder of the track. This class allows that functionality by defining that parameter with a list of values rather than a scalar. The parameter will change to the next value in the list whenever a change criterion (number of trials or reversals) is encountered. This means that the length of the list defining a dynamic parameter must always be the 1 longer than that of change_indices. For the example given above:

..., step_size_up=[1., 0.2], step_size_down=[1., 0.2], \
change_indices=[2], change_rule='reversals', ...

would change the step sizes from 1 to 0.2 after two reversals.

If static step sizes are used, both step_size_up and step_size_down must be scalars and change_indices must be None.

check_valid(n_reversals)

If last reversals contain reversals exceeding x_min or x_max.

Parameters:

n_reversalsint

Number of reversals (starting from the end to check).

Returns:

validbool

True if none of the reversals are at x_min or x_max and False otherwise.

property n_reversals

The number of reversals so far

property n_trials

The number of trials so far

plot(ax=None, threshold=True, n_skip=2)

Plot the adaptive track.

Parameters:

axAxesSubplot | None

The axes to make the plot on. If None defaults to current axes.

thresholdbool

Whether to plot the estimated threshold on the axes. Default is True.

n_skipint

See documentation for TrackerUD.threshold.

Returns:

figFigure

The figure handle.

axAxesSubplot

The axes handle.

lineslist of Line2D

The handles to the staircase line and the reversal dots.

plot_thresh(n_skip=2, ax=None)

Plot a line showing the threshold.

Parameters:

n_skipint

See documentation for TrackerUD.threshold.

axAxes

The handle to the axes object. If None, the current axes will be used.

Returns:

linelist Line2D

The handle to the threshold line, as returned from plt.plot.

respond(correct)

Update the tracker based on the last response.

Parameters:

correctboolean

Was the most recent subject response correct?

property responses

The response history

property reversal_inds

The trial indices which had reversals

property reversals

The reversal history (0 where there was no reversal)

property stopped

Has the tracker stopped

threshold(n_skip=2)

Compute the track’s threshold.

Parameters:

n_skipint

The number of reversals to skip at the beginning when computing the threshold.

Returns:

thresholdfloat

The handle to the threshold line.

Notes

The threshold is computed as the average of the up reversals and the average of the down reversals. In this way if there’s an unequal number of them the asymmetry won’t bias the threshold estimate.

This can also be used before the track is stopped if the experimenter wishes.

property x

The staircase

property x_current

The current level

Examples using expyfun.stimuli.TrackerUD

Adaptive tracking from above and below

Adaptive tracking from above and below

Adaptive tracking for two trial types and tracker reconstruction from .tab

Adaptive tracking for two trial types and tracker reconstruction from .tab

Do an adaptive track staircase

Do an adaptive track staircase