use explicit descriptions instead of greek letters (#114)

README.md

@@ -63,9 +63,9 @@ u, _ = load_data("binary")
 hgf = HGF(
     n_levels=2,
     model_type="binary",
-    initial_mu={"1": .0, "2": .5},
-    initial_pi={"1": .0, "2": 1e4},
-    omega={"2": -3.0},
+    initial_mean={"1": .0, "2": .5},
+    initial_precision={"1": .0, "2": 1e4},
+    tonic_volatility={"2": -3.0},
 )
 
 # add new observations

docs/source/index.md

@@ -66,9 +66,9 @@ u, _ = load_data("binary")
 hgf = HGF(
     n_levels=2,
     model_type="binary",
-    initial_mu={"1": .0, "2": .5},
-    initial_pi={"1": .0, "2": 1e4},
-    omega={"2": -3.0},
+    initial_mean={"1": .0, "2": .5},
+    initial_precision={"1": .0, "2": 1e4},
+    tonic_volatility={"2": -3.0},
 )
 
 # add new observations

docs/source/notebooks/0-Creating_networks.ipynb

@@ -84,7 +84,7 @@
    "outputs": [],
    "source": [
     "from pyhgf.typing import Indexes\n",
-    "parameters = {\"mu\": 0.0, \"pi\": 1.0}\n",
+    "parameters = {\"mean\": 0.0, \"precision\": 1.0}\n",
     "\n",
     "attributes = (parameters, parameters, parameters)\n",
     "edges = (\n",
@@ -99,7 +99,7 @@
    "id": "54c60f31-3554-48d5-906f-484f7b209545",
    "metadata": {},
    "source": [
-    "The code above illustrate the creation of a probabilistic network of 3 nodes with simple parameters sets $(\\mu=0.0, \\pi=1.0)$. Node 2 is the value parent of node 1. Node 3 is the value parent of node 2 and has no parents."
+    "The code above illustrates creating a probabilistic network of 3 nodes with simple parameter sets $(mean = 0.0, precision = 1.0)$. Node 2 is the value parent of node 1. Node 3 is the value parent of node 2 and has no parents."
    ]
   },
   {
@@ -218,7 +218,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "hgf.attributes[3][\"pi\"] = 5.0"
+    "hgf.attributes[3][\"precision\"] = 5.0"
    ]
   },
   {

docs/source/notebooks/0-Creating_networks.md

@@ -5,7 +5,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.7
+    jupytext_version: 1.15.1
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
@@ -66,7 +66,7 @@ One of the advantages of reasoning this way is that it dissociates variables tha
 
 ```{code-cell} ipython3
 from pyhgf.typing import Indexes
-parameters = {"mu": 0.0, "pi": 1.0}
+parameters = {"mean": 0.0, "precision": 1.0}
 
 attributes = (parameters, parameters, parameters)
 edges = (
@@ -76,7 +76,7 @@ edges = (
 )
 ```
 
-The code above illustrate the creation of a probabilistic network of 3 nodes with simple parameters sets $(\mu=0.0, \pi=1.0)$. Node 2 is the value parent of node 1. Node 3 is the value parent of node 2 and has no parents.
+The code above illustrates creating a probabilistic network of 3 nodes with simple parameter sets $(mean = 0.0, precision = 1.0)$. Node 2 is the value parent of node 1. Node 3 is the value parent of node 2 and has no parents.
 
 +++
 
@@ -95,7 +95,7 @@ hgf.plot_network()
 The simpler change we can make on a network is to change the values of some of its parameters. The parameters are stored in the `attributes` variable as a dictionary where the key (integers) are node indexes. Therefore, modifying the expected precision of the third node in the previous example is as simple as:
 
 ```{code-cell} ipython3
-hgf.attributes[3]["pi"] = 5.0
+hgf.attributes[3]["precision"] = 5.0
 ```
 
 However, modifying parameters values *manually* should not be that common as this is something we want the model to perform dynamically as we present new observations, but this can be used for example to generate prior predictive by sampling some parameter values from a distribution. 

docs/source/notebooks/1.1-Binary_HGF.md

@@ -76,9 +76,9 @@ slideshow:
 two_levels_hgf = HGF(
     n_levels=2,
     model_type="binary",
-    initial_mu={"1": .0, "2": .5},
-    initial_pi={"1": .0, "2": 1.0},
-    omega={"2": -3.0},
+    initial_mean={"1": .0, "2": .5},
+    initial_precision={"1": .0, "2": 1.0},
+    tonic_volatility={"2": -3.0},
 )
 ```
 
@@ -142,11 +142,11 @@ Here, we create a new {py:class}`pyhgf.model.HGF` instance, setting the number o
 three_levels_hgf = HGF(
     n_levels=3,
     model_type="binary",
-    initial_mu={"1": .0, "2": .5, "3": 0.},
-    initial_pi={"1": .0, "2": 1.0, "3": 1.0},
-    omega={"1": None, "2": -3.0, "3": -2.0},
-    rho={"1": None, "2": 0.0, "3": 0.0},
-    kappas={"1": None, "2": 1.0},
+    initial_mean={"1": .0, "2": .5, "3": 0.},
+    initial_precision={"1": .0, "2": 1.0, "3": 1.0},
+    tonic_volatility={"1": None, "2": -3.0, "3": -2.0},
+    tonic_drift={"1": None, "2": 0.0, "3": 0.0},
+    volatility_coupling={"1": None, "2": 1.0},
     eta0=0.0,
     eta1=1.0,
     binary_precision=jnp.inf,
@@ -208,11 +208,11 @@ slideshow:
 with pm.Model() as two_levels_binary_hgf:
 
     # Set a prior over the evolution rate at the second level.
-    omega_2 = pm.Uniform("omega_2", -3.5, 0.0)
+    tonic_volatility_2 = pm.Uniform("tonic_volatility_2", -3.5, 0.0)
 
     # Call the pre-parametrized HGF distribution here.
     # All parameters are set to their default value, except omega_2.
-    pm.Potential("hgf_loglike", hgf_logp_op(omega_2=omega_2))
+    pm.Potential("hgf_loglike", hgf_logp_op(tonic_volatility_2=tonic_volatility_2))
 ```
 
 #### Visualizing the model
@@ -229,26 +229,26 @@ with two_levels_binary_hgf:
 ```
 
 ```{code-cell} ipython3
-az.plot_trace(two_level_hgf_idata, var_names=["omega_2"]);
+az.plot_trace(two_level_hgf_idata, var_names=["tonic_volatility_2"]);
 plt.tight_layout()
 ```
 
 ### Using the learned parameters
 To visualize how the model would behave under the most probable values, we average the $\omega_{2}$ samples and use this value in a new model.
 
 ```{code-cell} ipython3
-omega_2 = az.summary(two_level_hgf_idata)["mean"]["omega_2"]
+tonic_volatility_2 = az.summary(two_level_hgf_idata)["mean"]["tonic_volatility_2"]
 ```
 
 ```{code-cell} ipython3
 hgf_mcmc = HGF(
     n_levels=2,
     model_type="binary",
-    initial_mu={"1": jnp.inf, "2": 0.5},
-    initial_pi={"1": 0.0, "2": 1.0},
-    omega={"1": jnp.inf, "2": omega_2},
-    rho={"1": 0.0, "2": 0.0},
-    kappas={"1": 1.0}).input_data(
+    initial_mean={"1": jnp.inf, "2": 0.5},
+    initial_precision={"1": 0.0, "2": 1.0},
+    tonic_volatility={"1": jnp.inf, "2": tonic_volatility_2},
+    tonic_drift={"1": 0.0, "2": 0.0},
+    volatility_coupling={"1": 1.0}).input_data(
         input_data=u
     )
 ```
@@ -287,12 +287,17 @@ slideshow:
 with pm.Model() as three_levels_binary_hgf:
 
      # Set a prior over the evolution rate at the second and third levels.
-    omega_2 = pm.Uniform("omega_2", -4.0, 0.0)
-    omega_3 = pm.Normal("omega_3", -11.0, 2)
+    tonic_volatility_2 = pm.Uniform("tonic_volatility_2", -4.0, 0.0)
+    tonic_volatility_3 = pm.Normal("tonic_volatility_3", -11.0, 2)
 
     # Call the pre-parametrized HGF distribution here.
     # All parameters are set to their default value except omega_2 and omega_3.
-    pm.Potential("hgf_loglike", hgf_logp_op(omega_2=omega_2, omega_3=omega_3))
+    pm.Potential(
+        "hgf_loglike", 
+        hgf_logp_op(
+            tonic_volatility_2=tonic_volatility_2, 
+            tonic_volatility_3=tonic_volatility_3)
+    )
 ```
 
 #### Visualizing the model
@@ -314,27 +319,27 @@ with three_levels_binary_hgf:
 ```
 
 ```{code-cell} ipython3
-az.plot_trace(three_level_hgf_idata, var_names=["omega_2", "omega_3"]);
+az.plot_trace(three_level_hgf_idata, var_names=["tonic_volatility_2", "tonic_volatility_3"]);
 plt.tight_layout()
 ```
 
 ### Using the learned parameters
 To visualize how the model would behave under the most probable values, we average the $\omega_{2}$ samples and use this value in a new model.
 
 ```{code-cell} ipython3
-omega_2 = az.summary(three_level_hgf_idata)["mean"]["omega_2"]
-omega_3 = az.summary(three_level_hgf_idata)["mean"]["omega_3"]
+tonic_volatility_2 = az.summary(three_level_hgf_idata)["mean"]["tonic_volatility_2"]
+tonic_volatility_3 = az.summary(three_level_hgf_idata)["mean"]["tonic_volatility_3"]
 ```
 
 ```{code-cell} ipython3
 hgf_mcmc = HGF(
     n_levels=3,
     model_type="binary",
-    initial_mu={"1": jnp.inf, "2": 0.5, "3": 0.0},
-    initial_pi={"1": 0.0, "2": 1e4, "3": 1e1},
-    omega={"1": jnp.inf, "2": omega_2, "3": omega_3},
-    rho={"1": 0.0, "2": 0.0, "3": 0.0},
-    kappas={"1": 1.0, "2": 1.0}).input_data(
+    initial_mean={"1": jnp.inf, "2": 0.5, "3": 0.0},
+    initial_precision={"1": 0.0, "2": 1e4, "3": 1e1},
+    tonic_volatility={"1": jnp.inf, "2": tonic_volatility_2, "3": tonic_volatility_3},
+    tonic_drift={"1": 0.0, "2": 0.0, "3": 0.0},
+    volatility_coupling={"1": 1.0, "2": 1.0}).input_data(
         input_data=u
     )
 ```

docs/source/notebooks/1.2-Categorical_HGF.md

@@ -124,7 +124,7 @@ tags: [hide-cell]
 ---
 fig, axs = plt.subplots(nrows=5, figsize=(12, 9), sharex=True)
 plot_nodes(categorical_hgf, node_idxs=31, axs=axs[0])
-axs[1].imshow(categorical_hgf.node_trajectories[0]["mu"].T, interpolation="none", aspect="auto")
+axs[1].imshow(categorical_hgf.node_trajectories[0]["mean"].T, interpolation="none", aspect="auto")
 axs[1].set_title("Mean of the implied Dirichlet distribution", loc="left")
 axs[1].set_ylabel("Categories")
 
@@ -191,7 +191,7 @@ def categorical_surprise(omega_2, hgf, input_data):
     for va_pa in hgf.edges[0].value_parents:
         for va_pa_va_pa in hgf.edges[va_pa].value_parents:
             for va_pa_va_pa_va_pa in hgf.edges[va_pa_va_pa].value_parents:
-                hgf.attributes[va_pa_va_pa_va_pa]["omega"] = omega_2
+                hgf.attributes[va_pa_va_pa_va_pa]["tonic_volatility"] = omega_2
 
     # fit the model to new data
     hgf.input_data(input_data=input_data.T)