tutorial page

ComputationalPsychiatry · Nov 6, 2023 · 798c33c · 798c33c
1 parent 5465e20
commit 798c33c
Show file tree

Hide file tree

Showing 24 changed files with 146 additions and 200 deletions.
diff --git a/docs/source/images/categorical.png b/docs/source/images/categorical.png
diff --git a/docs/source/images/input_mean_precision.png b/docs/source/images/input_mean_precision.png
diff --git a/docs/source/learn.md b/docs/source/learn.md
@@ -21,21 +21,16 @@ glob:
 
 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: theory
 :link-type: ref
-:img-top: ./images/hgf.png
+:img-top: ./images/trajectories.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)
 :::
 ::::
 
@@ -51,32 +46,27 @@ How the generative model of the Hierarchical Gaussian filter can be turned into
 
 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: continuous_hgf
+:::{grid-item-card}  The categorical Hierarchical Gaussian Filter
+:link: categorical_hgf
 :link-type: ref
-:img-top: ./images/hgf.png
-
+:img-top: ./images/categorical.png
 
-Introducing with example the continuous Hierarchical Gaussian filter and its applications to signal processing.
+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.2-Continuous_HGF.ipynb)
 :::
 
-:::{grid-item-card}  The categorical Hierarchical Gaussian Filter
-:link: categorical_hgf
+:::{grid-item-card}  The continuous Hierarchical Gaussian Filter
+:link: continuous_hgf
 :link-type: ref
-:img-top: ./images/binary.png
+:img-top: ./images/continuous.png
 
 
-Introducing the categorical Hierarchical Gaussian Filter as a generalisation of the binary version.
+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.´3-CAtegorical_HGF.ipynb)
+
 :::
 ::::
 
@@ -86,25 +76,21 @@ Introducing the categorical Hierarchical Gaussian Filter as a generalisation of
 :::{grid-item-card}  Using custom response functions
 :link: custom_response_functions
 :link-type: ref
-:img-top: ./images/binary.png
+:img-top: ./images/response_models.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: multilevel_hgf
 :link-type: ref
-:img-top: ./images/binary.png
+:img-top: ./images/response_models.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
@@ -115,8 +101,6 @@ How to use any model as a distribution to perform hierarchical inference at the
 
 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)
 :::
 ::::
 
@@ -128,17 +112,13 @@ How to use any model as a distribution to perform hierarchical inference at the
 :link: example_1
 :link-type: ref
 
