HGF Toolbox

Release ID: $Format:%h %d$

---

Copyright (C) 2012-2022 Christoph Mathys chmathys@ethz.ch Translational Neuromodeling Unit (TNU) University of Zurich and ETH Zurich

---

The HGF toolbox is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see the file COPYING). If not, see http://www.gnu.org/licenses/.

---

How to cite the HGF Toolbox

Please cite the following paper when using the HGF Toolbox:

Frässle, S., et al. (2021). TAPAS: An Open-Source Software Package for Translational Neuromodeling and Computational Psychiatry. Frontiers in Psychiatry, 12:680811. https://doi.org/10.3389/fpsyt.2021.680811

Installation

Move this folder to a location of your choice and add it to your Matlab path.

Documentation and configuration

Documentation can be found in the manual contained in the Manual.pdf file. This will point you to the relevant configuration files. Further documentation is available throughout the source code.

Tutorial demo

There is a Matlab LiveScript tutorial demo that can be launched by opening hgfdemo.mlx in Matlab. A PDF version is available in hgfdemo.pdf.

Release notes

v7.1

• Add ehgfar1plotTraj
• Bugfix ### v7.0
• Numerical stability improvements to optimization
• Combined response models (more than one observation per trial)
• Various bugfixes and minor improvements

v6.1

• Improved functionality of beta_obs response model
• Included reference to TAPAS paper

v6.0

• Introduced first eHGF models (ehgf, ehgfbinary, ehgfjget)
• Enabled calling fitModel with config structures as arguments
• Enabled changing config structures on the fly
• Introduced sampleModel for sampling from the prior
• Various other additions, improvements, and bugfixes

v5.3

• Enabled setting and storing of seed for random number generator in simulations
• Debugged reading of response model configuration in simModel
• Reduced default maxStep from 2 to 1 in quasinewtonoqptimconfig
• Improved readability of siem files for unitsqsgm and softmaxbinary
• Added simulation capability for softmaxwld and softmaxmu3_wld
• Added softmax_wld response model
• Improved readability of softmaxmu3wld code
• Improved readability of softmax and softmax_mu3 code

v5.2

• Brought hgf_demo.pdf up to date
• Added gaussianobsoffset response model
• Brought example in simModel up to date
• Added sim and namep files for unitsqsgmmu3
• Fixed typo in softmaxmu3wld
• Introduced softmaxmu3wld decision model
• Estimate mu02 by default in hgfar1binarymab
• Improved comment in softmaxmu3config
• Change to pi2 update in hgfar1binarymab
• Enabled simulation for hgfar1binary_mab
• Added softmax_mu3
• Added hgfar1binary_mab
• Fixed automatic detection of number of levels in hgfar1binary
• Fixed documentation of hgfar1binary
• Fixed hgfbinarymab_plotTraj
• Fixed trajectory calculations in hgfbinarymab
• Adapted riddersgradient and riddershessian to new Matlab versions
• Quashed bug in rwbinarydual found by gbelluc@gmail.com

v5.1

• Added condhallucobs and condhallucobs2 models
• Introduced kappa1 in all binary HGF models

v5.0

• Ported interactive demo to Matlab LiveScript
• Various additional small improvements
• Updated manual
• Updated and renamed README to README.md

v4.17

• Improvements to logrtlinearbinary_minimal

v4.16

• Added the binary HGF with trial-by-trial perceptual uncertainty as hgfbinarypu_tbt

v4.15

• Added the Kalman filter as kf

v4.14

• Improved the beta_obs model
• Improved calculation of implied 1st-level learning rate

v4.13

• Corrected sign of update trajectories
• Added option to base responses on predictions or posteriors in the beta_obs model

v4.12

• Added tapas_autocorr.m

v4.11

• Predictions and residuals returned by all observations models
• Added tapasfitplotResidualDiagnostics()

v4.10

• Added hgfcategoricalnorm
• Added Boltzmann distribution (i.e., softmax normalization) as tapas_boltzmann()

v4.9

• Set implied learning rate at first level to 0 if update is zero

v4.8

• Give choice of using predictions or posteriors with softmax_binary

v4.7

• Added cdfgaussian_obs model
• Added hgfbinarypu (perceptual uncertainty) model
• Improvements for betaobs with hgfwhichworld

