Merge pull request #173 from CCS-Lab/docs/hgf

Add article: Hierarchical Bayesian Analysis on Hierarchical Gaussian Filter

Author: bugoverdose

Python/hbayesdm/models/_hgf_ibrb.py

@@ -54,11 +54,11 @@ def __init__(self, **kwargs):
                 ('mu0', 'prior belief for each level before starting the experiment'),
                 ('sigma0', 'prior uncertainty for each level before starting the experiment'),
                 ('kappa_lower', 'Lower bounds for kappa for each level (2 ~ L-1). Defaults to [0] and can not be negative. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].'),
-                ('kappa_upper', 'Upper bounds for kappa for each level (2 ~ L-1). Defaults to [3]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].'),
+                ('kappa_upper', 'Upper bounds for kappa for each level (2 ~ L-1). Defaults to [2]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].'),
                 ('omega_lower', 'Lower bounds for omega for each level (2 ~ L). Defaults to [-10. -15]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].'),
-                ('omega_upper', 'Upper bounds for omega for each level (2 ~ L). Defaults to [5, 5]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].'),
+                ('omega_upper', 'Upper bounds for omega for each level (2 ~ L). Defaults to [0, 0]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].'),
                 ('zeta_lower', 'Upper bound for zeta. Defaults to 0 and can not be negative. Parameter value is fixed if zeta_lower == zeta_upper.'),
-                ('zeta_upper', 'Upper bound for zeta. Defaults to 3. Parameter value is fixed if zeta_lower == zeta_upper.'),
+                ('zeta_upper', 'Upper bound for zeta. Defaults to 2. Parameter value is fixed if zeta_lower == zeta_upper.'),
             ]),
             **kwargs,
         )
@@ -211,11 +211,11 @@ def hgf_ibrb(
         - ``mu0``: prior belief for each level before starting the experiment
         - ``sigma0``: prior uncertainty for each level before starting the experiment
         - ``kappa_lower``: Lower bounds for kappa for each level (2 ~ L-1). Defaults to [0] and can not be negative. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].
-        - ``kappa_upper``: Upper bounds for kappa for each level (2 ~ L-1). Defaults to [3]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].
+        - ``kappa_upper``: Upper bounds for kappa for each level (2 ~ L-1). Defaults to [2]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].
         - ``omega_lower``: Lower bounds for omega for each level (2 ~ L). Defaults to [-10. -15]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].
-        - ``omega_upper``: Upper bounds for omega for each level (2 ~ L). Defaults to [5, 5]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].
+        - ``omega_upper``: Upper bounds for omega for each level (2 ~ L). Defaults to [0, 0]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].
         - ``zeta_lower``: Upper bound for zeta. Defaults to 0 and can not be negative. Parameter value is fixed if zeta_lower == zeta_upper.
-        - ``zeta_upper``: Upper bound for zeta. Defaults to 3. Parameter value is fixed if zeta_lower == zeta_upper.
+        - ``zeta_upper``: Upper bound for zeta. Defaults to 2. Parameter value is fixed if zeta_lower == zeta_upper.
 
     Returns
     -------

Python/hbayesdm/models/_hgf_ibrb_single.py

@@ -41,23 +41,23 @@ def __init__(self, **kwargs):
                 ('mu0', [0.5, 1.0]),
                 ('sigma0', [0.1, 1.0]),
                 ('kappa_lower', [0]),
-                ('kappa_upper', [3]),
+                ('kappa_upper', [2]),
                 ('omega_lower', [-10, -15]),
-                ('omega_upper', [5, 5]),
+                ('omega_upper', [0, 0]),
                 ('zeta_lower', 0),
