Notebook documentation

figures/MAM2EBRAINS/M2E_visualize_fc.py

@@ -90,7 +90,9 @@ def matrix_plot(M, ax, matrix, index, vlim, pos=None):
     ax.set_ylabel('Cortical area', size=14)
 
 
-def visualize_fc(M, data_path, label):
+def visualize_fc(M, data_path):
+    label = M.simulation.label
+
     # compute functional connectivity
     compute_fc(M, data_path, label)
     compute_communities(M, data_path, label)

multi-area-model.ipynb

@@ -53,11 +53,11 @@
     "    * [2.1. Configuring model parameters](#section_2_1)\n",
     "    * [2.2. Instantiate a multi-area model](#section_2_2)\n",
     "    * [2.3. Predict firing rates from theory](#section_2_3)\n",
-    "    * [2.4. Extract and visualize interareal connectivity](#section_2_3)\n",
+    "    * [2.4. Extract and visualize inter-areal connectivity](#section_2_3)\n",
     "    * [2.5. Run a simulation](#section_2_5)\n",
     "* [S3. Visualization of Network Dynamics](#section_3) \n",
     "    * [3.1. Mean firing rate over simulated populations](#section_3_1)\n",
-    "    * [3.2. Normalized instantaneous firing rate over simulated areas](#section_3_2)\n",
+    "    * [3.2. Instantaneous firing rate over simulated areas](#section_3_2)\n",
     "    * [3.3. Time-averaged firing rate over all populations](#section_3_3)\n",
     "    * [3.4. Network dynamics](#section_3_4)\n",
     "    * [3.5. Functional connectivity](#section_3_5)\n",
@@ -161,6 +161,14 @@
     "### 1.1. Parameters to tune <a class=\"anchor\" id=\"section_1_1\"></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "9daf88e5-0d45-4529-a228-70c33900b05e",
