Tutorial 1d - changing_thresholds

In this tutorial, we introduce PyBEAM’s changing_thresholds model and its usage. If you have not done so already, follow the directions on the PyBEAM github to install pybeam. Then, import PyBEAM’s precoded submodule:

# import PyBEAM's precoded submodule
import pybeam.precoded as pbp

We will now call the precoded changing_thresholds model.

# call changing_thresholds model
model = pbp.changing_thresholds()

The changing_thresholds() model class calls the changing thresholds model. This is a two threshold EAM with constant non-decision time, constant relative start point, constant drift rate, and time varying decision thresholds. The default threshold is a Weibull function, giving the following default parameters:

'tnd': non-decision time
'w': relative start point
'mu': drift rate
'b': decision threshold location at time zero (upper is at b, lower is
     at -b; initial separation is 2b)
'lamb': log10 of Weibull scale parameter
'kappa': log10 Weibull shape parameter
'c': Weibull collapse parameter

The scale parameter, ‘lamb’, approximately indicates when/how early threshold collapse occurs. The shape parameter, ‘kappa’, indicates the threshold shape. Both of these are input as the log10 of the actual parameter (useful for sampling purposes). If below one, the threshold is exponential like; if above one, the threshold is logistic like. The collapse parameter, ‘c’, indicates how much the thresholds collapse. If c = -1, the thresholds collpase to zero; if c = 1, no collapse occurs; if c > 1, thresholds expand above b. The equation is

upper threshold = -lower threshold = b - 0.5*b*(1 - c)*(1 - exp(-(t/(10^lamb))^(10^kappa))))

If ever you are unsure what parameters a model uses, the following callout returns the model’s parameters:

# check which parameters your model uses
model.parameters()

['tnd', 'w', 'mu', 'b', 'lamb', 'kappa', 'c']

Five inputs can be provided as arguments to the changing_thresholds() class: sigma, contamination, thresholds, non_decision, and start. sigma allows the user to set the diffusion rate of the acccumulator. By default, sigma = 1.0. contamination indicates if a contamination model should be added to the model. By default, contamination = ‘none’, but it can also be contamination = ‘uniform’ if a uniform contamination distribution should be added.

non_decision and start allow the user to add across-trial variability to the non-decision time and relative start points. By default, non_decision = ‘constant’, but can also be ‘uniform’ or ‘normal’. ‘uniform’ adds a uniform non-decision distribution, while ‘normal’ adds a normal non-decision distribution (truncated at zero to avoid non-decision times below zero). By default, start = ‘constant’, but can also be ‘uniform’ or ‘normal’. ‘uniform’ adds a uniform relative start distribution, while ‘normal’ adds a normal relative start distribution (truncated near 0 and 1 to prevent probability mass leaving the thresholds). These are used as follows:

# call changing_thresholds with user set sigma, contamination,
# and across-trial variability
model = pbp.changing_thresholds(sigma = 1.0,
                      contamination = 'uniform',
                      non_decision = 'normal',
                      start = 'uniform')

# output model parameters
model.parameters()

['tnd',
 'w',
 'mu',
 'b',
 'lamb',
 'kappa',
 'c',
 'sd_tnd',
 'sd_w',
 'g',
 'gl',
 'gu']

Note that the model now has five additional parameters. These are:

'sd_tnd': standard deviation of non-decision time
          distribution (width of uniform distribution if
          non_decision = 'uniform').
'sd_w': width of relative start distribution (standard
        deviation of uniform distribution if
        start = 'normal').
'g': contamination strength (i.e. proportion of rt
     distribution due to contamination model)
'gl': lower bound of uniform contamination distribution
'gu': upper bound of uniform contamination distribution

The remaining optional input, thresholds, allows the user to change which changing thresholds they are using. The default is ‘weibull’, but other inputs include ‘linear’ and ‘exponential’. If ‘linear’ is chosen, linear thresholds are used, giving the following threshold parameter:

'm': slope of linear thresholds (positive give collapse, negative gives expansion. equation is
     upper threshold = -lower threshold = b - mt).

If ‘exponential’ is chosen, exponential thresholds are used, giving the following threshold parameter:

'tau': log10 of rate of exponential threshold collapse
(upper threshold = -lower threshold = b*exp(-t/ (10^tau) ) )

Note that, as for the Weibull model, we input tau as the log10 of the actual parameter.

We have now finished our introduction to the changing_thresholds model! Proceed to Tutorial 2 to learn how to use your PyBEAM model.