Data simulated from the restricted 2HTM

Description

Data set generated from a restricted Two-High Threshold model.

Usage

SimData

Format

A data frame with five variables:

subj

subjects number

group

group label of the subjects

tree

condition of the current trial

cat

observed response category

rt

observed response time in ms

Details

Fourty subjects with thirty trials per condition (Studied items, new Items) were simulated.

Examples

###################################################################
# Detect-Guess variant of the restricted Two-High Threshold model.
###################################################################

head(SimData)

mdl_2HTM <- "
# targets
d+(1-d)*g     ; 0
(1-d)*(1-g)   ; 1

# lures
(1-d)*g       ; 0
d+(1-d)*(1-g) ; 1

# d: detect; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

data <- to_ertmpt_data(raw_data = SimData, model = model)

# this might take some time to run
ertmpt_out <- fit_ertmpt(model = model, data = data)

# convergence
## traceplot and summary of the first six parameters
coda::traceplot(ertmpt_out$samples[,1:6])
summary(ertmpt_out)

Set process thresholds equal

Description

Setting multiple process thresholds (a) equal. One of the process thresholds will be estimated and the other named thresholds will be set to equal the former. The equality can be removed by only using one name of a process.

Usage

a2a(model, names, keep_consts = FALSE)

set_a_equal(model, names, keep_consts = FALSE)

Arguments

Value

A list of the class drtmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, a2const, nu2const, nu2nu, omega2const, and omega2omega

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process thresholds for both detection processes ("do" and "dn")
# will be set equal.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## make do = dn
new_model <- a2a(model = model, names = c("do", "dn"))
new_model


## make do = dn
new_model <- set_a_equal(model = model, names = c("do", "dn"))
new_model

Set process threshold to constants

Description

Setting process thresholds (a) to constants or change it back to be estimated.

Usage

a2const(model, names, constants = NA)

set_a_const(model, names, constants = NA)

Arguments

Value

An object of the class drtmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, a2a, nu2const, nu2nu, omega2const and omega2omega

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process threshold for guessing (g) will be set to 1.0.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## setting threshold for g to a constant (1.0):
new_model <- a2const(model = model, names = c("g"), constants = c(1.0))
new_model


## setting threshold of g to a constant (1.0):
new_model <- set_a_const(model = model, names = c("g"), constants = c(1.0))
new_model

Set mapping between response categories and encoding plus motor execution times

Description

Mapping response categories with encoding and motor execution times (deltas). Unlike the processes there are no names for the different deltas and therefore a mapping from response categories to different deltas must be specified.

Usage

delta2delta(model, trees, categories, mappings = 0)

set_deltas_equal(model, trees, categories, mappings = 0)

Arguments

Value

A list of the class ertmpt_model.

Author(s)

Raphael Hartmann

See Also

theta2const, tau2zero, theta2theta, and tau2tau,

Examples

###########################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times will be set to different responses 
###########################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

## changing the model to have two different encoding and motor execution 
## times for "old" and "new" responses.
new_model <- delta2delta(model = model, trees = c(0, 1), 
                         categories = c(1,3), mappings = c(1,1))
new_model


model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## changing the model to have two different encoding and motor execution 
## times for "old" and "new" responses.
new_model <- delta2delta(model = model, trees = c(0, 1), 
                         categories = c(1,3), mappings = c(1,1))
new_model
                                 

## changing the model to have two different encoding and response execution 
## times for "old" and "new" responses.
new_model <- set_deltas_equal(model = model, trees = c(0, 1), 
                              categories = c(1,3), mappings = c(1,1))
new_model

Fit Diffusion-RT-MPT Models

Description

Given model and data, this function a Hamiltonian MCMC sampler and stores the samples in an mcmc.list called samples. Posterior predictive checks developed by Klauer (2010), deviance information criterion (DIC; Spiegelhalter et al., 2002), 99% and 95% highest density intervals (HDI) together with the median will be provided for the main parameters in a list called diags. Optionally, the indices widely applicable information criterion (WAIC; Watanabe, 2010; Vehtari et al., 2017) and leave-one-out cross-validation (LOO; Vehtari et al., 2017) can be saved. Additionally the log-likelihood (LogLik) can also be stored. Some specifications of the function call are also saved in specs.

Usage