v4.6

• Adapted betaobs to deal with phbinary
• Added Pearce-Hall in ph_binary
• Clarified the role of default settings in comments of fitModel
• Brought softmaxbinarysim up to date

v4.5

• Improved comments in softmaxbinarysim
• Improved comments in tapasbetaobs.m
• Added tapasbetaobs_{sim,namep}.m

v4.4

• Added tapashgfar1binarynamep.m
• Improved rw_binary

v4.3

• Added bayesoptimalcategorical
• Improved hgfcategoricalplotTraj

v4.2

• Adapted softmaxsim to hgfcategorical
• Added hgf_categorical
• Added datagen_categorical and categorical data example

v4.1

• Improved hgf_jget

v4.0

• Added PDF manual
• Added interactive demo in hgf_demo
• Added file of raw commands from hgfdemo in hgfdemo_commands
• Adapted fitModel to calculate AIC and BIC
• Renamed F (negative variational free energy) to LME (log-model evidence, to which it is an approximation)
• Calculate accuracy and complexity in fitModel
• Save everything relating to model quality under r.optim
• Improved output of fitModel
• Added hierarchical hidden Markov model (hhmm)
• Added hidden Markov model (hmm)
• Added WhatWorld (hgf_whatworld) model
• Added linear log-reaction time (logrtlinearwhatworld) model for WhatWorld
• Added WhichWorld (hgf_whichworld) model
• Added AR(1) model for binary outcomes (hgfar1binary)
• Added Jumping Gaussian Estimation (hgf_jget) model
• Added unitsqsgmmu3 decision model
• Added binary multi-armed bandit model hgfbinarymab
• Added beta_obs observation model for decision noise on the unit interval
• Added softmax decision model with different inverse temperature for each kind of binary decision (softmax_2beta)
• Added logrtlinearbinary decision model
• Added Rescorla-Wagner model with different learning rate for each kind of binary outcome (rwbinarydual)
• Included additional trajectories in output of hgf, hgfar1, hgfar1mab, hgfbinary, hgfar1binary, hgfbinarymab, hgfwhichworld, and hgfwhatworld
• Made infStates more consistent across models
• Removed deprecated hgf_binary3l
• Made fitModel explicitly return negative log-joint probability and negative log-likelihood
• Modified simModel to read configuration files of perceptual and observation models
• Abolished theta in hgf, hgfbinary, hgfar1, hgfar1mab, hgfar1binary, hgfbinarymab, and hgf_jget
• Moved kappa estimation from logit-space to log-space for hgf, hgfbinary, hgfar1, hgfar1mab, hgfar1binary, hgfbinarymab, and hgf_jget
• Introduced checking for implausible jumps in trajectories for hgf, hgfbinary, hgfar1, hgfar1mab, hgfar1binary, hgfbinarymab, and hgf_jget
• Adapted fitModel to deal with cases the _transp() function performs operations important to the () function
• Introduced multinomial softmax decision model
• Improved documentation for hgfar1mab model
• Added error IDs for all errors

v3.0

• Improved error handling in tapas_fitModel()
• Prefixed all function names with “tapas_”
• Added rs_precision
• Added rs_belief
• Added rs_surprise
• Added sutton_k1
• Added hgfar1mab
• Added softmax for continuous responses
• Improved checking of trajectory validity in HGF models
• Debugged input handling in softmax_binary

v2.1

• Introduced Bayesian parameter averaging
• Amended calculation of log-priors in fitModel.m
• Debugged construction of time axis in hgf_plotTraj
• Debugged removal of placeholder field in estimate structure

v2.0

• Estimation of Bayes optimal parameters added
• infStates the same 3-dim array in hgf_binary as in hgf
• Changes to softmax_binary: trial-by-trial rewards read from input matrix
• hgf_binary generalized to n levels
• Old hgfbinary lives on as hgfbinary3l
• Input at irregular intervals enabled in hgf and hgf_binary
• Support for constant drift in hgf and hgf_binary
• Introduced use of placeholders in config files
• quasinewton_optim: increased default maximum number of regularizations to 16
• Automatic detection of upper bound on theta for hgf
• Improved input checks
• Support for AR(1) processes in new hgf_ar1
• quasinewton_optim: improved resetting after exhaustion of regularizations

v1.0

• Original release