qol fixes on documentation (#236)

* use the last version of setup-python * add sphinx_design back * remove unnecessary import in notebooks * use chains=2 max in tutorials * use IPython utils to hide Colab installation outputs * links
ComputationalPsychiatry · Sep 14, 2024 · bdafea7 · bdafea7
1 parent f27e0eb
commit bdafea7
Show file tree

Hide file tree

Showing 21 changed files with 121 additions and 78 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.12'
 

diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml
@@ -16,7 +16,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Run lint

diff --git a/.github/workflows/pypi.yml b/.github/workflows/pypi.yml
@@ -10,7 +10,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.12"
 

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -16,7 +16,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - uses: actions/cache@v2

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -44,6 +44,7 @@
     "matplotlib.sphinxext.plot_directive",
     "numpydoc",
     "myst_nb",
+    "sphinx_design",
     "sphinxcontrib.bibtex",
     "sphinx_togglebutton",
     "sphinx_exercise",

diff --git a/docs/source/learn.md b/docs/source/learn.md
@@ -26,6 +26,7 @@ notebooks/1.3-Continuous_HGF.ipynb
 notebooks/2-Using_custom_response_functions.ipynb
 notebooks/3-Multilevel_HGF.ipynb
 notebooks/4-Parameter_recovery.ipynb
+notebooks/5-Non_linear_value_coupling
 ```
 
 ```{toctree}
@@ -67,7 +68,7 @@ How the generative model of the Hierarchical Gaussian filter can be turned into
 :::{grid-item-card}  Creating and manipulating networks of probabilistic nodes
 :link: probabilistic_networks
 :link-type: ref
-:img-top: ./images/graph_networks.svg
+:img-top: ./images/graph_network.svg
 
 How to create and manipulate a network of probabilistic nodes for reinforcement learning? Working at the intersection of graphs, neural networks and probabilistic frameworks.
 :::

diff --git a/docs/source/notebooks/0.1-Theory.ipynb b/docs/source/notebooks/0.1-Theory.ipynb
@@ -34,10 +34,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    ! pip install watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install watermark"
    ]
   },
   {

diff --git a/docs/source/notebooks/0.2-Creating_networks.ipynb b/docs/source/notebooks/0.2-Creating_networks.ipynb
@@ -42,11 +42,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {
@@ -131,7 +132,7 @@
     "\n",
     "This list describes the sequence of function-to-nodes instructions that are executed during the inference and update processes.\n",
     "\n",
-    "![graph_networks](../images/graph_networks.svg)\n",
+    "![graph_network](../images/graph_network.svg)\n",
     "\n",
     "```{tip} Compatibility with JAX transformations\n",
     "One of the advantages of reasoning this way is that it dissociates variables that are transparent to the JAX framework and can be expressed as \"PyTress\" from variables that should be filtered before transformations. The variable `attributes` ($\\theta$) is typically expressed as a PyTree while the other variables that contain parametrized functions are filtered. See [the documattion](https://jax.readthedocs.io/en/latest/notebooks/thinking_in_jax.html#jit-mechanics-tracing-and-static-variables) for further details on JAX transformations.\n",

diff --git a/docs/source/notebooks/0.3-Generalised_filtering.ipynb b/docs/source/notebooks/0.3-Generalised_filtering.ipynb
@@ -17,6 +17,29 @@
     "[![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.3-Generalised_filtering.ipynb)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "31b80846",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": [
+     "hide-cell"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "from IPython.utils import io\n",
+    "if 'google.colab' in sys.modules:\n",
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,

diff --git a/docs/source/notebooks/1.1-Binary_HGF.ipynb b/docs/source/notebooks/1.1-Binary_HGF.ipynb
@@ -38,11 +38,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {
@@ -870,7 +871,7 @@
    ],
    "source": [
     "with two_levels_binary_hgf:\n",
-    "    two_level_hgf_idata = pm.sample(chains=4, cores=1)"
+    "    two_level_hgf_idata = pm.sample(chains=2, cores=1)"
    ]
   },
   {
@@ -1299,7 +1300,7 @@
    ],
    "source": [
     "with three_levels_binary_hgf:\n",
-    "    three_level_hgf_idata = pm.sample(chains=4, cores=1)"
+    "    three_level_hgf_idata = pm.sample(chains=2, cores=1)"
    ]
   },
   {

diff --git a/docs/source/notebooks/1.2-Categorical_HGF.ipynb b/docs/source/notebooks/1.2-Categorical_HGF.ipynb
@@ -36,11 +36,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {

diff --git a/docs/source/notebooks/1.3-Continuous_HGF.ipynb b/docs/source/notebooks/1.3-Continuous_HGF.ipynb
@@ -44,10 +44,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {
@@ -959,7 +961,7 @@
    ],
    "source": [
     "with two_level_hgf:\n",
-    "    two_level_hgf_idata = pm.sample(chains=4, cores=1)"
+    "    two_level_hgf_idata = pm.sample(chains=2, cores=1)"
    ]
   },
   {
@@ -1353,7 +1355,7 @@
    ],
    "source": [
     "with three_level_hgf:\n",
-    "    three_level_hgf_idata = pm.sample(chains=4, cores=1)"
+    "    three_level_hgf_idata = pm.sample(chains=2, cores=1)"
    ]
   },
   {

diff --git a/docs/source/notebooks/2-Using_custom_response_functions.ipynb b/docs/source/notebooks/2-Using_custom_response_functions.ipynb
@@ -44,10 +44,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {
@@ -907,7 +909,7 @@
    ],
    "source": [
     "with sigmoid_hgf:\n",
-    "    sigmoid_hgf_idata = pm.sample(chains=4, cores=1)"
+    "    sigmoid_hgf_idata = pm.sample(chains=2, cores=1)"
    ]
   },
   {

diff --git a/docs/source/notebooks/3-Multilevel_HGF.ipynb b/docs/source/notebooks/3-Multilevel_HGF.ipynb
@@ -50,11 +50,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {
@@ -81,7 +82,6 @@
    ],
    "source": [
     "import arviz as az\n",
-    "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import pymc as pm\n",

diff --git a/docs/source/notebooks/4-Parameter_recovery.ipynb b/docs/source/notebooks/4-Parameter_recovery.ipynb
@@ -44,11 +44,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {

diff --git a/docs/source/notebooks/5-Non_linear_value_coupling.ipynb b/docs/source/notebooks/5-Non_linear_value_coupling.ipynb
@@ -32,11 +32,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {
@@ -56,7 +57,7 @@
     "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
-    "from jax import jit, lax\n",
+    "from jax import lax\n",
     "from pyhgf.model import Network\n",
     "import seaborn as sns\n",
     "\n",

diff --git a/docs/source/notebooks/Example_1_Heart_rate_variability.ipynb b/docs/source/notebooks/Example_1_Heart_rate_variability.ipynb
@@ -44,10 +44,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf systole watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark systole"
    ]
   },
   {

diff --git a/docs/source/notebooks/Example_2_Input_node_volatility_coupling.ipynb b/docs/source/notebooks/Example_2_Input_node_volatility_coupling.ipynb
@@ -44,10 +44,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    !pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {

diff --git a/docs/source/notebooks/Example_3_Multi_armed_bandit.ipynb b/docs/source/notebooks/Example_3_Multi_armed_bandit.ipynb
@@ -44,11 +44,12 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
     "import sys\n",
-    "\n",
+    "from IPython.utils import io\n",
     "if 'google.colab' in sys.modules:\n",
-    "    ! pip install pyhgf watermark"
+    "\n",
+    "  with io.capture_output() as captured:\n",
+    "      ! pip install pyhgf watermark"
    ]
   },
   {