fit_drtmpt(
  model,
  data,
  n.chains = 4,
  n.iter = 1000,
  n.phase1 = 1000,
  n.phase2 = 2000,
  n.thin = 1,
  Rhat_max = 1.1,
  Irep = 1000,
  prior_params = NULL,
  flags = NULL,
  control = NULL
)

Arguments

Value

A list of the class drtmpt_fit containing

• samples: the posterior samples as an mcmc.list object,

• diags: some diagnostics like deviance information criterion, posterior predictive checks for the frequencies and latencies, potential scale reduction factors, and also the 99% and 95% HDIs and medians for the group-level parameters,

• specs: some model specifications like the model, arguments of the model call, and information about the data transformation,

• indices (optional): if enabled, WAIC and LOO,

• LogLik (optional): if enabled, the log-likelihood matrix used for WAIC and LOO.

• summary includes posterior mean and median of the main parameters.

Author(s)

Raphael Hartmann

References

Klauer, K. C. (2010). Hierarchical multinomial processing tree models: A latent-trait approach. Psychometrika, 75(1), 70-98.

Spiegelhalter, D. J., Best, N. G., Carlin, B. P., & Van Der Linde, A. (2002). Bayesian measures of model complexity and fit. Journal of the royal statistical society: Series b (statistical methodology), 64(4), 583-639.

Vehtari, A., Gelman, A., & Gabry, J. (2017). Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC. Statistics and Computing, 27(5), 1413-1432.

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicable information criterion in singular learning theory. Journal of Machine Learning Research, 11(Dec), 3571-3594.

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each response.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

data_file <- system.file("extdata/data.txt", package="rtmpt")
data <- read.table(file = data_file, header = TRUE)
data_list <- to_drtmpt_data(raw_data = data, model = model)

# This might take some time
drtmpt_out <- fit_drtmpt(model = model, data = data_list, Rhat_max = 1.1)
drtmpt_out

Fit Exponential-RT-MPT Models

Description

Given model and data, this function calls an altered version of the C++ program by Klauer and Kellen (2018) to sample from the posterior distribution via a Metropolis-Gibbs sampler and storing it in an mcmc.list called samples. Posterior predictive checks developed by Klauer (2010), deviance information criterion (DIC; Spiegelhalter et al., 2002), 99% and 95% highest density intervals (HDI) together with the median will be provided for the main parameters in a list called diags. Optionally, the indices widely applicable information criterion (WAIC; Watanabe, 2010; Vehtari et al., 2017) and leave-one-out cross-validation (LOO; Vehtari et al., 2017) can be saved. Additionally the log-likelihood (LogLik) can also be stored. Some specifications of the function call are also saved in specs.

Usage

fit_ertmpt(
  model,
  data,
  n.chains = 4,
  n.iter = 5000,
  n.burnin = 200,
  n.thin = 1,
  Rhat_max = 1.05,
  Irep = 1000,
  prior_params = NULL,
  indices = FALSE,
  save_log_lik = FALSE,
  old_label = FALSE
)

Arguments

Value

A list of the class ertmpt_fit containing

• samples: the posterior samples as an mcmc.list object,

• diags: some diagnostics like deviance information criterion, posterior predictive checks for the frequencies and latencies, potential scale reduction factors, and also the 99% and 95% HDIs and medians for the group-level parameters,

• specs: some model specifications like the model, arguments of the model call, and information about the data transformation,

• indices (optional): if enabled, WAIC and LOO,

• LogLik (optional): if enabled, the log-likelihood matrix used for WAIC and LOO.

• summary includes posterior mean and median of the main parameters.

Author(s)

Raphael Hartmann

References

Hartmann, R., Johannsen, L., & Klauer, K. C. (2020). rtmpt: An R package for fitting response-time extended multinomial processing tree models. Behavior Research Methods, 52(3), 1313–1338.

Hartmann, R., & Klauer, K. C. (2020). Extending RT-MPTs to enable equal process times. Journal of Mathematical Psychology, 96, 102340.

Klauer, K. C. (2010). Hierarchical multinomial processing tree models: A latent-trait approach. Psychometrika, 75(1), 70-98.

Klauer, K. C., & Kellen, D. (2018). RT-MPTs: Process models for response-time distributions based on multinomial processing trees with applications to recognition memory. Journal of Mathematical Psychology, 82, 111-130.

