diff --git a/docs/source/conf.py b/docs/source/conf.py index 921086940..39d6d7bb8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -49,6 +49,7 @@ "myst_nb", "sphinxcontrib.bibtex", "sphinx_togglebutton", + "sphinx_design" ] panels_add_bootstrap_css = False @@ -110,7 +111,7 @@ }, } -myst_enable_extensions = ["dollarmath"] +myst_enable_extensions = ["dollarmath", "colon_fence"] html_sidebars = { "api": [], @@ -130,3 +131,5 @@ "python": ("https://docs.python.org/3", None), "jax": ("https://jax.readthedocs.io/en/latest", None), } + + diff --git a/docs/source/index.md b/docs/source/index.md index d222c30b1..580b8cd17 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -52,7 +52,7 @@ The pyhgf package includes pre-implemented standard HGF models that can be used ### Model fitting -Here we demonstrate how to fit a two-level binary Hierarchical Gaussian filter. The input time series are binary outcome from {cite:p}`2013:iglesias`. +Here we demonstrate how to fit a two-level binary Hierarchical Gaussian filter. The input time series are binary outcome from {cite:p}`Iglesias2021`. ```python from pyhgf.model import HGF @@ -96,7 +96,7 @@ This implementation of the Hierarchical Gaussian Filter was largely inspired by --- hidden: --- -Tutorials <tutorials.md> +Learn <learn.md> API <api.rst> Cite <cite.md> References <references.md> diff --git a/docs/source/learn.md b/docs/source/learn.md new file mode 100644 index 000000000..03118af53 --- /dev/null +++ b/docs/source/learn.md @@ -0,0 +1,136 @@ +# Learn + +```{toctree} +--- +hidden: +glob: +--- + +.notebooks/*.md + +``` + +## Theory + +::::{grid} 2 + +:::{grid-item-card} Creating and manipulating networks of probabilistic nodes +:link: {ref}`probabilistic_networks` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/networks.png + +How to create and manipulate a network of probabilistic nodes for reinforcement learning? Working at the intersection of graphs, neural networks and probabilistic frameworks. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0-Creating_networks.ipynb) + +::: + +:::{grid-item-card} An introduction to the Hierarchical Gaussian Filter +:link: {ref}`theory` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/hgf.png + + +How the generative model of the Hierarchical Gaussian filter can be turned into update functions that update nodes through value and volatility coupling? + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0-Theory.ipynb) +::: +:::: + + +## Tutorials + +::::{grid} 3 + +:::{grid-item-card} The binary Hierarchical Gaussian Filter +:link: {ref}`binary_hgf` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/binary.png + +Introducing with example the binary Hierarchical Gaussian filter and its applications to reinforcement learning. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/1.1-Binary_HGF.ipynb) +::: + +:::{grid-item-card} The continuous Hierarchical Gaussian Filter +:link: {ref}`continuous_hgf` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/hgf.png + + +Introducing with example the continuous Hierarchical Gaussian filter and its applications to signal processing. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/1.2-Continuous_HGF.ipynb) +::: + +:::{grid-item-card} The categorical Hierarchical Gaussian Filter +:link: {ref}`categorical_hgf` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/binary.png + + +Introducing the categorical Hierarchical Gaussian Filter as a generalisation of the binary version. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/1.´3-CAtegorical_HGF.ipynb) +::: + +::: + +:::{grid-item-card} Using custom response functions +:link: {ref}`custom_response_functions` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/binary.png + + +How to adapt any model to specific behaviours and experimental design by using custom response functions. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/2-Using_custom_response_functions.ipynb) +::: + +::: + +:::{grid-item-card} Embedding the Hierarchical Gaussian Filter in a Bayesian network for multilevel inference +:link: {ref}`multilevel_hgf` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/binary.png + + +How to use any model as a distribution to perform hierarchical inference at the group level. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/3-Multilevel_HGF.ipynb) +::: + +:::{grid-item-card} Embedding the Hierarchical Gaussian Filter in a Bayesian network for multilevel inference +:link: {ref}`parameters_recovery` +:link-type: ref +:img-top: https://github.com/ilabcode/pyhgf/blob/master/docs/source/images/binary.png + + +How to use any model as a distribution to perform hierarchical inference at the group level. + ++++ +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/4-Parameter_recovery.ipynb) +::: +:::: + +## Use cases + +| Notebook | Colab | +| --- | ---| +| {ref}`example_1` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/Example_1_Heart_rate_variability.ipynb) +| {ref}`example_2` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/Example_2_Input_node_volatility_coupling.ipynb) + +## Exercises + +Hand-on exercises to build intuition around the main components of the HGF and use an agent that optimizes its action under noisy observations. + +| Notebook | Colab | +| --- | ---| +| {ref}`hgf_exercises` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/Exercise_1_Using_the_HGF.ipynb) \ No newline at end of file diff --git a/docs/source/notebooks/0-Creating_networks.ipynb b/docs/source/notebooks/0-Creating_networks.ipynb index 2379a2325..072a8866d 100644 --- a/docs/source/notebooks/0-Creating_networks.ipynb +++ b/docs/source/notebooks/0-Creating_networks.ipynb @@ -14,7 +14,12 @@ "(probabilistic_networks)=\n", "# Creating and manipulating networks of probabilistic nodes\n", "\n", - "[pyhgf](https://ilabcode.github.io/pyhgf/index.html#) is designed with inspiration from graph neural network libraries that can support message-passing schemes and performs beliefs propagation through networks of probabilistic nodes. Here, this principle is applied to predictive processing and focuses on networks that are structured as **rooted trees** and perform variational message passing to update beliefs about the state of the environment, inferred from the observations at the root of the tree. While this library is optimized to implement the standard two-level and three-level HGF {cite:p}`2011:mathys,2014:mathys`, as well as the generalized HGF {cite:p}`weber:2023`, it can also be applied to much larger use cases, with the idea is to generalize belief propagation as it has been described so far to larger and more complex networks that will capture a greater variety of environmental structure. Therefore, the library is also designed to facilitate the creation and manipulation of such probabilistic networks. Importantly, here we consider that a probabilistic network should be defined by the following four variables:\n", + "---\n", + "Open an interactive version of this notebook here: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0-Creating_networks.ipynb).\n", + "\n", + "---\n", + "\n", + "[pyhgf](https://ilabcode.github.io/pyhgf/index.html#) is designed with inspiration from graph neural network libraries that can support message-passing schemes and perform belief propagation through networks of probabilistic nodes. Here, this principle is applied to predictive processing and focuses on networks that are structured as **rooted trees** and perform variational message passing to update beliefs about the state of the environment, inferred from the observations at the root of the tree. While this library is optimized to implement the standard two-level and three-level HGF {cite:p}`2011:mathys,2014:mathys`, as well as the generalized HGF {cite:p}`weber:2023`, it can also be applied to much larger use cases, with the idea is to generalize belief propagation as it has been described so far to larger and more complex networks that will capture a greater variety of environmental structure. Therefore, the library is also designed to facilitate the creation and manipulation of such probabilistic networks. Importantly, here we consider that a probabilistic network should be defined by the following four variables:\n", "1. the network parameters\n", "2. the network structure\n", "3. the update function(s)\n", @@ -53,7 +58,7 @@ "\n", "$$\\mathcal{F} = \\{f_1, ..., f_n\\}$$\n", "\n", - "In this set, each update function is linked to a node from the node indexes $n \\in 1, ..., k$ to which the function should apply. The most standard uses of the HGF only require continuous and/or binary update functions for input and states node that can be found in the {ref}`pyhgf.continuous` and {ref}`pyhgf.binary` sub-modules.\n", + "In this set, each update function is linked to a node from the node indexes $n \\in 1, ..., k$ to which the function should apply. The most standard uses of the HGF only require continuous and/or binary update functions for input and states node that can be found in the {py:func}`pyhgf.updates` sub-module.\n", "\n", "The dynamic of belief propagation dynamics (which part of the network should be updated and in which order) are controlled by the ordered update sequence\n", "\n", @@ -1480,7 +1485,7 @@ ")\n", "```\n", "\n", - "The HGF class include a built-in {ref}`pyhgf.modeal.HGF.get_update_sequence` method to automatically generate the update sequence from the network structure, assuming that we want to propagate the beliefs from the lower part of the tree (the input nodes) to its upper part (nodes that do not have parents)." + "The HGF class include a built-in {py:func}`pyhgf.model.HGF.get_update_sequence` method to automatically generate the update sequence from the network structure, assuming that we want to propagate the beliefs from the lower part of the tree (the input nodes) to its upper part (nodes that do not have parents)." ] }, { diff --git a/docs/source/notebooks/0-Creating_networks.md b/docs/source/notebooks/0-Creating_networks.md index 8f8228f5c..1d9521f1c 100644 --- a/docs/source/notebooks/0-Creating_networks.md +++ b/docs/source/notebooks/0-Creating_networks.md @@ -17,7 +17,12 @@ kernelspec: (probabilistic_networks)= # Creating and manipulating networks of probabilistic nodes -[pyhgf](https://ilabcode.github.io/pyhgf/index.html#) is designed with inspiration from graph neural network libraries that can support message-passing schemes and performs beliefs propagation through networks of probabilistic nodes. Here, this principle is applied to predictive processing and focuses on networks that are structured as **rooted trees** and perform variational message passing to update beliefs about the state of the environment, inferred from the observations at the root of the tree. While this library is optimized to implement the standard two-level and three-level HGF {cite:p}`2011:mathys,2014:mathys`, as well as the generalized HGF {cite:p}`weber:2023`, it can also be applied to much larger use cases, with the idea is to generalize belief propagation as it has been described so far to larger and more complex networks that will capture a greater variety of environmental structure. Therefore, the library is also designed to facilitate the creation and manipulation of such probabilistic networks. Importantly, here we consider that a probabilistic network should be defined by the following four variables: +--- +Open an interactive version of this notebook here: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0-Creating_networks.ipynb). + +--- + +[pyhgf](https://ilabcode.github.io/pyhgf/index.html#) is designed with inspiration from graph neural network libraries that can support message-passing schemes and perform belief propagation through networks of probabilistic nodes. Here, this principle is applied to predictive processing and focuses on networks that are structured as **rooted trees** and perform variational message passing to update beliefs about the state of the environment, inferred from the observations at the root of the tree. While this library is optimized to implement the standard two-level and three-level HGF {cite:p}`2011:mathys,2014:mathys`, as well as the generalized HGF {cite:p}`weber:2023`, it can also be applied to much larger use cases, with the idea is to generalize belief propagation as it has been described so far to larger and more complex networks that will capture a greater variety of environmental structure. Therefore, the library is also designed to facilitate the creation and manipulation of such probabilistic networks. Importantly, here we consider that a probabilistic network should be defined by the following four variables: 1. the network parameters 2. the network structure 3. the update function(s) @@ -46,7 +51,7 @@ The way beliefs are being updated, or the type of generic computation that is pe $$\mathcal{F} = \{f_1, ..., f_n\}$$ -In this set, each update function is linked to a node from the node indexes $n \in 1, ..., k$ to which the function should apply. The most standard uses of the HGF only require continuous and/or binary update functions for input and states node that can be found in the {ref}`pyhgf.continuous` and {ref}`pyhgf.binary` sub-modules. +In this set, each update function is linked to a node from the node indexes $n \in 1, ..., k$ to which the function should apply. The most standard uses of the HGF only require continuous and/or binary update functions for input and states node that can be found in the {py:func}`pyhgf.updates` sub-module. The dynamic of belief propagation dynamics (which part of the network should be updated and in which order) are controlled by the ordered update sequence @@ -423,7 +428,7 @@ update_sequence = ( ) ``` -The HGF class include a built-in {ref}`pyhgf.modeal.HGF.get_update_sequence` method to automatically generate the update sequence from the network structure, assuming that we want to propagate the beliefs from the lower part of the tree (the input nodes) to its upper part (nodes that do not have parents). +The HGF class include a built-in {py:func}`pyhgf.model.HGF.get_update_sequence` method to automatically generate the update sequence from the network structure, assuming that we want to propagate the beliefs from the lower part of the tree (the input nodes) to its upper part (nodes that do not have parents). +++ diff --git a/docs/source/notebooks/0-Theory.md b/docs/source/notebooks/0-Theory.md index b2a485473..d244746da 100644 --- a/docs/source/notebooks/0-Theory.md +++ b/docs/source/notebooks/0-Theory.md @@ -305,7 +305,7 @@ Hierarchical Gaussian Filters are inspired by other simpler models for Bayesian ### The propagation of prediction and prediction errors -Having described the model as a specific configuration of predictive nodes offer many advantages, especially in term of modularity for the user. However, the model itself is not limited to the description of the generative process that we covered in the previous examples. The most interesting, and also the more complex, part of the modelling consists of the capability for the network to update the hierarchical structure in a Bayesian optimal way as new observations are presented. These steps are defined by a set of simple, one-step update equations that represent changes in beliefs about the hidden states (i.e. the sufficient statistics of the nodes) specified in the generative model. These equations were first described in {cite:t}`2011:mathys`, and the update equations for volatility and value coupling in the generalized Hierarchical Gaussian filter (on which most of the update functions in [pyhgf](https://github.com/ilabcode/pyhgf) are based) have been described in {cite:p}`weber:2023`. The exact computations in each step especially depend on the nature of the coupling (via {term}`VAPE`s vs. {term}`VOPE`s) between the parent and children nodes. It is beyond the scope of this tutorial to dive into the derivation of these steps and we refer the interested reader to the mentioned papers. Here, we provide a general overview of the dynamic of the update sequence that supports belief updating. The computations triggered by any observation at each time point can be ordered in time as shown in the [belief update algorithm](#belief-update). +Having described the model as a specific configuration of predictive nodes offer many advantages, especially in term of modularity for the user. However, the model itself is not limited to the description of the generative process that we covered in the previous examples. The most interesting, and also the more complex, part of the modelling consists of the capability for the network to update the hierarchical structure in a Bayesian optimal way as new observations are presented. These steps are defined by a set of simple, one-step update equations that represent changes in beliefs about the hidden states (i.e. the sufficient statistics of the nodes) specified in the generative model. These equations were first described in {cite:t}`2011:mathys`, and the update equations for volatility and value coupling in the generalized Hierarchical Gaussian filter (on which most of the update functions in [pyhgf](https://github.com/ilabcode/pyhgf) are based) have been described in {cite:p}`weber:2023`. The exact computations in each step especially depend on the nature of the coupling (via {term}`VAPE`s vs. {term}`VOPE`s) between the parent and children nodes. It is beyond the scope of this tutorial to dive into the derivation of these steps and we refer the interested reader to the mentioned papers. Here, we provide a general overview of the dynamic of the update sequence that supports belief updating. The computations triggered by any observation at each time point can be ordered in time as shown in the belief update algorithm. +++ diff --git a/docs/source/tutorials.md b/docs/source/tutorials.md deleted file mode 100644 index e1c1c9b47..000000000 --- a/docs/source/tutorials.md +++ /dev/null @@ -1,44 +0,0 @@ -# Tutorials - -```{toctree} ---- -hidden: -glob: ---- - -.notebooks/*.md - -``` - -## How does it work? - -| Notebook | Colab | -| --- | ---| -| {ref}`probabilistic_networks` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0-Creating_networks.ipynb) -| {ref}`theory` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0-Theory.ipynb) - -## Using the Hierarchical Gaussian Filter - -| Notebook | Colab | -| --- | ---| -| {ref}`binary_hgf` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/1.1-Binary_HGF.ipynb) -| {ref}`continuous_hgf` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/1.2-Continuous_HGF.ipynb) -| {ref}`categorical_hgf` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/1.´3-CAtegorical_HGF.ipynb) -| {ref}`custom_response_functions` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/2-Using_custom_response_functions.ipynb) -| {ref}`multilevel_hgf` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/3-Multilevel_HGF.ipynb) -| {ref}`parameters_recovery` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/4-Parameter_recovery.ipynb) - -## Use cases - -| Notebook | Colab | -| --- | ---| -| {ref}`example_1` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/Example_1_Heart_rate_variability.ipynb) -| {ref}`example_2` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/Example_2_Input_node_volatility_coupling.ipynb) - -## Exercises - -Hand-on exercises to build intuition around the main components of the HGF and use an agent that optimizes its action under noisy observations. - -| Notebook | Colab | -| --- | ---| -| {ref}`hgf_exercises` | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/Exercise_1_Using_the_HGF.ipynb) \ No newline at end of file diff --git a/requirements-docs.txt b/requirements-docs.txt index 43879c5f1..2d96cd2fc 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -12,4 +12,5 @@ graphviz watermark systole bokeh==2.3.2 -sphinx-togglebutton \ No newline at end of file +sphinx-togglebutton +sphinx-design \ No newline at end of file