Package {lddmm}

lddmm: Longitudinal Drift-Diffusion Mixed Models (LDDMM)

Description

Implementation of the drift-diffusion mixed model for category learning as described in Paulon et al. (2021) doi:10.1080/01621459.2020.1801448.

Author(s)

Maintainer: Giorgio Paulon giorgiopaulon90@gmail.com

Authors:

• Giorgio Paulon giorgiopaulon90@gmail.com

• Abhra Sarkar abhra.sarkar@utexas.edu [contributor]

See Also

Useful links:

• https://github.com/giorgiopaulon/LDDMM

• Report bugs at https://github.com/giorgiopaulon/LDDMM/issues

Spline Basis Functions

Description

Quadratic B-spline basis on equally spaced knots (supplement §S.1), evaluated on a grid. Points outside ⁠[min(knots), max(knots)]⁠ get a row of zeros.

Usage

B_basis(xgrid, knots)

Arguments

Value

n x (K+1) matrix with the value of each basis function on xgrid. At a knot, exactly two adjacent basis functions are non-zero, both equal to 1/2.

Hamming Ball

Description

All label vectors within Hamming distance r of x (supplement §S.4).

Usage

H_ball(x, S, r)

Arguments

Value

Matrix with length(x) rows; each column is one member of the ball, starting with x itself and ordered by distance from x.

Drift Diffusion Model Fit

Description

Fits the longitudinal inverse Gaussian drift-diffusion mixed model of Paulon et al. (2021) by Markov chain Monte Carlo.

Usage

LDDMM(
  data,
  hypers = NULL,
  cluster = TRUE,
  boundaries = c("flexible", "constant", "fixed", "fixed-constant"),
  random_effects = c("correct-incorrect", "shared"),
  z_max = NULL,
  informed = TRUE,
  Niter = 5000,
  burnin = 2000,
  thin = 5,
  save_z = FALSE,
  save_loglik = TRUE,
  verbose = TRUE,
  debug_checks = FALSE
)

Arguments

Details

On trial \ell of block t, subject i hears input stimulus s and answers d. One accumulator per possible decision races to its boundary; the first to arrive determines the decision and the response time. The accumulator of decision d has drift \mu^{(i)}_{d,s}(t) = \exp\{f_{\mu,d,s}(t) + u^{(i)}_{\mu}(t)\}, boundary b^{(i)}_{d,s}(t) = \exp\{f_{b,d,s}(t) + u^{(i)}_{b}(t)\} and starts after an offset \delta^{(i)}_s. The fixed effects f are quadratic B-splines over blocks whose coefficients are locally clustered across (d, s) by hidden Markov models; the random effects u are smooth subject-specific spline curves.

Priors are calibrated so that, for the most stable performance, most values of r_time should lie between 0 and 10; response times in seconds work well. The offset \delta^{(i)}_s cannot exceed the fastest response of subject i to stimulus s, so implausibly fast responses (for example anticipations under 100 ms) force it towards zero and are best removed before fitting.

Value

List with the following MCMC posterior samples:

• post_mean_delta: population offsets (draw x stimulus)

• post_mean_mu, post_mean_b: population drift and boundary curves (block x stimulus x decision x draw), integrating out the random effects

• post_ind_delta: individual offsets (stimulus x subject x draw)

• post_ind_mu, post_ind_b: individual drift and boundary curves (block x subject x stimulus x decision x draw)

• sigma2_mu_us, sigma2_mu_ua, sigma2_b_us, sigma2_b_ua: smoothness and variance parameters of the random effects

• sigma2_1_mu, sigma2_1_b: smoothness parameters of the fixed effects (sigma2_b_us and sigma2_1_b are NA for constant boundaries)

• pred_ans, pred_time: posterior predictive decisions and response times at the population level (block x stimulus x draw)

• pred_ans_ind, pred_time_ind: the same for each subject (subject x block x stimulus x draw)

• loglik: log-likelihood of each observation (draw x observation)

• Z: cluster labels (stimulus x decision x knot x draw), if save_z = TRUE

• acceptance: acceptance rates of the Metropolis-Hastings steps after burn-in

• settings: model options and hyperparameters used

References

