Tutorial 1e - UGM

In this tutorial, we introduce PyBEAM’s UGM (urgency gating model) 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 UGM (urgency gating model).

# call UGM model
model = pbp.UGM()

The UGM() model class calls the UGM model. This is a two threshold EAM with constant non-decision time, constant relative start point, and constant decision thresholds. The drift rate and diffusion rate change with the time and/or spatial coordinate. The default parameters for it are as follows:

'tnd': non-decision time
'w': relative start point
'mu': drift rate
'l': leakage rate
'k': urgency parameter
'b': decision threshold location (upper is at b, lower is
     at -b; separation is 2b)

The drift rate is:

drift = mu*(1.0 + k*t) - (l - k/(1.0 + k*t) )*x

where x is the spatial coordinate and t is the time coordinate.

The diffusion rate is:

diffusion = sigma*(1.0 + k*t)

where sigma is the scale parameter (discussed below) and t is the time coordinate.

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', 'l', 'k', 'b']

Four inputs can be provided as arguments to the UGM() class: sigma, contamination, non_decision, and start. sigma allows the user to set the scale parameter 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 UGM with user set sigma, contamination,
# and across-trial variability
model = pbp.UGM(sigma = 1.0,
                contamination = 'uniform',
                non_decision = 'normal',
                start = 'uniform')

# output model parameters
model.parameters()

['tnd', 'w', 'mu', 'l', 'k', 'b', '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

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