+   "metadata": {},
+   "source": [
+    "The values assigned for the following parameters are kept the same as in the paper except for the `scale_down_to` which is set as 0.006 enabling to simulate a down-scaled multi-area model with 2GB RAM. By default, it's set as 1.0 for simulating the full-scame model."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "4f67c1ba",
@@ -169,7 +177,7 @@
     "|Parameter        |Default value|Value range/options|Value assigned|Description|\n",
     "|:---------------:|:-----------:|:-----------------:|:------------:|:---------:|\n",
     "|scale_down_to    |$1.0$        |$(0, 1.0]$         |$0.006$       |$^1$       |\n",
-    "|cc_weights_factor|$1.0$        |$[1.0, 2.5]$       |$1.9$         |$^2$       |\n",
+    "|cc_weights_factor|$1.9$        |$[1.0, 2.5]$       |$1.9$         |$^2$       |\n",
     "|areas_simulated  |complete_area_list|Sublists of complete_area_list|complete_area_list|$^3$|\n",
     "|replace_non_simulated_areas|None|None, 'hom_poisson_stat', 'het_poisson_stat', 'het_current_nonstat'|'het_poisson_stat'|$^4$ |\n",
     "|g        |$-11.0$|$\\leq -1.0$ |$-11.0$ |$^5$ |\n",
@@ -183,7 +191,7 @@
    "source": [
     "1. `scale_down_to` is the down-scaling factor that defines the ratio by which the full-scale multi-area model is reduced to a model with fewer neurons and indegrees. This reduction is essential to enable simulation on machines with limited computational power, ensuring that simulation results can be obtained in a relatively shorter timeframe. <br> If the value is `scale_down_to = 1.`, the full-scale network will be simulated. <br> In the pre-set down-scaled version, `scale_down_to = 0.006`. This setting reduces the number of neurons and indegrees to 0.6 % of their full-scale counterparts, facilitating simulation on a typical local machine. <br> **Warning**: This may not yield reasonable results from the network dynamics and is only meant to demonstrate the simulation workflow! <br> \n",
     "\n",
-    "2. `cc_weights_factor` is the scaling factor that controls the cortico-cortical synaptic strength. <br> By default it is set to `1.0`, ensuring that inter- and intra-area synapses have equal strength. <br> **Important**: This factor plays a crucial role in transitioning the network activity from the ground to the metastable state.  In the full-scale network, the ground state and metastable state activities are achieved when this parameter is set to `1.0` and `1.9`, respectively.<br>\n",
+    "2. `cc_weights_factor` is the scaling factor that controls the cortico-cortical synaptic strength. <br> By default it is set to `1.9`, keeping the same value for producing the metastable state as in the original paper. <br> **Important**: This factor plays a crucial role in transitioning the network activity from the ground to the metastable state.  In the full-scale network, the ground state and metastable state activities are achieved when this parameter is set to `1.0` and `1.9`, respectively.<br>\n",
     "\n",
     "3. `areas_simulated` specifies the cortical areas to be included in the simulation process. Its default value is `complete_area_list` meaning all the areas in the complete_area_list will be simulated.\n",
     "```python\n",
@@ -195,7 +203,7 @@
     "\n",
     "5. `g` defines the relative inhibitory synaptic strength (in relative units to the excitatory synaptic strength). By default: `-11.0`, as used in the full-scale network. `g = -1.0` means equal excitatory and inhibitory strengths, and `g < -1.0` results in stronger inhibition than excitation.\n",
     "\n",
-    "6. `rate_ext` defines the rate of the Poissonian spike generator (in spikes/s), by default: `10.0`. It also serves as one of the input parameters of the model. When a larger value is assigned to `rate_ext`, the excitatory background noise is increased."
+    "6. `rate_ext` defines the rate of the Poissonian spike generator (in spikes/s), by default: `10.0`. It also serves as one of the input parameters of the model. When a larger value is assigned to `rate_ext`, the excitatory background noise is increased. Note that the external Poisson indegree onto 5E and 6E is increased by a factor of 1.125 and 1.41666667 repectively, and the external Poisson indegree onto 23E and 5E in area TH is increased by a factor of 1.2."
    ]
   },
   {
@@ -206,18 +214,17 @@
    "outputs": [],
    "source": [
     "# Downscaling factor\n",
-    "# Value range/options: (0, 1.], change it to 1. to run the full-scale network\n",
+    "# value range/options: (0, 1.], change it to 1. to simulate the full-scale network\n",
     "scale_down_to = 0.006\n",
     "\n",
     "# Scaling factor for cortico-cortical connections (Chi) \n",
-    "# Value range/options: [1., 2.5], \n",
-    "# A weight factor of 1.0 produces Ground state activity.\n",
-    "# A value larger than 1. reproduces the \"Metastable\" state activity, \n",
+    "# value range/options: [1., 2.5], \n",
+    "# a weight factor of 1.0 produces Ground state activity.\n",
     "# 1.9 was assigned to produce results in Schmidt et al. (2018).\n",
     "cc_weights_factor = 1.9\n",
     "\n",
     "# Cortical areas included in the simulation\n",
-    "# Value range/options: any sublist of complete_area_list\n",
+    "# value range/options: any sublist of complete_area_list\n",
     "# where complete_area_list is\n",
     "complete_area_list = ['V1', 'V2', 'VP', 'V3', 'V3A', 'MT', 'V4t', 'V4', 'VOT', 'MSTd',\n",
     "                      'PIP', 'PO', 'DP', 'MIP', 'MDP', 'VIP', 'LIP', 'PITv', 'PITd',\n",
@@ -227,8 +234,8 @@
     "# areas_simulated = ['V1', 'V2']\n",
     "\n",
     "# Firing rates used to replace the non-simulated areas\n",
-    "# Value range/options: None, 'hom_poisson_stat', 'het_poisson_stat', 'het_current_nonstat'\n",
-    "# If areas_simulated is complete_area_list, then replace_non_simulated_areas will be set as None \n",
+    "# value range/options: None, 'hom_poisson_stat', 'het_poisson_stat', 'het_current_nonstat'\n",
+    "# if areas_simulated is complete_area_list, then replace_non_simulated_areas will be set as None \n",
     "# regardless of the value assigned below\n",
     "replace_non_simulated_areas = 'het_poisson_stat'\n",
     "\n",
@@ -296,7 +303,7 @@
     "# Determine cc_weights_I_factor from cc_weights_factor\n",
     "if cc_weights_factor == 1.0:                                                  # For ground state with cc_weights_factor as 1., \n",
     "    cc_weights_I_factor = 1.0                                                 # cc_weights_I_factor is set to 1.\n",
-    "elif cc_weights_factor > 1.0 and cc_weights_factor <= 2.5:                    # For metastable state with cc_weights_factor in (1., 2.5],\n",
+    "elif cc_weights_factor > 1.0 and cc_weights_factor <= 2.5:                    # For cc_weights_factor in (1., 2.5],\n",
     "    cc_weights_I_factor = 2.0                                                 # cc_weights_I_factor is set to 2.\n",
     "else:                                                                         # cc_weights_factor outside of (1., 2.5], raise error\n",
     "    raise Exception(\"A value in range [1.0, 2.5] should be assigned to the parameter cc_weights_factor!\")\n",
@@ -371,6 +378,14 @@
     "### 2.3. Predict firing rates from theory <a class=\"anchor\" id=\"section_2_3\"></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "07cc84bf-dbcf-4ac3-b76e-ebe0886b4012",
+   "metadata": {},
+   "source": [
+    "Note: the prediction may differ from the simulation results, especially in the presence of synchrony."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -397,7 +412,15 @@
    "id": "2062ddf3",
    "metadata": {},
    "source": [
-    "### 2.4. Extract and visualize interareal connectivity <a class=\"anchor\" id=\"section_2_4\"></a>"
+    "### 2.4. Extract and visualize inter-areal connectivity <a class=\"anchor\" id=\"section_2_4\"></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "53cc3cdd-e623-4adc-8ae5-a36775417892",
+   "metadata": {},
+   "source": [
+    "The inter-areal connectivity of the model is expressed as the relative indegrees for each target area. The relative indegrees for each target area are calculated as following: the value in the cell showing the stregnth of connection from a source area to a target area is calculated as the indegree from the source area to the target area divided by the sum of all indegrees to the target area."
    ]
   },
   {
@@ -406,15 +429,15 @@
    "metadata": {},
    "source": [
     "The connectivity and neuron numbers are stored in the attributes of the model class. \n",
-    "- Neuron numbers are stored in `M.N` as a dictionary (and in `M.N_vec` as an array).\n",
+    "- Neuron numbers of all populations in each area are stored in `M.N` as a dictionary (and in `M.N_vec` as an array).\n",
     "\n",
     "- Indegrees are stored in `M.K` as a dictionary (and in `M.K_matrix` as an array).<br>\n",
     "  Dictionary of nodes indegrees organized as:<br>\n",
-    "  `{<source_area>: {<source_pop>: {<target_area>: {<target_pop>: indegree_values}}}}`\n",
+    "  `{<target_area>: {<target_pop>: {<source_area>: {<source_pop>: indegree_values}}}}`\n",
     "\n",
     "- Number of synapses can be accessed via `M.synapses` (and in `M.syn_matrix` as an array). <br>\n",
     "  Dictionary of synapses that target neurons receive, it is organized as:<br>\n",
-    "  `{<source_area>: {<source_pop>: {<target_area>: {<target_pop>: number_of_synapses}}}}`"
+    "  `{<target_area>: {<target_pop>: {<source_area>: {<source_pop>: number_of_synapses}}}}`"
    ]
   },
   {
@@ -541,7 +564,7 @@
     "tags": []
    },
    "source": [
-    "### 3.2. Normalized instantaneous firing rate over simulated areas <a class=\"anchor\" id=\"section_3_2\"></a>"
+    "### 3.2. Instantaneous firing rate over simulated areas <a class=\"anchor\" id=\"section_3_2\"></a>"
    ]
   },
   {
@@ -612,8 +635,8 @@
    },
    "outputs": [],
    "source": [
-    "# Choose at most 3 areas from the areas_simulated to show their sipking activities\n",
-    "# By default, it's set as ['V1', 'V2', 'FEF'] when all areas from complete_area_list are simulated\n",
+    "# Choose at most 3 areas from the areas_simulated to show their spiking activities\n",
+    "# By default, the list is ['V1', 'V2', 'FEF'] when all areas from complete_area_list are simulated\n",
     "raster_areas = ['V1', 'V2', 'FEF']\n",
     "\n",
     "from M2E_visualize_dynamics import visual_dynamics\n",
@@ -633,7 +656,7 @@
    "id": "013adaf8-af8b-470e-94f0-b69121d1ca2c",
    "metadata": {},
    "source": [
-    "Comparison of inter-area interactions of the down-scaled MAM visualized as functional connectivity and experimental data. (A) Simulated functional connectivity (FC) for w = 1.9 measured by the zero-time-lag correlation coefficient of synaptic input currents. (B) FC of macaque resting-state fMRI (see Materials and methods)."
+    "Comparison of area-level functional connectivity (FC) between the down-scaled MAM and macaque experimental data. (A) Simulated FC measured by the zero-time-lag correlation coefficient of synaptic input currents. (B) FC of macaque resting-state fMRI (see Materials and methods)."
    ]
   },
   {
@@ -653,8 +676,7 @@
    "outputs": [],
    "source": [
     "from M2E_visualize_fc import visualize_fc\n",
-    "label = M.simulation.label\n",
-    "visualize_fc(M, data_path, label)"
+    "visualize_fc(M, data_path)"
    ]
   },
   {