-                ('zeta_upper', 3),
+                ('zeta_upper', 2),
             ]),
             additional_args_desc=OrderedDict([
                 ('L', 'Total level of hierarchy. Defaults to minimum level of 3'),
                 ('input_first', 'TRUE if participant observed u[t] before choosing y[t], FALSE if participant observed u[t] after choosing y[t]'),
                 ('mu0', 'prior belief for each level before starting the experiment'),
                 ('sigma0', 'prior uncertainty for each level before starting the experiment'),
                 ('kappa_lower', 'Lower bounds for kappa for each level (2 ~ L-1). Defaults to [0] and can not be negative. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].'),
-                ('kappa_upper', 'Upper bounds for kappa for each level (2 ~ L-1). Defaults to [3]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].'),
+                ('kappa_upper', 'Upper bounds for kappa for each level (2 ~ L-1). Defaults to [2]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].'),
                 ('omega_lower', 'Lower bounds for omega for each level (2 ~ L). Defaults to [-10. -15]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].'),
-                ('omega_upper', 'Upper bounds for omega for each level (2 ~ L). Defaults to [5, 5]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].'),
+                ('omega_upper', 'Upper bounds for omega for each level (2 ~ L). Defaults to [0, 0]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].'),
                 ('zeta_lower', 'Upper bound for zeta. Defaults to 0 and can not be negative. Parameter value is fixed if zeta_lower == zeta_upper.'),
-                ('zeta_upper', 'Upper bound for zeta. Defaults to 3. Parameter value is fixed if zeta_lower == zeta_upper.'),
+                ('zeta_upper', 'Upper bound for zeta. Defaults to 2. Parameter value is fixed if zeta_lower == zeta_upper.'),
             ]),
             **kwargs,
         )
@@ -209,11 +209,11 @@ def hgf_ibrb_single(
         - ``mu0``: prior belief for each level before starting the experiment
         - ``sigma0``: prior uncertainty for each level before starting the experiment
         - ``kappa_lower``: Lower bounds for kappa for each level (2 ~ L-1). Defaults to [0] and can not be negative. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].
-        - ``kappa_upper``: Upper bounds for kappa for each level (2 ~ L-1). Defaults to [3]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].
+        - ``kappa_upper``: Upper bounds for kappa for each level (2 ~ L-1). Defaults to [2]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].
         - ``omega_lower``: Lower bounds for omega for each level (2 ~ L). Defaults to [-10. -15]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].
-        - ``omega_upper``: Upper bounds for omega for each level (2 ~ L). Defaults to [5, 5]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].
+        - ``omega_upper``: Upper bounds for omega for each level (2 ~ L). Defaults to [0, 0]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].
         - ``zeta_lower``: Upper bound for zeta. Defaults to 0 and can not be negative. Parameter value is fixed if zeta_lower == zeta_upper.
-        - ``zeta_upper``: Upper bound for zeta. Defaults to 3. Parameter value is fixed if zeta_lower == zeta_upper.
+        - ``zeta_upper``: Upper bound for zeta. Defaults to 2. Parameter value is fixed if zeta_lower == zeta_upper.
 
     Returns
     -------

R/R/hgf_ibrb.R

@@ -22,11 +22,11 @@
 #' @templateVar ADDITIONAL_ARGS_3 \item{mu0}{prior belief for each level before starting the experiment}
 #' @templateVar ADDITIONAL_ARGS_4 \item{sigma0}{prior uncertainty for each level before starting the experiment}
 #' @templateVar ADDITIONAL_ARGS_5 \item{kappa_lower}{Lower bounds for kappa for each level (2 ~ L-1). Defaults to [0] and can not be negative. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].}
-#' @templateVar ADDITIONAL_ARGS_6 \item{kappa_upper}{Upper bounds for kappa for each level (2 ~ L-1). Defaults to [3]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].}
+#' @templateVar ADDITIONAL_ARGS_6 \item{kappa_upper}{Upper bounds for kappa for each level (2 ~ L-1). Defaults to [2]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].}
 #' @templateVar ADDITIONAL_ARGS_7 \item{omega_lower}{Lower bounds for omega for each level (2 ~ L). Defaults to [-10. -15]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].}