Spiegelhalter, D. J., Best, N. G., Carlin, B. P., & Van Der Linde, A. (2002). Bayesian measures of model complexity and fit. Journal of the royal statistical society: Series b (statistical methodology), 64(4), 583-639.

Vehtari, A., Gelman, A., & Gabry, J. (2017). Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC. Statistics and Computing, 27(5), 1413-1432.

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicable information criterion in singular learning theory. Journal of Machine Learning Research, 11(Dec), 3571-3594.

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each response.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

data_file <- system.file("extdata/data.txt", package="rtmpt")
data <- read.table(file = data_file, header = TRUE)
data_list <- to_ertmpt_data(raw_data = data, model = model)

# This might take some time
ertmpt_out <- fit_ertmpt(model = model, data = data_list, Rhat_max = 1.1)
ertmpt_out

# Type ?SimData for another working example.

Simulation-based calibration for RT-MPT models

Description

Simulate data from RT-MPT models using ertmpt_model objects. The difference to sim_ertmpt_data is that here only scalars are allowed. This makes it usable for simulation-based calibration (SBC; Talts et al., 2018). You can specify the random seed, number of subjects, number of trials, and some parameters (same as prior_params from fit_ertmpt).

Usage

fit_ertmpt_SBC(
  model,
  seed,
  n.eff_samples = 99,
  n.chains = 4,
  n.iter = 5000,
  n.burnin = 200,
  n.thin = 1,
  Rhat_max = 1.05,
  Irep = 1000,
  n.subj = 40,
  n.trials = 30,
  prior_params = NULL,
  sim_list = NULL
)

Arguments

Value

A list of the class ertmpt_sbc containing

• ranks: the rank statistic for all parameters,

• sim_list: an object of the class ertmpt_sim,

• fit_list: an object of the class ertmpt_fit,

• specs: some specifications like the model, seed number, etc.,

Author(s)

Raphael Hartmann

References

Talts, S., Betancourt, M., Simpson, D., Vehtari, A., & Gelman, A. (2018). Validating Bayesian inference algorithms with simulation-based calibration. arXiv preprint arXiv:1804.06788.

Examples

########################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be different for each response.
########################################################################################

mdl_2HTM <- "
# targets
d+(1-d)*g     ; 0
(1-d)*(1-g)   ; 1

# lures
(1-d)*g       ; 0
d+(1-d)*(1-g) ; 1

# d: detect; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

params <- list(mean_of_exp_mu_beta = 10,
               var_of_exp_mu_beta = 10,
               mean_of_mu_gamma = 0.5,
               var_of_mu_gamma = 0.0025,
               mean_of_omega_sqr = 0.005,
               var_of_omega_sqr = 0.000025,
               df_of_sigma_sqr = 10,
               sf_of_scale_matrix_SIGMA = 0.1,
               sf_of_scale_matrix_GAMMA = 0.01,
               prec_epsilon = 10,
               add_df_to_invWish = 5)

R = 2 # typically 2000 with n.eff_samples = 99, but this will run many days
rank_mat <- matrix(NA, ncol = 393, nrow = 2)
for (r in 1:R) {
  SBC_out <- fit_ertmpt_SBC(model, seed = r*123, prior_params = params,
                           n.eff_samples = 99, n.thin = 5,
                           n.iter = 5000, n.burnin = 2000, Irep = 5000)
  rank_mat[r, ] <- SBC_out$ranks
}

Set process drift rate to constants

Description

Setting process drif rate (nu/v) to constants or change it back to be estimated.

Usage

nu2const(model, names, constants = NA)

set_nu_const(model, names, constants = NA)

set_v_const(model, names, constants = NA)

v2const(model, names, constants = NA)

Arguments

Value

An object of the class drtmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, a2const, a2a, nu2nu, omega2const and omega2omega

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process drift rate for guessing (g) will be set to 1.0.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## setting drift rate for g to a constant (1.0):
new_model <- nu2const(model = model, names = c("g"), constants = c(1.0))
new_model


## setting drift rate of g to a constant (1.0):
new_model <- set_nu_const(model = model, names = c("g"), constants = c(1.0))
new_model

## setting drift rate of g to a constant (1.0):
new_model <- set_v_const(model = model, names = c("g"), constants = c(1.0))
new_model

## setting drift rate of g to a constant (1.0):
new_model <- v2const(model = model, names = c("g"), constants = c(1.0))
new_model

