Race Models

Niek Stevenson

Introduction

This vignette shows a single-subject race-model workflow in EMC2 using the Linear Ballistic Accumulator (LBA). In EMC2, the Racing Diffusion Model (RDM) and Lognormal Race Model (LNR) are also race models and use a similar design logic. Here we use a simulated Stroop task to illustrate how to set this up.

The steps are:

1. Specify a race-model design with multiple responses and stimulus identities
2. Inspect sampled parameters and their mapping to design cells
3. Simulate data
4. Define priors and create an emc object
5. Fit the model
6. Summarize posterior estimates and run posterior predictive checks

For parameter details and transformations, see ?LBA.

1. Specify a Race-Model Design

We define a three-choice Stroop task with stimulus identity S (red, green, blue) and matching response levels. In race models, EMC2 internally builds an accumulator factor lR (one accumulator per response option). We define matchfun to indicate whether the stimulus identity matches each accumulator, which creates the latent match factor lM. By adding S to the drift rate we account for differences in color processing. Similarly, by adding B ~ LR we account for a-priori preferences for responding certain colors.

matchfun <- function(d) d$S == d$lR

# "Average/difference" coding for the TRUE/FALSE lM factor
ADmat <- matrix(c(-1/2, 1/2), ncol = 1, dimnames = list(NULL, "d"))

design_lba <- design(
  factors = list(subjects = 1, S = c("red", "green", "blue")),
  Rlevels = c("red", "green", "blue"),
  matchfun = matchfun,
  formula = list(v ~ lM + S, B ~ lR, A ~ 1, t0 ~ 1, sv ~ 1),
  contrasts = list(v = list(lM = ADmat)),
  constants = c(sv = log(1)),
  model = LBA
)

## 
##  Sampled Parameters: 
## [1] "v"         "v_lMd"     "v_Sgreen"  "v_Sblue"   "B"         "B_lRgreen"
## [7] "B_lRblue"  "A"         "t0"       
## 
##  Design Matrices: 
## $v
##     lM     S v v_lMd v_Sgreen v_Sblue
##   TRUE   red 1   0.5        0       0
##  FALSE   red 1  -0.5        0       0
##  FALSE green 1  -0.5        1       0
##   TRUE green 1   0.5        1       0
##  FALSE  blue 1  -0.5        0       1
##   TRUE  blue 1   0.5        0       1
## 
## $B
##     lR B B_lRgreen B_lRblue
##    red 1         0        0
##  green 1         1        0
##   blue 1         0        1
## 
## $A
##  A
##  1
## 
## $t0
##  t0
##   1
## 
## $sv
##  sv
##   1

design() combines model and experimental structure into an emc.design object.

2. Inspect Parameters and Mapping

sampled_pars() returns the free parameters implied by the design.

sampled_pars(design_lba)

##         v     v_lMd  v_Sgreen   v_Sblue         B B_lRgreen  B_lRblue         A 
##         0         0         0         0         0         0         0         0 
##        t0 
##         0

mapped_pars() shows how those parameters map back to design cells. Here:

• v_lMd captures match-vs-mismatch drift differences
• v_Sgreen and v_Sblue capture stimulus-identity shifts in drift
• B_lRgreen and B_lRblue capture response-specific threshold bias

mapped_pars(design_lba)

## $v 
##   lM     S      
##  TRUE   red    : v + 0.5 * v_lMd
##  FALSE  red    : v - 0.5 * v_lMd
##  FALSE  green  : v - 0.5 * v_lMd + v_Sgreen
##  TRUE   green  : v + 0.5 * v_lMd + v_Sgreen
##  FALSE  blue   : v - 0.5 * v_lMd + v_Sblue
##  TRUE   blue   : v + 0.5 * v_lMd + v_Sblue
## 
## $B 
##   lR     
##  red    : exp(B)
##  green  : exp(B + B_lRgreen)
##  blue   : exp(B + B_lRblue)

In this example we simulate data, but you can replace this with your empirical data. We first define true parameter values on the transformed scale and inspect the numeric mapping:

