hBayesDM_model: hBayesDM Model Base Function

Description

The base function from which all hBayesDM model functions are created.

Usage

hBayesDM_model(
  task_name,
  model_name,
  model_type = "",
  data_columns,
  parameters,
  regressors = NULL,
  postpreds = "y_pred",
  stanmodel_arg = NULL,
  preprocess_func
)

Value

A specific hBayesDM model function.

Arguments

task_name: Character value for name of task. E.g. "gng".
model_name: Character value for name of model. E.g. "m1".
model_type: Character value for modeling type: "" OR "single" OR "multipleB".
data_columns: Character vector of necessary column names for the data. E.g. c("subjID", "cue", "keyPressed", "outcome").
parameters: List of parameters, with information about their lower bound, plausible value, upper bound. E.g. list("xi" = c(0, 0.1, 1), "ep" = c(0, 0.2, 1), "rho" = c(0, exp(2), Inf)).
regressors: List of regressors, with information about their extracted dimensions. E.g. list("Qgo" = 2, "Qnogo" = 2, "Wgo" = 2, "Wnogo" = 2). OR if model-based regressors are not available for this model, NULL.
postpreds: Character vector of name(s) for the trial-level posterior predictive simulations. Default is "y_pred". OR if posterior predictions are not yet available for this model, NULL.
stanmodel_arg: Leave as NULL (default) for completed models. Else should either be a character value (specifying the name of a Stan file) OR a stanmodel object (returned as a result of running stan_model).
preprocess_func: Function to preprocess the raw data before it gets passed to Stan. Takes (at least) two arguments: a data.table object raw_data and a list object general_info. Possible to include additional argument(s) to use during preprocessing. Should return a list object data_list, which will then directly be passed to Stan.

Details

task_name: Typically same task models share the same data column requirements.

model_name: Typically different models are distinguished by their different list of parameters.

model_type is one of the following three:

"": Modeling of multiple subjects. (Default hierarchical Bayesian analysis.)
"single": Modeling of a single subject.
"multipleB": Modeling of multiple subjects, where multiple blocks exist within each subject.

data_columns must be the entirety of necessary data columns used at some point in the R or Stan code. I.e. "subjID" must always be included. In the case of 'multipleB' type models, "block" should also be included as well.

parameters is a list object, whose keys are the parameters of this model. Each parameter key must be assigned a numeric vector holding 3 elements: the parameter's lower bound, plausible value, and upper bound.

regressors is a list object, whose keys are the model-based regressors of this model. Each regressor key must be assigned a numeric value indicating the number of dimensions its data will be extracted as. If model-based regressors are not available for this model, this argument should just be NULL.

postpreds defaults to "y_pred", but any other character vector holding appropriate names is possible (c.f. Two-Step Task models). If posterior predictions are not yet available for this model, this argument should just be NULL.

stanmodel_arg can be used by developers, during the developmental stage of creating a new model function. If this argument is passed a character value, the Stan file with the corresponding name will be used for model fitting. If this argument is passed a stanmodel object, that stanmodel object will be used for model fitting. When creation of the model function is complete, this argument should just be left as NULL.

preprocess_func is the part of the code that is specific to the model, and is thus written in the specific model R file.
Arguments for this function are:

raw_data: A data.table that holds the raw user data, which was read by using fread.
general_info: A list that holds the general informations about the raw data, i.e. subjs, n_subj, t_subjs, t_max, b_subjs, b_max.
...: Optional additional argument(s) that specific model functions may want to include. Examples of such additional arguments currently being used in hBayesDM models are: RTbound (choiceRT_ddm models), payscale (igt models), and trans_prob (ts models).

Return value for this function should be:

data_list: A list with appropriately named keys (as required by the model Stan file), holding the fully preprocessed user data.

NOTE: Syntax for data.table slightly differs from that of data.frame. If you want to use raw_data as a data.frame when writing the preprocess_func, simply begin with the line: raw_data <- as.data.frame(raw_data).
NOTE: Because of allowing case & underscore insensitive column names in user data, raw_data columns must now be referenced by their lowercase non-underscored versions, e.g. "subjid", within the code of the preprocess function.