-#' @templateVar ADDITIONAL_ARGS_8 \item{omega_upper}{Upper bounds for omega for each level (2 ~ L). Defaults to [5, 5]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].}
+#' @templateVar ADDITIONAL_ARGS_8 \item{omega_upper}{Upper bounds for omega for each level (2 ~ L). Defaults to [0, 0]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].}
 #' @templateVar ADDITIONAL_ARGS_9 \item{zeta_lower}{Upper bound for zeta. Defaults to 0 and can not be negative. Parameter value is fixed if zeta_lower == zeta_upper.}
-#' @templateVar ADDITIONAL_ARGS_10 \item{zeta_upper}{Upper bound for zeta. Defaults to 3. Parameter value is fixed if zeta_lower == zeta_upper.}
+#' @templateVar ADDITIONAL_ARGS_10 \item{zeta_upper}{Upper bound for zeta. Defaults to 2. Parameter value is fixed if zeta_lower == zeta_upper.}
 #'
 #' @template model-documentation
 #'

R/R/hgf_ibrb_single.R

@@ -21,11 +21,11 @@
 #' @templateVar ADDITIONAL_ARGS_3 \item{mu0}{prior belief for each level before starting the experiment}
 #' @templateVar ADDITIONAL_ARGS_4 \item{sigma0}{prior uncertainty for each level before starting the experiment}
 #' @templateVar ADDITIONAL_ARGS_5 \item{kappa_lower}{Lower bounds for kappa for each level (2 ~ L-1). Defaults to [0] and can not be negative. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].}
-#' @templateVar ADDITIONAL_ARGS_6 \item{kappa_upper}{Upper bounds for kappa for each level (2 ~ L-1). Defaults to [3]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].}
+#' @templateVar ADDITIONAL_ARGS_6 \item{kappa_upper}{Upper bounds for kappa for each level (2 ~ L-1). Defaults to [2]. Parameter value is fixed for level l if kappa_upper[l] == kappa_lower[l].}
 #' @templateVar ADDITIONAL_ARGS_7 \item{omega_lower}{Lower bounds for omega for each level (2 ~ L). Defaults to [-10. -15]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].}
-#' @templateVar ADDITIONAL_ARGS_8 \item{omega_upper}{Upper bounds for omega for each level (2 ~ L). Defaults to [5, 5]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].}
+#' @templateVar ADDITIONAL_ARGS_8 \item{omega_upper}{Upper bounds for omega for each level (2 ~ L). Defaults to [0, 0]. Parameter value is fixed for level l if omega_upper[l] == omega_lower[l].}
 #' @templateVar ADDITIONAL_ARGS_9 \item{zeta_lower}{Upper bound for zeta. Defaults to 0 and can not be negative. Parameter value is fixed if zeta_lower == zeta_upper.}
-#' @templateVar ADDITIONAL_ARGS_10 \item{zeta_upper}{Upper bound for zeta. Defaults to 3. Parameter value is fixed if zeta_lower == zeta_upper.}
+#' @templateVar ADDITIONAL_ARGS_10 \item{zeta_upper}{Upper bound for zeta. Defaults to 2. Parameter value is fixed if zeta_lower == zeta_upper.}
 #'
 #' @template model-documentation
 #'
@@ -56,11 +56,11 @@ hgf_ibrb_single <- hBayesDM_model(
     'mu0' = c(0.5, 1.0),
     'sigma0' = c(0.1, 1.0),
     'kappa_lower' = c(0),
-    'kappa_upper' = c(3),
+    'kappa_upper' = c(2),
     'omega_lower' = c(-10, -15),
-    'omega_upper' = c(5, 5),
+    'omega_upper' = c(0, 0),
     'zeta_lower' = 0,
-    'zeta_upper' = 3
+    'zeta_upper' = 2
   ),
   regressors      = NULL,
   postpreds       = NULL,