Set process drift rates equal

Description

Setting multiple process drift rates (nu/v) equal. One of the process drift rates will be estimated and the other named drift rates will be set to equal the former. The equality can be removed by only using one name of a process.

Usage

nu2nu(model, names, keep_consts = FALSE)

set_nu_equal(model, names, keep_consts = FALSE)

set_v_equal(model, names, keep_consts = FALSE)

v2v(model, names, keep_consts = FALSE)

Arguments

Value

A list of the class drtmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, a2const, a2a, nu2const, omega2const, and omega2omega

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process drift rates for both detection processes ("do" and "dn")
# will be set equal.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## make do = dn
new_model <- nu2nu(model = model, names = c("do", "dn"))
new_model


## make do = dn
new_model <- set_nu_equal(model = model, names = c("do", "dn"))
new_model

## make do = dn
new_model <- set_v_equal(model = model, names = c("do", "dn"))
new_model

## make do = dn
new_model <- v2v(model = model, names = c("do", "dn"))
new_model

Set process relative starting-point to constants

Description

Setting process relative starting-point (omega/w) to constants or change it back to be estimated.

Usage

omega2const(model, names, constants = NA)

set_omega_const(model, names, constants = NA)

set_w_const(model, names, constants = NA)

w2const(model, names, constants = NA)

Arguments

Value

An object of the class drtmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, a2const, a2a, nu2const, nu2nu, and omega2omega

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process relative starting-point for guessing (g) will be set to 0.5.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## setting relative starting-point for g to a constant (1.0):
new_model <- omega2const(model = model, names = c("g"), constants = c(0.5))
new_model


## setting relative starting-point of g to a constant (0.5):
new_model <- set_omega_const(model = model, names = c("g"), constants = c(0.5))
new_model

## setting relative starting-point of g to a constant (0.5):
new_model <- set_w_const(model = model, names = c("g"), constants = c(0.5))
new_model

## setting relative starting-point of g to a constant (0.5):
new_model <- w2const(model = model, names = c("g"), constants = c(0.5))
new_model

Set process relaitve starting-point equal

Description

Setting multiple process relaitve starting-points (omega/w) equal. One of the process relaitve starting-points will be estimated and the other named relaitve starting-points will be set to equal the former. The equality can be removed by only using one name of a process.

Usage

omega2omega(model, names, keep_consts = FALSE)

set_omegas_equal(model, names, keep_consts = FALSE)

set_w_equal(model, names, keep_consts = FALSE)

w2w(model, names, keep_consts = FALSE)

Arguments

Value

A list of the class drtmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, a2const, a2a, nu2const, nu2nu, and omega2const

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process relaitve starting-points for both detection processes ("do" and "dn")
# will be set equal.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## make do = dn
new_model <- omega2omega(model = model, names = c("do", "dn"))
new_model


## make do = dn
new_model <- set_omegas_equal(model = model, names = c("do", "dn"))
new_model

## make do = dn
new_model <- set_w_equal(model = model, names = c("do", "dn"))
new_model

## make do = dn
new_model <- w2w(model = model, names = c("do", "dn"))
new_model

Set responses in an ertmpt_model or a drtmpt_model

Description

Change the responses for a tree and the categories within that tree.

Usage

set_resps(model, tree, categories, values = 0)

Arguments

Value

A list of the class ertmpt_model or drtmpt_model.

Author(s)

Raphael Hartmann

Examples

#########################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times will be set to different values 
#   for each response.
#########################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

## changing the model to have two different encoding and response execution 
## times for "old" and "new" responses.
for(i in c(0,1)) model <- set_resps(model = model, tree = i, 
                                    categories = i*2+1, values = 1)


#' model <- to_drtmpt_model(mdl_file = mdl_2HTM)

## changing the model to have two different encoding and response execution 
## times for "old" and "new" responses.
for(i in c(0,1)) model <- set_resps(model = model, tree = i, 
                                    categories = i*2+1, values = 1)
                                 

Simulate data from RT-MPT models

Description

Simulate data from RT-MPT models using ertmpt_model objects. You can specify the random seed, number of subjects, number of trials per tree, and some parameters (mainly the same as prior_params from fit_ertmpt).

Usage

sim_ertmpt_data(model, seed, n.subj, n.trials, params = NULL)

Arguments

Value

A list of the class ertmpt_sim containing