Paulon, G., Llanos, F., Chandrasekaran, B., Sarkar, A. (2021). Bayesian semiparametric longitudinal drift-diffusion mixed models for tone learning in adults. Journal of the American Statistical Association 116, 1114-1127. doi:10.1080/01621459.2020.1801448

Spline Penalty Matrix

Description

Penalty matrix of the smoothness inducing prior for spline coefficients: t(beta) %*% P %*% beta is the sum of squared first differences of beta (Eilers and Marx, 1996; article eq. 10).

Usage

P_smooth1(K)

Arguments

Value

K x K matrix P = t(D) %*% D, with D the (K-1) x K first-difference matrix.

Calculate WAIC

Description

Watanabe-Akaike information criterion (Gelman, Hwang and Vehtari, 2014), which estimates the expected out-of-sample prediction error using a bias-corrected adjustment of the within-sample error.

Usage

compute_WAIC(model_fit)

Arguments

Value

A scalar indicating the WAIC (smaller WAIC denotes better fit)

Example dataset

Description

Data in the format required by LDDMM(): 24,254 trials of 99 participants over 5 training blocks, with two possible input stimuli and decisions. The data were analyzed in Roark, Paulon, Sarkar and Chandrasekaran (2021), Psychonomic Bulletin & Review 28, 898-909.

Usage

data

Format

A data frame with 24,254 rows and 6 columns.

Details

• subject: participant labels

• block: training blocks (longitudinal units)

• s: input stimuli

• d: decisions

• r_time: response times, in seconds

• cens: censoring indicators (1 censored, 0 non censored); all 0 here

Parameter posterior draws

Description

Posterior draws of the subject-level drift or boundary parameters of the correct responses (d = s) from an LDDMM() fit.

Usage

extract_post_draws(data, fit, par = c("drift", "boundary"))

Arguments

Value

Data frame with columns block, subject, draw and one column ⁠<par>_<s>_<s>⁠ per stimulus with the posterior draws.

Parameter posterior means

Description

Posterior means of the subject-level drift or boundary parameters of the correct responses (d = s) from an LDDMM() fit.

Usage

extract_post_mean(data, fit, par = c("drift", "boundary"))

Arguments

Value

Data frame with columns block, subject and one column ⁠<par>_<s>_<s>⁠ per stimulus with the posterior means.

Log-likelihood

Description

Log-likelihood of the inverse Gaussian race model (article eq. 2), including the contribution of censored observations.

Usage

log_likelihood(tau, mu, b, delta, cens, D, log)

Arguments

Value

The (log-)likelihood of all n observations.

Log-likelihood of each observation

Description

Log-likelihood of the inverse Gaussian race model for every observation, including the contribution of censored observations.

Usage

log_likelihood_ind(tau, mu, b, delta, cens, D)

Arguments

Value

Vector of n log-likelihood values. An uncensored response time that is not larger than its offset has log-likelihood -Inf.

Descriptive plots

Description

Mean response time of each decision for every input stimulus and block, pooled over subjects. Censored trials are excluded.

Usage

plot_RT(data)

Arguments

Value

A ggplot object.

Descriptive plots

Description

Proportion of each decision for every input stimulus and block, by subject (thin lines) and pooled over subjects (thick lines). Censored trials are excluded.

Usage

plot_accuracy(data)

Arguments

Value

A ggplot object.

Plot posterior estimates

Description

Posterior means and 90% credible intervals of the population-level drift or boundary curves from an LDDMM() fit. Each panel is an input stimulus s; colours are the decisions d.

Usage

plot_post_pars(data, fit, par = c("drift", "boundary"))

Arguments

Value

A ggplot object.

Posterior predictive checks

Description

Compares the data with responses simulated from the fitted model. For every saved draw, LDDMM() simulates one response of every subject to every stimulus in every block (pred_ans_ind and pred_time_ind).

• type = "response": proportion of each decision, by stimulus and block. Lines are the posterior predictive mean of the proportion; bands are the 90% interval of the proportion among the simulated responses of one draw (one per participant), so they also contain the sampling variability of that many responses. Points are the observed proportions.

• type = "rt": 10%, 50% and 90% quantiles of the response times, by stimulus and block. Lines are the posterior predictive quantiles (pooled over subjects and draws); points are the observed quantiles.

Usage

plot_predictive(data, fit, type = c("response", "rt"))

Arguments

Details

Censored trials are left out of the observed data.

Value

A ggplot object.