What is hBayesDM?

hBayesDM (hierarchical Bayesian modeling of Decision-Making tasks) is a user-friendly R package that offers hierarchical Bayesian analysis of various computational models on an array of decision-making tasks. Click here to download its help file (reference manual). Click here to read our preprint. Click here to download a poster we recently presented at several conferences/meetings. You can find hBayesDM on CRAN now.

User Support (New in December, 2016)

Latest Version

0.3.0 (Jan 14, 2016)

What’s new Version 0.3.0 - Made several changes following the guidelines for R packages providing interfaces to Stan. - Stan models are precompiled and models will run immediately when called. - The default number of chains is set to 4. - Set the default value of adapt_delta to 0.95 to reduce the potential for divergences. - rhat function uses LOOIC by default. Users can select WAIC or both (LOOIC & WAIC) if needed.

Version 0.2.3.3 - Add help files. - Add a function (rhat) for checking Rhat values. - Change a link to its tutorial website.

Version 0.2.3.1 - Add a new function (plotInd) for plotting individual parameters. See its help file (?plotInd) for more details.

Motivation

Computational modeling provides a quantitative framework for investigating latent neurocognitive processes (e.g., learning rate, reward sensitivity) and interactions among multiple decision-making systems. Parameters of a computational model reflect psychologically meaningful individual differences: thus, getting accurate parameter estimates of a computational model is critical to improving the interpretation of its findings. Hierarchical Bayesian analysis (HBA) is regarded as the gold standard for parameter estimation, especially when the amount of information from each participant is small (see below “Why hierarchical Bayesian analysis?”). However, many researchers interested in HBA often find the approach too technical and challenging to be implemented.

We introduce a free R package hBayesDM, which offers HBA of various computational models on an array of decision-making tasks (see below for a list of tasks and models currently available). Users can perform HBA of various computational models with a single line of coding. Example datasets are also available. With hBayesDM, we hope anyone with minimal knowledge of programming can take advantage of advanced computational modeling and HBA. It is our expectation that hBayesDM will contribute to the dissemination of these computational tools and enable researchers in related fields to easily characterize latent neurocognitive processes within their study populations.

Why hierarchical Bayesian analysis (HBA)?

Most computational models do not have closed form solutions and we need to estimate parameter values. Traditionally parameters are estimated at the individual level with maximum likelihood estimation (MLE): getting point estimates for each individual separately. However, individual MLE estimates are often noisy especially when there is insufficient amount of data. A group-level analysis (e.g., group-level MLE), which estimate a single set of parameters for the whole group of individuals, may generate more reliable estimates but inevitably ignores individual differences.

HBA and other hierarchical approaches (e.g., Huys et al., 2011) allow for individual differences while pooling information across individuals. Both individual and group parameter estimates (i.e., posterior distributions) are estimated simultaneously in a mutually constraining fashion. Consequently, individual parameter estimates tend to be more stable and reliable because commonalities among individuals are captured and informed by the group tendencies (e.g., Ahn et al., 2011). HBA also finds full posterior distributions instead of point estimates (thus providing rich information about the parameters). HBA also makes it easy to do group comparisons in a Bayesian fashion (e.g., comparing clinical and non-clinical groups, see an example below).

HBA is a branch of Bayesian statistics and the conceptual framework of Bayesian data analysis is clearly written in Chapter 2 of John Kruschke’s book (J. Kruschke, 2014). In Bayesian statistics, we assume prior beliefs (i.e., prior distributions) for model parameters and update the priors into posterior distributions given the data (e.g., trial-by-trial choices and outcomes) using Bayes’ rule. Note that the prior distributions we use for model parameters are vague (e.g., flat) or weakly informative priors, so they play a minimal role in the posterior distribution.

