hBayesDM_model: hBayesDM Model Base Function
In hBayesDM: Hierarchical Bayesian Modeling of Decision-Making Tasks

hBayesDM_model

R Documentation

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
)

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.