Hidden Markov model of evidence accumulation

This repository is associated with the article

Kucharský, Š., Tran, N. H., Veldkamp, K., Raijmakers, M., & Visser, I. (2021). Hidden Markov models of evidence accumulation in speeded decision tasks. Computational Brain & Behavior, 4, 416-441. https://doi.org/10.1007/s42113-021-00115-0

Dependencies (setting up correct version of Stan)

The models were written in Stan and require CmdStan version above 2.24.0. The code was run using cmdstanr package in R. To set up the computational environment correctly in the analysis scripts, the correct version of CmdStan is loaded using the following command:

set\_cmdstan\_path(readRDS("path\_to\_cmdstan.Rds"))

The object path\_to\_cmdstan.Rds actually contains just a string that specifies the folder where the appropriate version of CmdStan is installed:

> readRDS("path\_to\_cmdstan.Rds")
[1] "~/.cmdstan/cmdstan-2.24.0-rc1/"

For it to work on a computer with different location to CmdStan, run the following command in R:

path\_to\_cmdstan <- "my/path/to/cmdstan/installation"
saveRDS(path\_to\_cmdstan, "path\_to\_cmdstan.Rds")

Note: there has been an update of the way how cmdstanr package extracts parameters see here for an example. This yields previously saved CmdStan objects unworkable. To be able to work with the saved files, install earlier version of cmdstanr package, v0.2.0 https://github.com/stan-dev/cmdstanr/releases/tag/v0.2.0.

Structure of this repository

1. data/ folder contains cleaned data from Dutilh, et al. (2010) that are reanalyzed in the article.
2. stan/ folder contains stan models and scripts:
   • helpers/ contains some functions that are used in the stan models
   • hmm/ contains manually written backward, forward, and forward-backward algorithm that was used to check the use of the new hmm_marginal_lpdf() function implemented in CmdStan version 2.24.0.
   • later/ contains functions that implement the simplified LBA model in Stan
   • Additionally, the folder contains models like hmm_normal.stan that were used to check the correctness of the use of the new HMM functions in Stan language (see also script hmm_normal.R).
3. scripts/ folder contains the R scripts used to produce the output presented in the article. The scripts are meant to be run in order. Here the brief summary of what each script does.
   • 00_get_dutilh_2010_data.R downloads, cleans and saves data from Dutilh, et al. (2010) study.
   • 01_sim_prior_predictives.R simulates data from a prior predictive distribution. The script saves the hyperparameters in hyperparameters.Rds object, and the simulated data (and true parameter values) inside prior_predictives.Rds.
   • 02_sim_map_estimation.R fits the prior predictive data sets using maximum a posteriori estimation, saves the results in map_estimates_simulation.Rds object, and computes parameter recovery results.
   • 03_sim_full_bayes_estimation.R fits the prior predictive data sets using MCMC, and saves the results inside of folder under saves/sbc. (The actuall saved chains are not uploaded to GitHub due to huge size of the files)
   • 04_sim_full_bayes_results.R processes the fitted models on the simulated data, and creates output for the Simulation-based calibration model sensitivity analysis, parameter recovery, and coverage of the posterior credible intervals.
   • 05_fit_dutilh_data.R is a script that fits data from a single participant. It is mean to be run from a terminal using command: Rscript --vanilla scripts/05_fit_dutilh_data.R A to fit data from participant "A", etc. The resulting fit objects are saved in folder saves/hmm_later/.
   • 06_results_dutilh_data.R processes the fitted models on the Dutilh, et al. (2010) data and produces the figures and tables presented in the article.
   • hmm_normal.R checks the correctness of the use of the new hmm_marginal_lpdf() function.
   • hmm_later.R is a "legacy" script. Originally, the simulations were run here, later the code was refactored to make it easier to make sense of the code.
4. saves/ folder contains some R objects saved during the project for convenience.
5. R/ folder contains some R functions for convenience.
6. figures/ folder contains all figures generated in this project.