• data: the data.frame with the simulated data,

• gen_list: a list containing lists of the group-level and subject-specific parameters for the process-related parameters and the motor-related parameters, and the trial-specific probabilities, process-times, and motor-times,

• specs: some specifications like the model, seed number, etc.,

Author(s)

Raphael Hartmann

Examples

########################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be different for each response.
########################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g     ; 0
(1-do)*(1-g)    ; 1

# lures
(1-dn)*g        ; 0
dn+(1-dn)*(1-g) ; 1

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

# random group-level parameters
params <- list(mean_of_mu_alpha = 0, 
               #var_of_mu_alpha = 1
               mean_of_exp_mu_beta = 10, 
               var_of_exp_mu_beta = 10, 
               mean_of_mu_gamma = 0.5, 
               var_of_mu_gamma = 0.0025, 
               mean_of_omega_sqr = 0.005, 
               var_of_omega_sqr = 0.000025,
               df_of_sigma_sqr = 10, 
               sf_of_scale_matrix_SIGMA = 0.1, 
               sf_of_scale_matrix_GAMMA = 0.01, 
               prec_epsilon = 10,
               add_df_to_invWish = 5)

sim_dat <- sim_ertmpt_data(model, seed = 123, n.subj = 40, n.trials = 30, params = params)

# fixed group-level parameters
params <- list(mean_of_mu_alpha = 0, 
               mean_of_exp_mu_beta = 10, 
               mean_of_mu_gamma = 0.5, 
               mean_of_omega_sqr = 0.005, 
               df_of_sigma_sqr = 10, 
               sf_of_scale_matrix_SIGMA = 0.1, 
               sf_of_scale_matrix_GAMMA = 0.01, 
               prec_epsilon = 10,
               add_df_to_invWish = 5,
               SIGMA = diag(9),   # independent process-related params
               GAMMA = diag(2))   # independent motor time params

sim_dat <- sim_ertmpt_data(model, seed = 123, n.subj = 40, n.trials = 30, params = params)

Simulate data from an RT-MPT model

Description

Simulate data from RT-MPT models using ertmpt_model objects. The difference to sim_ertmpt_data is that here only scalars are allowed. This makes it usable for simulation-based calibration (SBC; Talts et al., 2018). You can specify the random seed, number of subjects, number of trials, and some parameters (same as prior_params from fit_ertmpt).

Usage

sim_ertmpt_data_SBC(model, seed, n.subj, n.trials, params = NULL)

Arguments

Value

A list of the class ertmpt_sim containing

• data: the data.frame with the simulated data,

• gen_list: a list containing lists of the group-level and subject-specific parameters for the process-related parameters and the motor-related parameters, and the trial-specific probabilities, process-times, and motor-times,

• specs: some specifications like the model, seed number, etc.,

Author(s)

Raphael Hartmann

References

Talts, S., Betancourt, M., Simpson, D., Vehtari, A., & Gelman, A. (2018). Validating Bayesian inference algorithms with simulation-based calibration. arXiv preprint arXiv:1804.06788.

Examples

########################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be different for each response.
########################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g     ; 0
(1-do)*(1-g)    ; 1

# lures
(1-dn)*g        ; 0
dn+(1-dn)*(1-g) ; 1

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

params <- list(mean_of_exp_mu_beta = 10, 
               var_of_exp_mu_beta = 10, 
               mean_of_mu_gamma = 0.5, 
               var_of_mu_gamma = 0.0025, 
               mean_of_omega_sqr = 0.005, 
               var_of_omega_sqr = 0.000025,
               df_of_sigma_sqr = 10, 
               sf_of_scale_matrix_SIGMA = 0.1, 
               sf_of_scale_matrix_GAMMA = 0.01, 
               prec_epsilon = 10,
               add_df_to_invWish = 5)

sim_dat <- rtmpt:::sim_ertmpt_data_SBC(model, seed = 123, n.subj = 40, 
                                      n.trials = 30, params = params)

Set process completion times equal

Description

Setting multiple process completion times (taus) equal. This means all process times of negative outcomes will be set equal and all process times of positive outcomes will be set equal. Only two process times (one for the negative and one for the positive outcome) of the named processes will be estimated. The equality can be removed by just naming only one process name.

Usage

tau2tau(model, names, outcome, keep_zeros = FALSE)

