Draw datasets from a learning family's generative process

Walks each subject forward through the design, drawing a choice from the current value store and learning from the payoff that choice earns. It is the same recursion the likelihood tapes, at mode = "simulate", so a draw and the density that scores it cannot drift apart.

Usage

frm_task_simulate(family, data, pars, nsim = 1L, response = NULL, seed = NULL)

Arguments

family

A family from this package, such as bandit2arm_delta().

data

A design from frm_task_design(), or any data frame with the same canonical columns.

pars

Named list of parameters on their NATURAL scales (a learning rate in (0, 1), not its logit). Each element is one value, recycled everywhere; or one value per subject, in the order levels(factor(data$id)) gives; or one value per ROW. The per-row form is what a covariate that varies WITHIN a subject needs, which is what a reversal is: see the example.

nsim

Datasets to draw.

response

Name of the column the drawn response goes into. NULL, the default, uses the family's own: choice for a family whose response is the option taken, rt for rlddm(), whose response is the response time and whose drawn choice is written beside it.

seed

Passed to set.seed() when not NULL.

Value

A list of nsim data frames, each data with the drawn columns replaced.

Details

This route takes parameters directly, per subject or per row, rather than through a formula and a random-effect covariance. That is what a recovery study wants, and it makes the simulator independent of the fitting machinery, so agreement between a fit and its truth is evidence about both. frmtmb::frm_simulate() is the other route and goes through the fitted grammar; the two agree by construction for every family except ts_par7(), which frmtmb::frm_simulate() refuses because one trial's draw is three numbers.

See also

frm_task_design(), frmtmb::frm_simulate()

Examples

d <- frm_task_design("bandit2arm", n_subject = 5, n_trial = 30,
                     seed = 1)
sims <- frm_task_simulate(bandit2arm_delta(subject = id, trial = trial),
                          d, pars = list(alpha = 0.4, tau = 3),
                          nsim = 2, seed = 1)
table(sims[[1]]$choice)
#> 
#>   1   2 
#> 105  45 

# a learning rate that changes within a subject, one value per row
r <- frm_task_design("reversal", n_subject = 5, n_trial = 30, seed = 2)
a <- ifelse(r$after_reversal == "after", 0.6, 0.2)
rs <- frm_task_simulate(bandit2arm_delta(subject = id, trial = trial),
                        r, pars = list(alpha = a, tau = 3), seed = 2)
table(rs[[1]]$choice)
#> 
#>  1  2 
#> 74 76