-+++
-[![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)
-
 :::
 
 :::{grid-item-card}  Value and volatility coupling with an input node
 :link: example_2
 :link-type: ref
+:img-top: ./images/input_mean_precision.png
 
-+++
-[![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)
 :::
 ::::
 
@@ -153,8 +133,5 @@ Hand-on exercises to build intuition around the main components of the HGF and u
 :link: hgf_exercises
 :link-type: ref
 
-+++
-[![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)
-
 :::
 ::::
diff --git a/docs/source/notebooks/0-Creating_networks.ipynb b/docs/source/notebooks/0-Creating_networks.ipynb
@@ -15,6 +15,14 @@
     "# Creating and manipulating networks of probabilistic nodes"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e368e07c-2dbb-47df-bf93-f2b8ec3a7e5b",
+   "metadata": {},
+   "source": [
+    "[![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) "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,

diff --git a/docs/source/notebooks/0-Creating_networks.md b/docs/source/notebooks/0-Creating_networks.md
@@ -17,6 +17,10 @@ kernelspec:
 (probabilistic_networks)=
 # Creating and manipulating networks of probabilistic nodes
 
++++
+
+[![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) 
+
 ```{code-cell} ipython3
 ---
 editable: true

diff --git a/docs/source/notebooks/0-Theory.ipynb b/docs/source/notebooks/0-Theory.ipynb
@@ -7,6 +7,9 @@
    "source": [
     "(theory)=\n",
     "# Introduction to the Hierarchical Gaussian Filter\n",
+    "\n",
+    "[![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)\n",
+    "\n",
     "In this notebook, we introduce the main concepts on which the Hierarchical Gaussian Filter (HGF) is based. We describe the main equations and illustrate the examples with Python code. We start with the generative model of the HGF, which describes how the model assumes that the data is being generated. This generative structure is then used to filter the observation (i.e. the sensory part of the model), which is then used by the agent to produce behaviours (i.e. the action part of the model). Next, we show how this model can be \"inverted\" and used by an agent to infer parameter values that generate the sensory inputs. From there, we discuss the notion of prediction error and how derivations of the model can be used to infer probability densities given observed behavioural outcomes."
    ]
   },

diff --git a/docs/source/notebooks/0-Theory.md b/docs/source/notebooks/0-Theory.md
@@ -14,6 +14,9 @@ kernelspec:
 
 (theory)=
 # Introduction to the Hierarchical Gaussian Filter
+
+[![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)
+
 In this notebook, we introduce the main concepts on which the Hierarchical Gaussian Filter (HGF) is based. We describe the main equations and illustrate the examples with Python code. We start with the generative model of the HGF, which describes how the model assumes that the data is being generated. This generative structure is then used to filter the observation (i.e. the sensory part of the model), which is then used by the agent to produce behaviours (i.e. the action part of the model). Next, we show how this model can be "inverted" and used by an agent to infer parameter values that generate the sensory inputs. From there, we discuss the notion of prediction error and how derivations of the model can be used to infer probability densities given observed behavioural outcomes.
 
 ```{code-cell} ipython3

diff --git a/docs/source/notebooks/1.1-Binary_HGF.ipynb b/docs/source/notebooks/1.1-Binary_HGF.ipynb
@@ -9,6 +9,14 @@
     "# The binary Hierarchical Gaussian Filter"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "1258ea53-11fc-4a27-927c-2afc91f4aa12",
+   "metadata": {},
+   "source": [
+    "[![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)"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -92,7 +100,7 @@
     "The node structure corresponding to the two-level and three-level Hierarchical Gaussian Filters are automatically generated from `model_type` and `n_levels` using the nodes parameters provided in the dictionaries. Here we are not performing any optimization so those parameters are fixed to reasonable values.\n",
     "\n",
     "```{note}\n",
-    "The response function used is the binary surprise at each time point ({py:func}`pyhgf.response.binary_surprise`). In other words, at each time point the model try to update its hierarchy to minimize the discrepancy between the expected and real next binary observation. See also [this tutorial](custom_response_functions) to see how to create a custom response function.\n",
+    "The response function used is the binary surprise at each time point ({py:func}`pyhgf.response.first_level_binary_surprise`). In other words, at each time point the model try to update its hierarchy to minimize the discrepancy between the expected and real next binary observation. See also [this tutorial](custom_response_functions) to see how to create a custom response function.\n",
     "```"
    ]
   },

diff --git a/docs/source/notebooks/1.1-Binary_HGF.md b/docs/source/notebooks/1.1-Binary_HGF.md
@@ -15,6 +15,10 @@ kernelspec:
 (binary_hgf)=
 # The binary Hierarchical Gaussian Filter
 
++++
+
+[![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)
+
 ```{code-cell} ipython3
 :tags: [hide-cell]
 
@@ -68,7 +72,7 @@ u, _ = load_data("binary")
 The node structure corresponding to the two-level and three-level Hierarchical Gaussian Filters are automatically generated from `model_type` and `n_levels` using the nodes parameters provided in the dictionaries. Here we are not performing any optimization so those parameters are fixed to reasonable values.
 
 ```{note}
-The response function used is the binary surprise at each time point ({py:func}`pyhgf.response.binary_surprise`). In other words, at each time point the model try to update its hierarchy to minimize the discrepancy between the expected and real next binary observation. See also [this tutorial](custom_response_functions) to see how to create a custom response function.
+The response function used is the binary surprise at each time point ({py:func}`pyhgf.response.first_level_binary_surprise`). In other words, at each time point the model try to update its hierarchy to minimize the discrepancy between the expected and real next binary observation. See also [this tutorial](custom_response_functions) to see how to create a custom response function.
 ```
 
 ```{code-cell} ipython3

diff --git a/docs/source/notebooks/1.2-Categorical_HGF.ipynb b/docs/source/notebooks/1.2-Categorical_HGF.ipynb
diff --git a/docs/source/notebooks/1.3-Continuous_HGF.ipynb b/docs/source/notebooks/1.3-Continuous_HGF.ipynb
@@ -16,36 +16,19 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "d17cddb7-c96a-4697-88b2-f3e56841d8a5",
-   "metadata": {
-    "execution": {
-     "iopub.execute_input": "2023-11-06T08:58:37.370902Z",
-     "iopub.status.busy": "2023-11-06T08:58:37.370549Z",
-     "iopub.status.idle": "2023-11-06T08:58:37.381548Z",
-     "shell.execute_reply": "2023-11-06T08:58:37.380034Z"
-    },
-    "tags": []
-   },
-   "outputs": [],
+   "cell_type": "markdown",
+   "id": "fb99e4b3-b5f6-4393-b6f0-f867d61b1223",
+   "metadata": {},
    "source": [
-    "%%capture\n",
-    "import sys"
+    "[![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)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 38,
    "id": "c9999f8f-9f0c-4a49-acec-4fd316f5af1c",
    "metadata": {
     "editable": true,
-    "execution": {
-     "iopub.execute_input": "2023-11-06T08:58:37.386413Z",
-     "iopub.status.busy": "2023-11-06T08:58:37.386085Z",
-     "iopub.status.idle": "2023-11-06T08:58:41.252526Z",
-     "shell.execute_reply": "2023-11-06T08:58:41.251147Z"
-    },
     "slideshow": {
      "slide_type": ""
     },
@@ -55,6 +38,8 @@
    },
    "outputs": [],
    "source": [
+    "%%capture\n",
+    "import sys\n",
     "import arviz as az\n",
     "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",

diff --git a/docs/source/notebooks/1.3-Continuous_HGF.md b/docs/source/notebooks/1.3-Continuous_HGF.md
@@ -17,10 +17,9 @@ kernelspec:
 (continuous_hgf)=
 # The continuous Hierarchical Gaussian Filter
 
-```{code-cell} ipython3
-%%capture
-import sys
-```
++++
+
+[![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)
 
 ```{code-cell} ipython3
 ---
@@ -29,6 +28,8 @@ slideshow:
   slide_type: ''
 tags: [hide-cell]
 ---
+%%capture
+import sys
 import arviz as az
 import jax.numpy as jnp
 import matplotlib.pyplot as plt

diff --git a/docs/source/notebooks/2-Using_custom_response_functions.ipynb b/docs/source/notebooks/2-Using_custom_response_functions.ipynb
@@ -10,21 +10,11 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "dabd425e-d88b-44f2-a1c2-de47bf0a028d",
-   "metadata": {
-    "execution": {
-     "iopub.execute_input": "2023-11-06T08:59:09.028327Z",
-     "iopub.status.busy": "2023-11-06T08:59:09.028020Z",
-     "iopub.status.idle": "2023-11-06T08:59:09.038575Z",
-     "shell.execute_reply": "2023-11-06T08:59:09.037128Z"
-    }
-   },
-   "outputs": [],
+   "cell_type": "markdown",
+   "id": "1a9a9835-a027-4c14-9649-e7b51545b83d",
+   "metadata": {},
    "source": [
-    "%%capture\n",
-    "import sys"
+    "[![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)"
    ]
   },
   {
@@ -46,6 +36,8 @@
    },
    "outputs": [],
    "source": [
+    "%%capture\n",
+    "import sys\n",
     "import arviz as az\n",
     "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",
@@ -57,7 +49,7 @@
     "from pyhgf.model import HGF\n",
     "\n",
     "if 'google.colab' in sys.modules:\n",
-    "    ! pip install pyhgf\n"
+    "    ! pip install pyhgf"
    ]
   },
   {

diff --git a/docs/source/notebooks/2-Using_custom_response_functions.md b/docs/source/notebooks/2-Using_custom_response_functions.md
@@ -15,17 +15,18 @@ kernelspec:
 (custom_response_functions)=
 # Using custom response models
 
-```{code-cell} ipython3
-%%capture
-import sys
-```
++++
+
+[![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)
 
 ```{code-cell} ipython3
 ---
 editable: true
 slideshow:
   slide_type: ''
 ---
+%%capture
+import sys
 import arviz as az
 import jax.numpy as jnp
 import matplotlib.pyplot as plt

diff --git a/docs/source/notebooks/3-Multilevel_HGF.ipynb b/docs/source/notebooks/3-Multilevel_HGF.ipynb
@@ -10,9 +10,8 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "29119960-b626-4af5-9440-8fd306c20885",
+   "cell_type": "markdown",
+   "id": "ab7fa0a5-7fc9-47b8-96da-4ff5820a8f70",
    "metadata": {
     "execution": {
      "iopub.execute_input": "2023-11-06T08:59:25.111871Z",
@@ -21,10 +20,8 @@
      "shell.execute_reply": "2023-11-06T08:59:25.121477Z"
     }
    },
-   "outputs": [],
    "source": [
-    "%%capture\n",
-    "import sys"
+    "[![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)"
    ]
   },
   {
@@ -44,6 +41,8 @@
    },
    "outputs": [],
    "source": [
+    "%%capture\n",
+    "import sys\n",
     "import arviz as az\n",
     "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",