p_vector <- sampled_pars(design_lba)
p_vector[] <- c(
  v = 1.4,
  v_lMd = 1.8,
  v_Sgreen = 0.15,
  v_Sblue = -0.1,
  B = log(0.7),
  B_lRgreen = 0.1,
  B_lRblue = -0.1,
  A = log(0.3),
  t0 = log(0.25)
)

mapped_pars(design_lba, p_vector)

##       S    lR    lM    v sv     B   A   t0     b
## 1   red   red  TRUE 2.30  1 0.700 0.3 0.25 1.000
## 2   red green FALSE 0.50  1 0.774 0.3 0.25 1.074
## 3   red  blue FALSE 0.50  1 0.633 0.3 0.25 0.933
## 4 green   red FALSE 0.65  1 0.700 0.3 0.25 1.000
## 5 green green  TRUE 2.45  1 0.774 0.3 0.25 1.074
## 6 green  blue FALSE 0.65  1 0.633 0.3 0.25 0.933
## 7  blue   red FALSE 0.40  1 0.700 0.3 0.25 1.000
## 8  blue green FALSE 0.40  1 0.774 0.3 0.25 1.074
## 9  blue  blue  TRUE 2.20  1 0.633 0.3 0.25 0.933

To visualize the implied design-level behavior:

plot_design(design_lba, p_vector = p_vector, factors = list(v = "S", B = "lR"), plot_factor = "lR", layout = c(1,3))

3. Simulate Data

make_data() simulates trial-level responses and response times from the specified design and parameter values.

dat <- make_data(parameters = p_vector, design = design_lba, n_trials = 80)

A quick check of the simulated defective densities by stimulus identity:

plot_density(dat, factors = "S", layout = c(1,3))

4. Set Prior and Build EMC Object

prior() defines prior settings for parameters in this design. As always, be mindful that some parameters are represented on transformed scales, see ?LBA.

prior_lba <- prior(
  design = design_lba,
  type = "single",
  pmean = c(
    v = 1.2,
    v_lMd = 1.5,
    v_Sgreen = 0,
    v_Sblue = 0,
    B = log(0.8),
    B_lRgreen = 0,
    B_lRblue = 0,
    A = log(0.25),
    t0 = log(0.2)
  ),
  psd = c(
    v = .5,
    v_lMd = .6,
    v_Sgreen = .4,
    v_Sblue = .4,
    B = .25,
    B_lRgreen = .25,
    B_lRblue = .25,
    A = .25,
    t0 = .15
  )
)

Inspecting implied priors is a useful sanity check:

plot(prior_lba, N = 1e3)

Next we construct the emc object. make_emc() combines data, design, and prior into the object expected by fit().

emc <- make_emc(dat, design_lba, prior_list = prior_lba, type = "single")

## Processing data set 1

## Likelihood speedup factor: 2 (122 unique trials)

5. Fit

The following call is how you can fit this model and save intermediate output:

emc <- fit(emc, fileName = "data/race-models.RData")

6. Summarize and Check Model Fit

summary() reports quantiles, Rhat, and ESS for estimated parameters:

summary(emc)

## 
##  alpha 1 
##             2.5%    50%  97.5%  Rhat  ESS
## v          0.971  1.423  1.850 1.000 2841
## v_lMd      1.622  1.908  2.199 1.000 3000
## v_Sgreen  -0.155  0.159  0.465 1.001 2722
## v_Sblue   -0.432 -0.101  0.197 1.001 2991
## B         -0.592 -0.270  0.007 1.000 2912
## B_lRgreen -0.053  0.071  0.201 1.001 2974
## B_lRblue  -0.206 -0.068  0.060 1.001 2816
## A         -1.897 -1.405 -0.937 1.000 2807
## t0        -1.699 -1.488 -1.320 1.000 3000

plot_pars() compares posterior densities with the generating values:

plot_pars(emc, true_pars = p_vector, use_prior_lim = FALSE)

Finally, we generate posterior predictive datasets and compare CDFs:

pp <- predict(emc)

plot_cdf(dat, pp, factors = "S", layout = c(1,3))

This same race-model workflow extends naturally to the other race models RDM and LNR; the core steps (design() -> prior() -> make_emc() -> fit() -> predictive checks) remain the same.