set_taus_equal(model, names, outcome, keep_zeros = FALSE)

set_lambdas_equal(model, names, outcome, keep_zeros = FALSE)

lambda2lambda(model, names, outcome, keep_zeros = FALSE)

Arguments

Value

A list of the class ertmpt_model.

Note

If you use theta2theta() and tau2tau() with the same process names you might just change the EQN or MDL file accordingly by using the same process name for all processes which should have equal process times and probabilities.

Author(s)

Raphael Hartmann

See Also

delta2delta, theta2const, tau2zero and theta2theta

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process completion times for both detection processes ("do" and "dn") will be
# set equal.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

## make do = dn
new_model <- tau2tau(model = model, names = c("do", "dn"), outcome = "both")
new_model


## make do = dn
new_model <- set_taus_equal(model = model, names = c("do", "dn"), outcome = "both")
new_model

## make do = dn
new_model <- set_lambdas_equal(model = model, names = c("do", "dn"), outcome = "both")
new_model

## make do = dn
new_model <- lambda2lambda(model = model, names = c("do", "dn"), outcome = "both")
new_model

Set process completion times to zero

Description

Setting process completion times (taus) to zero or change it back to be estimated.

Usage

tau2zero(model, names, outcomes, values = 0)

set_tau_zero(model, names, outcomes, values = 0)

Arguments

Value

A list of the class ertmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, theta2const, theta2theta and tau2tau

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process completion times for both failed detections will be suppressed.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

## removing the process times (tau) for the failed (="minus") detection ("do" and "dn") 
new_model <- tau2zero(model = model, names = c("dn", "do"),
                      outcomes = c("minus", "minus"), values = 0)
new_model


## removing the process times (tau) for the failed (="minus") detection ("do" and "dn") 
new_model <- set_tau_zero(model = model, names = c("dn", "do"),
                          outcomes = c("minus", "minus"), values = 0)
new_model

Set process probabilities to constants

Description

Setting process probabilities (thetas) to constants or change it back to be estimated.

Usage

theta2const(model, names, constants = NA)

set_theta_const(model, names, constants = NA)

Arguments

Value

An object of the class ertmpt_model.

Author(s)

Raphael Hartmann

See Also

delta2delta, tau2zero, theta2theta and tau2tau

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process probability for guessing (g) will be set to 0.5.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

## setting g to a constant (0.5):
new_model <- theta2const(model = model, names = c("g"), constants = c(0.5))
new_model
                    

## setting g to a constant (0.5):
new_model <- set_theta_const(model = model, names = c("g"), constants = c(0.5))
new_model

Set process probabilities equal

Description

Setting multiple process probabilities (thetas) equal. One of the process probabilities will be estimated and the other named process(es) will be set to equal the former. The equality can be removed by only using one name of a process.

Usage

theta2theta(model, names, keep_consts = FALSE)

set_thetas_equal(model, names, keep_consts = FALSE)

Arguments

Value

A list of the class ertmpt_model.

Note

If you use theta2theta() and tau2tau() with the same process names you might just change the EQN or MDL file accordingly by using the same process name for all processes which should have equal process times and probabilities.

Author(s)

Raphael Hartmann

See Also

delta2delta, theta2const, tau2zero and tau2tau

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each category.
# The process probabilities for both detection processes ("do" and "dn") will be
# set equal.
####################################################################################

mdl_2HTM <- "
# targets
do+(1-do)*g
(1-do)*(1-g)

# lures
(1-dn)*g
dn+(1-dn)*(1-g)

# do: detect old; dn: detect new; g: guess
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)

## make do = dn
new_model <- theta2theta(model = model, names = c("do", "dn"))
new_model


## make do = dn
new_model <- set_thetas_equal(model = model, names = c("do", "dn"))
new_model

Transform data to be used in Diffusion RT-MPT model fitting

Description

Transform data, such that it can be used in fit_drtmpt. This implies changing each value/label in "subj", "group", "tree", and "cat" to numbers such that it starts from zero (e.g. data$tree = c(1,1,3,3,2,2,...) will be changed to data$tree = c(0,0,2,2,1,1,...)) and the columns will be ordered in the right way. "rt" must be provided in milliseconds. If it has decimal places it will be rounded to a whole number. fit_drtmpt will automatically call this function if its input is not already a drtmpt_data list, but it is advised to use it anyway because it provides information about the transformations of the data.

