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')[source]¶
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 ofExperimentController
is given, then it will take that object’swrite_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
andstep_size_down
are lists. The length ofchange_indices
must be the same as the length ofstep_size_up
andstep_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.
- 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
andstep_size_down
must be scalars andchange_indices
must be None.- check_valid(n_reversals)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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 for two trial types and tracker reconstruction from .tab
Do an adaptive track staircase