R/_pkgdown.yml

@@ -35,8 +35,10 @@ reference:
   - rhat
 
 articles:
-- title: Getting started
-  contents: getting_started
+- title: Tutorial
+  contents: 
+    - getting_started
+    - hgf_tutorial
 
 toc:
   depth: 1

R/vignettes/bibtex/hBayesDM_bib_short.bib

@@ -8,6 +8,20 @@
 %% Saved with string encoding Unicode (UTF-8) 
 
 
+@article{ahn2017hbayesdm,
+	Author       = {Ahn, Woo-Young and Haines, Nathaniel and Zhang, Lei},
+	Date-Added   = {2025-09-02 16:20:00 +0000},
+	Date-Modified= {2025-09-02 16:20:00 +0000},
+	Journal      = {Computational Psychiatry},
+	Pages        = {24--57},
+	Publisher    = {MIT Press},
+	Title        = {Revealing Neurocomputational Mechanisms of Reinforcement Learning and Decision-Making With the hBayesDM Package},
+	Volume       = {1},
+	Year         = {2017},
+	Month        = {October},
+	DOI          = {10.1162/CPSY\_a\_00002},
+	PMID         = {29601060},
+	PMCID        = {PMC5869013}}
 
 @article{aylward2018,
 	Author = {Aylward, Jessica and Valton, Vincent and Ahn, Woo-Young and Bond, Rebecca L and Dayan, Peter and Roiser, Jonathan P and Robinson, Oliver J},
@@ -28,6 +42,63 @@ @article{mathys2011bayesian
 	Volume = {5},
 	Year = {2011}}
 
+@article{mathys2014hgf,
+	Author = {Mathys, Christoph and Lomakina, Ekaterina I and Daunizeau, Jean and Iglesias, Susana and Brodersen, Kay H and Friston, Karl J and Stephan, Klaas Enno},
+	Date-Added = {2025-09-01 19:00:00 +0000},
+	Date-Modified = {2025-09-01 19:00:00 +0000},
+	Journal = {Frontiers in Human Neuroscience},
+	Pages = {825},
+	Publisher = {Frontiers},
+	Title = {Uncertainty in perception and the Hierarchical Gaussian Filter},
+	Volume = {8},
+	Year = {2014}}
+
+@article{tecilla2023modulation,
+	Author       = {Tecilla, Margherita and Großbach, Michael and Gentile, Giovanni and Holland, Peter and Sporn, Sebastian and Antonini, Angelo and Herrojo Ruiz, Maria},
+	Date-Added   = {2025-09-01 19:00:00 +0000},
+	Date-Modified= {2025-09-01 19:00:00 +0000},
+	Journal      = {Journal of Neuroscience},
+	Pages        = {1757--1777},
+	Publisher    = {Society for Neuroscience},
+	Title        = {Modulation of Motor Vigor by Expectation of Reward Probability Trial-by-Trial Is Preserved in Healthy Ageing and Parkinson's Disease Patients},
+	Volume       = {43},
+	Number       = {10},
+	Year         = {2023},
+	Month        = {Mar},
+	Day          = {8},
+	DOI          = {10.1523/JNEUROSCI.1583-22.2022},
+	PMID         = {36732072},
+	PMCID        = {PMC10010462}}
+
+@article{hein2021state,
+	Author       = {Hein, Thomas P. and de Fockert, Jan and Herrojo Ruiz, Maria},
+	Date-Added   = {2025-09-01 19:00:00 +0000},
+	Date-Modified= {2025-09-01 19:00:00 +0000},
+	Journal      = {NeuroImage},
+	Pages        = {117424},
+	Publisher    = {Elsevier},
+	Title        = {State anxiety biases estimates of uncertainty and impairs reward learning in volatile environments},
+	Volume       = {224},
+	Year         = {2021},
+	DOI          = {10.1016/j.neuroimage.2020.117424},
+	ISSN         = {1053-8119},
+	URL          = {https://www.sciencedirect.com/science/article/pii/S1053811920309095},
+	Keywords     = {Anxiety, Uncertainty, Hierarchical Bayesian inference, Computational modeling, Precision-weighted prediction error, Single-trial EEG}}
+
+@article{reed2020paranoia,
+	Author       = {Reed, Emily J and Uddenberg, Stefan and Suthaharan, Praveen and Mathys, Christoph D and Taylor, John R and Groman, Stephanie M and Corlett, Philip R},
+	Date-Added   = {2025-09-02 00:00:00 +0000},
+	Date-Modified= {2025-09-02 00:00:00 +0000},
+	Journal      = {Elife},
+	Title        = {Paranoia as a deficit in non-social belief updating},
+	Volume       = {9},
+	Year         = {2020},
+	Month        = {May},
+	Day          = {26},
+	DOI          = {10.7554/eLife.56345},
+	PMID         = {32452769},
+	PMCID        = {PMC7326495}}
+
 @article{bishara2010sequential,
 	Author = {Bishara, Anthony J and Kruschke, John K and Stout, Julie C and Bechara, Antoine and McCabe, David P and Busemeyer, Jerome R},
 	Date-Added = {2018-09-11 18:59:00 +0000},
@@ -565,3 +636,26 @@ @article{Busemeyer2000a
 	Title = {Model Comparisons and Model Selections Based on Generalization Criterion Methodology},
 	Volume = {44},
 	Year = {2000}}
+
+@article{heathcote2015goodpractices,
+	Author       = {Heathcote, Andrew and Brown, Scott D. and Wagenmakers, Eric-Jan},
+	Date-Added   = {2025-09-02 16:40:00 +0000},
+	Date-Modified= {2025-09-02 16:40:00 +0000},
+	Journal      = {Cognitive Science},
+	Pages        = {1069--1080},
+	Title        = {An Introduction to Good Practices in Cognitive Modeling},
+	Volume       = {39},
+	Number       = {5},
+	Year         = {2015}}
+
+@article{wilson2019tenrules,
+	Author       = {Wilson, Robert C and Collins, Anne GE},
+	Date-Added   = {2025-09-02 00:00:00 +0000},
+	Date-Modified= {2025-09-02 00:00:00 +0000},
+	Journal      = {eLife},
+	Pages        = {e49547},
+	Publisher    = {eLife Sciences Publications},
+	Title        = {Ten simple rules for the computational modeling of behavioral data},
+	Volume       = {8},
+	Year         = {2019},
+	DOI          = {10.7554/eLife.49547}}

R/vignettes/getting_started.Rmd

@@ -29,7 +29,7 @@ We introduce a free R package **hBayesDM**, which offers HBA of various computat
 
 ## Why hierarchical Bayesian analysis (HBA)?
 
-![](images/HBA_concept.png)
+![](images/getting_started/HBA_concept.png)
 
 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.
 
@@ -116,7 +116,7 @@ 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.
 
 
-![](images/hBayesDM_pipeLine.png)
+![](images/getting_started/hBayesDM_pipeLine.png)
 
 
 ### 1) Prepare the data
@@ -418,13 +418,12 @@ axis(side=2, at = c(0,1) )
 legend("bottomleft", legend=c("True", "PPC"), col=c("black", "red"), lty=1:2)
 ```
 
-![](images/PPC.png)
+![](images/getting_started/PPC.png)
 
 ## To-do list
 
 We are planning to add more tasks/models. We plan to include the following tasks and/or models in the near future. If you have any requests for a specific task or a model, please let us know.
 
-* Hierarchical Gaussian Filtering [@mathys2011bayesian].
 * More sequential sampling models (e.g., drift diffusion models with different drift rates for multiple conditions).
 * Models for the passive avoidance learning task [@newman1986passive; @Newman1985].
 * Models for the Stop Signal Task (SST)