Usage

to_drtmpt_data(raw_data, model)

Arguments

Value

A list of the class drtmpt_data containing transformed data and information about the transformation that has been done.

Author(s)

Raphael Hartmann

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each response.
####################################################################################

eqn_2HTM <- "
# CORE MPT EQN
# tree ; cat  ; mpt
target ; hit  ; do
target ; hit  ; (1-do)*g
target ; miss ; (1-do)*(1-g)

  lure ;  f_a ; (1-dn)*g
  lure ;  c_r ; dn
  lure ;  c_r ; (1-dn)*(1-g)
"

model <- to_drtmpt_model(eqn_file = eqn_2HTM)

data_file <- system.file("extdata/labeled_data.txt", package="rtmpt")
data <- read.table(file = data_file, header = TRUE)

data_list <- to_drtmpt_data(raw_data = data, model = model)
data_list

Create a model list to fit a Diffusion-RT-MPT

Description

Create a model list of the class drtmpt_model by providing either eqn_file or mdl_file. If both are provided mdl_file will be used.

Usage

to_drtmpt_model(eqn_file = NULL, mdl_file = NULL)

Arguments

Value

A list of the class drtmpt_model.

Note

Within a branch of a (RT-)MPT model it is not allowed to have the same process two or more times.

Author(s)

Raphael Hartmann

References

Heck, D. W., Arnold, N. R., & Arnold, D. (2018). TreeBUGS: An R package for hierarchical multinomial-processing-tree modeling. Behavior Research Methods, 50(1), 264-284.

Hu, X. (1999). Multinomial processing tree models: An implementation. Behavior Research Methods, Instruments, & Computers, 31(4), 689-695.

Singmann, H., & Kellen, D. (2013). MPTinR: Analysis of multinomial processing tree models in R. Behavior Research Methods, 45(2), 560-575.

See Also

delta2delta, theta2const, tau2zero, theta2theta, and tau2tau for functions to change the model

Examples

########################################################################################
# Detect-Guess variant of the Two-High Threshold model
#   with constant guessing and
#   suppressed process completion times for both failed detections.
# The encoding and motor execution times are assumed to be different for each response.
########################################################################################

## 1. using the mdl syntax
mdl_2HTM <- "
# targets
do+(1-do)*g     ; 0
(1-do)*(1-g)    ; 1

# lures
(1-dn)*g        ; 0
dn+(1-dn)*(1-g) ; 1

# do: detect old; dn: detect new; g: guess
"

model <- to_drtmpt_model(mdl_file = mdl_2HTM)
model

## 2. using the eqn syntax
eqn_2HTM <- "
# CORE MPT EQN
# tree ; cat ; mpt
     0 ;   0 ; do
     0 ;   0 ; (1-do)*g
     0 ;   1 ; (1-do)*(1-g)

     1 ;   2 ; (1-dn)*g
     1 ;   3 ; dn
     1 ;   3 ; (1-dn)*(1-g)

# OPTIONAL MPT CONSTRAINTS
#     tree ; cat ;  MAP
resp:    0 ;   0 ;    0
resp:    0 ;   1 ;    1
resp:    1 ;   2 ;    0
resp:    1 ;   3 ;    1
# different motor execution times for old and new responses.
"

model <- to_drtmpt_model(eqn_file = eqn_2HTM)
model

Transform data to be used in RT-MPT model fitting

Description

Transform data, such that it can be used in fit_ertmpt. This implies changing each value/label in "subj", "group", "tree", and "cat" to numbers such that it starts from zero (e.g. data$tree = c(1,1,3,3,2,2,...) will be changed to data$tree = c(0,0,2,2,1,1,...)) and the columns will be ordered in the right way. "rt" must be provided in milliseconds. If it has decimal places it will be rounded to a whole number. fit_ertmpt will automatically call this function if its input is not already an ertmpt_data list, but it is advised to use it anyway because it provides information about the transformations of the data.

Usage

to_ertmpt_data(raw_data, model)

to_rtmpt_data(raw_data, model)

Arguments

Value

A list of the class ertmpt_data containing transformed data and information about the transformation that has been done.

Author(s)

Raphael Hartmann

Examples

####################################################################################
# Detect-Guess variant of the Two-High Threshold model.
# The encoding and motor execution times are assumed to be equal for each response.
####################################################################################

eqn_2HTM <- "
# CORE MPT EQN
# tree ; cat  ; mpt
target ; hit  ; do
target ; hit  ; (1-do)*g
target ; miss ; (1-do)*(1-g)
       
  lure ;  f_a ; (1-dn)*g
  lure ;  c_r ; dn
  lure ;  c_r ; (1-dn)*(1-g)
"

model <- to_ertmpt_model(eqn_file = eqn_2HTM)

data_file <- system.file("extdata/labeled_data.txt", package="rtmpt")
data <- read.table(file = data_file, header = TRUE)

data_list <- to_ertmpt_data(raw_data = data, model = model)
data_list 


eqn_2HTM <- "
# CORE MPT EQN
# tree ; cat  ; mpt
target ; hit  ; do
target ; hit  ; (1-do)*g
target ; miss ; (1-do)*(1-g)
       
  lure ;  f_a ; (1-dn)*g
  lure ;  c_r ; dn
  lure ;  c_r ; (1-dn)*(1-g)
"

model <- to_rtmpt_model(eqn_file = eqn_2HTM)

data_file <- system.file("extdata/labeled_data.txt", package="rtmpt")
data <- read.table(file = data_file, header = TRUE)

data_list <- to_rtmpt_data(raw_data = data, model = model)
data_list 

Create a model list to fit an RT-MPT

Description

Create a model list of the class ertmpt_model by providing either eqn_file or mdl_file. If both are provided mdl_file will be used.

Usage

to_ertmpt_model(eqn_file = NULL, mdl_file = NULL)

to_rtmpt_model(eqn_file = NULL, mdl_file = NULL)

Arguments

Value

A list of the class ertmpt_model.

Note

Within a branch of a (RT-)MPT model it is not allowed to have the same process two or more times.

Author(s)

Raphael Hartmann

References

Heck, D. W., Arnold, N. R., & Arnold, D. (2018). TreeBUGS: An R package for hierarchical multinomial-processing-tree modeling. Behavior Research Methods, 50(1), 264-284.

Hu, X. (1999). Multinomial processing tree models: An implementation. Behavior Research Methods, Instruments, & Computers, 31(4), 689-695.

Singmann, H., & Kellen, D. (2013). MPTinR: Analysis of multinomial processing tree models in R. Behavior Research Methods, 45(2), 560-575.

See Also

delta2delta, theta2const, tau2zero, theta2theta, and tau2tau for functions to change the model

Examples

########################################################################################
# Detect-Guess variant of the Two-High Threshold model
#   with constant guessing and
#   suppressed process completion times for both failed detections.
# The encoding and motor execution times are assumed to be different for each response.
########################################################################################

## 1. using the mdl syntax
mdl_2HTM <- "
# targets
do+(1-do)*g     ; 0
(1-do)*(1-g)    ; 1

# lures
(1-dn)*g        ; 0
dn+(1-dn)*(1-g) ; 1

# do: detect old; dn: detect new; g: guess

# OPTIONAL MPT CONSTRAINTS
# for constant thetas and suppressed taus
# please use theta2cons() and tau2
"

model <- to_ertmpt_model(mdl_file = mdl_2HTM)
model

## 2. using the eqn syntax
eqn_2HTM <- "
# CORE MPT EQN
# tree ; cat ; mpt
     0 ;   0 ; do
     0 ;   0 ; (1-do)*g
     0 ;   1 ; (1-do)*(1-g)
       
     1 ;   2 ; (1-dn)*g
     1 ;   3 ; dn
     1 ;   3 ; (1-dn)*(1-g)

# OPTIONAL MPT CONSTRAINTS
# for constant thetas and suppressed taus
# please use theta2cons() and tau2

#     tree ; cat ;  MAP
resp:    0 ;   0 ;    0
resp:    0 ;   1 ;    1
resp:    1 ;   2 ;    0
resp:    1 ;   3 ;    1
# different motor execution times for old and new responses.
"

model <- to_ertmpt_model(eqn_file = eqn_2HTM)
model


mdl_2HTM <- "
# targets
do+(1-do)*g     ; 0
(1-do)*(1-g)    ; 1

# lures
(1-dn)*g        ; 0
dn+(1-dn)*(1-g) ; 1

# do: detect old; dn: detect new; g: guess
"

model <- to_rtmpt_model(mdl_file = mdl_2HTM)
model