For Bayesian updating, we use the Stan software package (http://mc-stan.org/), which implements a very efficient Markov Chain Monte Carlo (MCMC) algorithm called Hamiltonian Monte Carlo (HMC). HMC is known to be effective and works well even for large complex models. See Stan reference manual (http://mc-stan.org/documentation/) and Chapter 14 of J. Kruschke (2014) for a comprehensive description of HMC and Stan. What is MCMC and why shoud we use it? Remember, we need to update our priors into posterior distributions in order to make inference about model parameters. Simply put, MCMC is a way of approximating a posterior distribution by drawing a large number of samples from it. MCMC algorithms are used when posterior distributions cannot be analytically achieved or using MCMC is more efficient than searching for the whole grid of parameter space (i.e., grid search). To learn more about the basic foundations of MCMC, we recommend Chapter 7 of J. Kruschke (2014).

Detailed specification of Bayesian models is not available in text yet (stay tuned for our tutorial paper whose citation is listed below). At the same time, users can go over our Stan codes to check how we implement each computational model (e.g., PathTo_gng_m1 = system.file("stan/gng_m1.stan", package="hBayesDM") ). We made strong efforts to optimize Stan codes through reparameterization (e.g., Matt trick) and vectorization.

How to install hBayesDM

The hBayesDM package is now available on CRAN! There are two ways to install hBayesDM, both of which are described below. Make sure to install RStan prior to install hBayesDM. Typically RStan can be installed just by typing install.packages("rstan", dependencies = TRUE). For Windows, you need to install Rtools first to install RStan. How can you tell if RStan is correctly installed? Check if you can fit the ‘Eight Schools’ model without a problem. Check here or here if you experience difficulty installing RStan.

How to use hBayesDM

First, open RStudio (or just R) and load the package:

library(hBayesDM)

Four steps of doing HBA with hBayesDM are illustrated below. As an example, four models of the orthogonalized Go/Nogo task (Guitart-Masip et al., 2012; Cavanagh et al., 2013) are fit and compared with the hBayesDM package.

1. Prepare the data

For fitting a model with hBayesDM, all subjects’ data should be combined into a single text (*.txt) file. Look at the sample dataset and a help file (e.g., ?gng_m1) for each task and carefully follow the instructions.

Subjects’ data must contain variables that are consistent with the column names specified in the help file, though extra variables are in practice allowed.

It is okay if the number of trials is different across subjects. But there should exist no N/A data. If some trials contain N/A data (e.g., choice=NA in trial#10), remove the trials first.

Sample data are available here, although users can fit a model with sample data without separately downloading them with one of the function arguments. Once the hBayesDM package is installed, sample data can be also retrieved from the package folder. Note that the file name of sample (example) data for a given task is taskName_exampleData.txt (e.g., dd_exampleData.txt, igt_exampleData.txt, gng_exampleData.txt, etc.). See each model’s help file (e.g., ?gng_m1) to check required data columns and their labels.

If you download the sample data to “~/Downloads”, you may specify the path to the data file like this:

dataPath = "~/Downloads/gng_exampleData.txt"

2. Fit candidate models

Below the gng_m1 model is fit with its sample data. The command indicates that three MCMC chains are run and three cores are used for parallel computing. If you enter “example” as an argument for data, hBayesDM will use the sample data for the task. Note that you can save the output to a file (see the saveDir argument) or send an email when fitting is complete (see the email argument). You can also assign your own initial values (see the inits argument; e.g., inits=c(0.1, 0.2, 1.0)):

, which is the same as the command below because the default numbers of total (including warmup) iterations (MCMC samples), warmup iterations, and chains are 2,000, 1,000, and 4 for gng models.

output1 = gng_m1("example", ncore=4)

Executing the command will generate messages like below in the R console. It will take approximately 2~3 minutes (with the gng_m1 model & “example” data) for the model fitting to complete. Note that you may get warning messages about “numerical problems” or that there are a certain number of “divergent transitions after warmup”. When we check our models with example datasets, warning messages appear mostly at the beginning of the warmup period and there are very few divergent transitions after warmup. In such cases, you can ignore the warnings. Also see Appendix D of the Stan Reference Manual.

modelRegressor (optional): Trial-by-trial model-based regressors such as prediction errors, the values of the chosen option, etc. For each model, we pre-select appropriate model-based regressors. Currently (version 0.2.3.3), this feature is available only for the orthogonalized Go/NoGo task.

\(\hat{R}\) (Rhat) is an index of the convergence of the chains. \(\hat{R}\) values close to 1.00 would indicate that MCMC chains are converged to stationary target distributions. When we check MCMC performance of our models on sample data, \(\hat{R}\) values are 1.00 for most parameters or at most 1.04.

3. Plot model parameters

Make sure to visually diagnose MCMC performance (i.e., visually check whether MCMC samples are well mixed and converged to stationary distributions). For the diagnosis or visualization of hyper (group) parameters, you can use plot.hBayesDM or just plot, which searches for an extension function that contains the class name. The class of any hBayesDM output is hBayesDM: