{ "cells": [ { "cell_type": "markdown", "id": "b365f293-55b6-467d-acdb-ec110988c8fd", "metadata": {}, "source": [ "# Using Customized and External Cell and Channel Models in BioNet" ] }, { "cell_type": "markdown", "id": "88d41f7b-4ff9-4f25-99fd-9bc0c0804fa5", "metadata": {}, "source": [ "Through the main tutorials, we've been using networks built off cell models downloaded from the [Allen Cell-Types Database](https://celltypes.brain-map.org/data). While the Allen Cell-Types Databases has a comprehensive and continuingly growing selection of optimized cell-type models to download and use, for many scientists, it may not meet their needs. BMTK supports incorporating many cell types and synaptic models into their simulations, including pre-built models from non-Allen Institute organizations. It also allows users multiple ways to create their customized models. \n", "\n", "This section will focus on single-cell spiking models, including conductance-based models with multiple channels and/or compartments per model. We do not recommend using Rates-based models with BioNet, and they will likely not work.\n", "\n", "The following section will show users multiple ways to import or create their own networks and simulations. Many of the multi-compartment biophysically detailed models developed for the NEURON simulator are written in [.hoc](https://www.neuron.yale.edu/neuron/static/new_doc/programming/hocsyntax.html) format. Another popular format is [NeuroML v2](https://docs.neuroml.org/Userdocs/NeuroMLv2.html). In other cases, models may be written in Python. BioNet supports these options and allows users to readily implement other options, too.\n", "\n", "If you are unfamiliar with how and where to find cell and channel models that have been created by other scientists, two good options to start looking at are:\n", "\n", "1. [ModelDB](https://modeldb.science/)\n", "\n", "2. [Open Source Brain](https://v2.opensourcebrain.org/)\n", "\n", "\n", "**Note** - scripts and files for running this tutorial can be found in the directory [01_opt_external_models/](https://github.com/AllenInstitute/bmtk/tree/develop/docs/tutorial/01_opt_external_models)" ] }, { "cell_type": "markdown", "id": "a08c7955-0ed7-427a-a7eb-dbf97e212cc8", "metadata": {}, "source": [ "## 1. Cell Models" ] }, { "cell_type": "markdown", "id": "406d9391-8865-44a6-ba50-16dc2df98a3b", "metadata": {}, "source": [ "### 1.1. Example: Loading in a Simple Hoc Model " ] }, { "cell_type": "markdown", "id": "392eeeb2-95f7-44c6-a75f-6a2a8c20dc3c", "metadata": {}, "source": [ "\n", "##### Step 1: \n", "\n", "**Note**: *This step has already been done in the current notebook and does not need to be repeated, but may be useful when initializing other examples*\n", "\n", "The first thing we'll do is to download and unpack the model files from ModelDB, which for the Hay L5PC models can be found at [https://modeldb.science/139653](https://modeldb.science/139653). At the site, you can use the download button to download a zip file with the appropriate .hoc (cell model), .mod (ion channels), and .asc (morphologies) files.\n", "\n", "\n", "
\n", "
\n", " \n", "
\n", "
\n", "\n", "To run properly, we will need to move the following files from the download zip file into our **components/** folder so BMTK will be able to find them during the simulation:\n", "* Move **mod/** folder => **componets/mechanisms/mod/**.\n", "* Move **morphologies/\\*.asc** files => **components/morphologies/** folder.\n", "* Move **models/L5PCtemplate.hoc** and **models/L5PCbiophys4.hoc** => **componets/templates/** folder (*note*: The zip file contains four different version of L5PCbiophys model stored in different hoc files. However, only one can be loaded into NEURON at a time, hence we are only moving one of the files and not all of them).\n", " \n" ] }, { "cell_type": "markdown", "id": "b89a7c1e-8b28-4db5-bf96-9598dc3d8bb0", "metadata": {}, "source": [ "The model contains customized ion channels in the **components/mechanisms/mod/** folder that require compiling using the `nrnivmod` command. In a shell or using jupyter notebook you'll need to run the following:" ] }, { "cell_type": "code", "execution_count": 1, "id": "933ad3b3-d8ea-4b14-add0-554f3723571b", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "/home/shared/workspace/docs/tutorial/01_opt_external_models/components/mechanisms\n", "Mod files: \"modfiles/CaDynamics.mod\" \"modfiles/CaDynamics_E2.mod\" \"modfiles/Ca_HVA.mod\" \"modfiles/Ca_LVA.mod\" \"modfiles/Ca_LVAst.mod\" \"modfiles/Cav2_1.mod\" \"modfiles/Cav3_1.mod\" \"modfiles/Cav3_2.mod\" \"modfiles/Cav3_3.mod\" \"modfiles/Gfluct.mod\" \"modfiles/HCN1_Angeloetal2007.mod\" \"modfiles/Ih.mod\" \"modfiles/Im.mod\" \"modfiles/Im_v2.mod\" \"modfiles/K_P.mod\" \"modfiles/K_Pst.mod\" \"modfiles/K_T.mod\" \"modfiles/K_Tst.mod\" \"modfiles/Kca11.mod\" \"modfiles/Kca22.mod\" \"modfiles/Kca31.mod\" \"modfiles/Kd.mod\" \"modfiles/Kir23.mod\" \"modfiles/Kv11.mod\" \"modfiles/Kv15.mod\" \"modfiles/Kv2like.mod\" \"modfiles/Kv33.mod\" \"modfiles/Kv34.mod\" \"modfiles/Kv3_1.mod\" \"modfiles/Kv43.mod\" \"modfiles/Leak.mod\" \"modfiles/NaTa.mod\" \"modfiles/NaTa_t.mod\" \"modfiles/NaTg.mod\" \"modfiles/NaTs.mod\" \"modfiles/NaTs2_t.mod\" \"modfiles/NaV.mod\" \"modfiles/Nap.mod\" \"modfiles/Nap_Et2.mod\" \"modfiles/Nav16.mod\" \"modfiles/PC_Gaba_det_vi_alfa1.mod\" \"modfiles/PURKINJE_Ampa_det_vi.mod\" \"modfiles/ProbAMPANMDA2.mod\" \"modfiles/ProbUDFsyn2.mod\" \"modfiles/SK.mod\" \"modfiles/SK_E2.mod\" \"modfiles/SKv3_1.mod\" \"modfiles/cdp5_CAM.mod\" \"modfiles/epsp.mod\" \"modfiles/exp1isyn.mod\" \"modfiles/exp1syn.mod\" \"modfiles/stp1syn.mod\" \"modfiles/stp2syn.mod\" \"modfiles/stp3syn.mod\" \"modfiles/stp4syn.mod\" \"modfiles/stp5isyn.mod\" \"modfiles/stp5syn.mod\" \"modfiles/vecevent.mod\"\n", "\n", "COBJS=''\n", " -> \u001b[32mCompiling\u001b[0m mod_func.c\n", "gcc -O2 -I. -I/opt/conda/envs/bmtk/lib/python3.9/site-packages/neuron/.data/include -I/nrnwheel/openmpi/include -fPIC -c mod_func.c -o mod_func.o\n", " => \u001b[32mLINKING\u001b[0m shared library ./libnrnmech.so\n", "g++ -O2 -DVERSION_INFO='8.0.0' -std=c++11 -shared -fPIC -I /opt/conda/envs/bmtk/lib/python3.9/site-packages/neuron/.data/include -o ./libnrnmech.so -Wl,-soname,libnrnmech.so \\\n", " ./mod_func.o ./CaDynamics.o ./CaDynamics_E2.o ./Ca_HVA.o ./Ca_LVA.o ./Ca_LVAst.o ./Cav2_1.o ./Cav3_1.o ./Cav3_2.o ./Cav3_3.o ./Gfluct.o ./HCN1_Angeloetal2007.o ./Ih.o ./Im.o ./Im_v2.o ./K_P.o ./K_Pst.o ./K_T.o ./K_Tst.o ./Kca11.o ./Kca22.o ./Kca31.o ./Kd.o ./Kir23.o ./Kv11.o ./Kv15.o ./Kv2like.o ./Kv33.o ./Kv34.o ./Kv3_1.o ./Kv43.o ./Leak.o ./NaTa.o ./NaTa_t.o ./NaTg.o ./NaTs.o ./NaTs2_t.o ./NaV.o ./Nap.o ./Nap_Et2.o ./Nav16.o ./PC_Gaba_det_vi_alfa1.o ./PURKINJE_Ampa_det_vi.o ./ProbAMPANMDA2.o ./ProbUDFsyn2.o ./SK.o ./SK_E2.o ./SKv3_1.o ./cdp5_CAM.o ./epsp.o ./exp1isyn.o ./exp1syn.o ./stp1syn.o ./stp2syn.o ./stp3syn.o ./stp4syn.o ./stp5isyn.o ./stp5syn.o ./vecevent.o -L/opt/conda/envs/bmtk/lib/python3.9/site-packages/neuron/.data/lib -lnrniv -Wl,-rpath,/opt/conda/envs/bmtk/lib/python3.9/site-packages/neuron/.data/lib \n", "rm -f ./.libs/libnrnmech.so ; mkdir -p ./.libs ; cp ./libnrnmech.so ./.libs/libnrnmech.so\n", "Successfully created x86_64/special\n" ] } ], "source": [ "! cd components/mechanisms && nrnivmodl modfiles" ] }, { "cell_type": "markdown", "id": "9674554b-2bdb-4454-81d6-43cf6f9fe082", "metadata": {}, "source": [ "##### Step 2: Building the Network\n", "\n", "Building a network using the downloaded L5PC Hay model is very similar to how we built biophysically detailed network models in [previous tutorials](https://github.com/AllenInstitute/bmtk/blob/develop/docs/tutorial/tutorial_02_single_cell_syn.ipynb). We use the `add_nodes()` method to add a population of 1 or more L5PC `biophysical` cells and the `add_edges()` to connect them up with other cells. However, due to the model type and parameters, we will need to make some changes compared to how we utilize Allen-Cell Types Database models.\n", "\n", "* We set **model_template**=`hoc:L5PCtemplate` instead of the Allen `ctdb:Biophys1` value. The name of the Hoc Template for loading this particular model comes from the components/templates/L5PCtemplate.hoc file\n", "* In our Allen Cell-Types models, we had set the value **model_processing** to 'aibs_perisomatic', which told bmtk to call the special post-intialization directive `aibs_perisomatic`, which would modify each cell object in a specific manner. Although it is possible to create custom directives to update and modify each cell after the template has been loaded (see below), we don't want to do so. Instead, we leave the model_processing attribute blank.\n", "* In our Allen Cell-Types models, we also had a **dynamics_params** option that would update and add cell parameters after the cell had been initialized. However, for our L5PC Hay model, we have no current need to update the parameters (we'll instead use the parameter values stored in the .hoc files), so we will not have any dynamics_params attributes.\n", " " ] }, { "cell_type": "code", "execution_count": 2, "id": "ef2cc58c-6104-48ab-9c90-8c2ae3366597", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "WARNING:root:No edges have been made for this network, skipping saving of edges file.\n" ] } ], "source": [ "from bmtk.builder.networks import NetworkBuilder\n", "\n", "net = NetworkBuilder('L5')\n", "net.add_nodes(\n", " N=10,\n", " model_type='biophysical',\n", " model_template='hoc:L5PCtemplate',\n", " morphology='cell3.asc'\n", ")\n", "net.build()\n", "net.save(output_dir='network_L5')" ] }, { "cell_type": "code", "execution_count": 3, "id": "0f5ce031-8c95-4d89-846e-cba00e282ab1", "metadata": {}, "outputs": [], "source": [ "virt_exc = NetworkBuilder('virt_exc')\n", "virt_exc.add_nodes(\n", " N=20,\n", " model_type='virtual',\n", " ei_type='exc'\n", ")\n", "conns = virt_exc.add_edges(\n", " source=virt_exc.nodes(),\n", " target=net.nodes(),\n", " connection_rule=12,\n", " model_template='Exp2Syn',\n", " dynamics_params='AMPA_ExcToExc.json',\n", " distance_range=[0.0, 1.0e20],\n", " target_sections=['soma', 'basal', 'apical'],\n", " delay=2.0,\n", " syn_weight=0.01\n", ")\n", "\n", "virt_exc.build()\n", "virt_exc.save(output_dir='network_L5')" ] }, { "cell_type": "markdown", "id": "630bbd89-4ba9-4878-be1e-11a7e90ad732", "metadata": {}, "source": [ "##### Step 3: Running the simulation\n", "\n", "Running the simulation with the downloaded L5PC models is no different than running the simulations with the Allen Cell-Types Database cell models. BMTK will be able to use the configuration **components** sections along with the **model_template** and **morphology** values to automatically load in our 10 L5PC cells. The results for these cells, including spikes, Vm traces, etc., will be saved in the same format and paths as our other examples." ] }, { "cell_type": "code", "execution_count": 4, "id": "6a5659ff-4ec4-4f4a-afd2-16291b8b6738", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:09,287 [INFO] Created log file\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Created log file\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "numprocs=1\n", "2024-10-21 18:38:09,412 [INFO] Building cells.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building cells.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:16,890 [INFO] Building recurrent connections\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building recurrent connections\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:16,902 [INFO] Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:16,982 [INFO] Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:16,984 [INFO] Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:16,986 [INFO] Block save every 5000 steps\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Block save every 5000 steps\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:30,278 [INFO] step:5000 t_sim:500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:5000 t_sim:500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:43,513 [INFO] step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:38:56,897 [INFO] step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:10,212 [INFO] step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:10,249 [INFO] Simulation completed in 53.27 seconds \n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Simulation completed in 53.27 seconds \n" ] } ], "source": [ "from bmtk.simulator import bionet\n", "\n", "bionet.reset()\n", "conf = bionet.Config.from_json('config.L5.json')\n", "conf.build_env()\n", "\n", "net = bionet.BioNetwork.from_config(conf)\n", "sim = bionet.BioSimulator.from_config(conf, network=net)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "83ef2b8f-4c81-48ec-b8f6-faa3a07cfaa7", "metadata": {}, "source": [ "### 1.2. Example: Modifying Model Initialization " ] }, { "cell_type": "markdown", "id": "0c24a66f-8db0-44b0-948e-c4dbf9f93210", "metadata": {}, "source": [ "If we search Open Source Brain, we can see other more recent versions of [L5 Pyramidal Cell models based on the original L5PC Hay model](https://v2.opensourcebrain.org/repositories/2180). Suppose we wanted to incorporate these newer models alongside the original L5 PC network created above. We would need to do the following:\n", "1. Download the [files](https://github.com/OpenSourceBrain/267587/tree/master/Single%20Cell%20Modelling/Current-Step%20Simulations/L5Pyr_young)\n", "2. Move the morphology, mode, and model template files to their appropriate location\n", "3. Since these files also include new .mod files, we would have to recompile them:\n", "```bash\n", " $ cd components/mechanisms && nrnivmodl modfiles\n", "```\n", "\n", "The newer models have a different morphology file (`Hl5PN1.swc`) and HOC Template name (`HNTemplate`). So in order to add these new cells to the old one we can add the following call in our build script (**build_network.L5_updated.py**):\n", "\n", "```python\n", "net.add_nodes(\n", " N=5,\n", " model_type='biophysical',\n", " model_template='hoc:HNTemplate',\n", " morphology='HL5PN1.swc'\n", ")\n", "```\n", "\n", "*Note: We'll also modify the script to write the network to a different directory*\n" ] }, { "cell_type": "markdown", "id": "1d73fd45-d720-42d8-81da-7bb889872012", "metadata": {}, "source": [ "We could try to run the **L5_updated** model like before, but it would throw an error\n", "\n", "
\n", "⚠️ NEURON: init not enough arguments\n", "
\n", "\n", "The Reason: **We are not calling the HNTemplate correctly.**" ] }, { "cell_type": "markdown", "id": "cbae5da5-3592-4020-a4cb-51e53284cac7", "metadata": {}, "source": [ "If we look through the code and the documentation, we can see that, to instantiate an HNTemplate cell model instance, we must pass two parameters: The morphology file and the cell-type (one of a preset number of string values that will determine how specific properties are set within the model). In this case, the call would look like:\n", "\n", "```python\n", " h.HNTemplate(morphology_file_path, \"HL5PN1\")\n", "```\n", "\n", "The built-in BMTK function that tries to load hoc files, [loadHOC](https://github.com/AllenInstitute/bmtk/blob/develop/bmtk/simulator/bionet/default_setters/cell_models.py#L43), does not know how to load this specific template. And even if it did, you may run into other models that require different, unseen ways of initialization. \n", "\n", "While it is possible to overwrite the `loadHOC` function, it is not ideal. To avoid breaking existing models, we would need to have multiple cases based on each possible template." ] }, { "cell_type": "markdown", "id": "0dcb4381-0ca6-4460-8973-bac09438a69b", "metadata": {}, "source": [ "**Solution**\n", "\n", "Instead of using one function to load in every template, we can create our own custom function to load the HNTemplate. To achieve this, BMTK uses a special [python decorator](https://peps.python.org/pep-0318/) to assign to function users have written (in either the notebook or run_bionet.py script). Below, we show an example of how to do this using a custom function we'll call loadHNTemplate():" ] }, { "cell_type": "code", "execution_count": 5, "id": "861c2dfc-ce17-420b-b5e1-beb294996ff5", "metadata": {}, "outputs": [], "source": [ "from neuron import h\n", "from bmtk.simulator.bionet import cell_model\n", "from bmtk.simulator.bionet.io_tools import io\n", "\n", "@cell_model(directive='hoc:HNTemplate', model_type='biophysical')\n", "def loadHNTemplate(cell, template_name, dynamics_params):\n", " io.log_info(f'Calling loadHNTemplate() for cell {cell[\"node_id\"]}, template {template_name}')\n", " hobj = h.HNTemplate(cell['morphology'], \"HL5PN1\")\n", " return hobj" ] }, { "cell_type": "markdown", "id": "8f99de13-a200-445e-b70a-bd2b3fbdd08e", "metadata": {}, "source": [ " * The `@cell_model` is a decorator we put at the front of our function. Using `directive=hoc:Template` and `model_type=biophysical` parameters indicates to BMTK that whenever a cell model needs to be built for a *biophysical*, *HNTemplate* hoc template, it will use this function.\n", " * Our function requires three parameters;\n", " * The `cell` parameter contains attributes of each individual cell and can be used to extract properties like the morphology file, the node-id, coordinates, etc.\n", " * The `template_name` is, in this case, just the string value \"HNTemplate\"\n", " * The `dynamics_params` is a dictionary from the **dynamics_params** json or hdf5. In this network, we never set the dynamics_params attributes, so the value will be None.\n", " * We need to return either a hoc-object or some other Python class built using the NEURON API.\n", " * For a sanity check, we also included a log statement. We should only see this message for the 5 newer HNTemplate models, not for the other original \"L5PCTemplate\" cells.\n", "\n", "\n", "During simulation, this function will be called for every cell with matching \"template_name\" and \"model_type\"." ] }, { "cell_type": "code", "execution_count": 6, "id": "d315eb04-6c0f-415b-aedd-21a8c8253ba8", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:10,266 [INFO] Created log file\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Created log file\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Mechanisms already loaded from path: ./components/mechanisms. Aborting.\n", "2024-10-21 18:39:10,335 [INFO] Building cells.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building cells.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:14,153 [INFO] Calling loadHNTemplate() for cell 5, template HNTemplate\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Calling loadHNTemplate() for cell 5, template HNTemplate\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:14,377 [INFO] Calling loadHNTemplate() for cell 6, template HNTemplate\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Calling loadHNTemplate() for cell 6, template HNTemplate\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:14,596 [INFO] Calling loadHNTemplate() for cell 7, template HNTemplate\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Calling loadHNTemplate() for cell 7, template HNTemplate\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:14,813 [INFO] Calling loadHNTemplate() for cell 8, template HNTemplate\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Calling loadHNTemplate() for cell 8, template HNTemplate\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:15,043 [INFO] Calling loadHNTemplate() for cell 9, template HNTemplate\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Calling loadHNTemplate() for cell 9, template HNTemplate\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:15,258 [INFO] Building recurrent connections\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building recurrent connections\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:15,282 [INFO] Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:15,346 [INFO] Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:15,347 [INFO] Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:15,348 [INFO] Block save every 5000 steps\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Block save every 5000 steps\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:35,798 [INFO] step:5000 t_sim:500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:5000 t_sim:500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:39:56,404 [INFO] step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:17,730 [INFO] step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:38,490 [INFO] step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:38,524 [INFO] Simulation completed in 83.18 seconds \n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Simulation completed in 83.18 seconds \n" ] } ], "source": [ "bionet.reset()\n", "conf = bionet.Config.from_json('config.L5_updated.json')\n", "conf.build_env()\n", "\n", "net = bionet.BioNetwork.from_config(conf)\n", "sim = bionet.BioSimulator.from_config(conf, network=net)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "76b4dafc-4f86-4013-aee0-3188269e5a43", "metadata": {}, "source": [ "### 1.3. Example: Loading a python-based neuronal model into your simulation " ] }, { "cell_type": "markdown", "id": "fc168bf2-4487-40a7-96b0-b00ad0748336", "metadata": {}, "source": [ "Often, rather than being written in old .hoc format, scientists may instead release their models written in Python. For example, in this [mouse Purkinje cell model](https://github.com/OpenSourceBrain/267694/tree/main/mouse_model), the model is itself saved in the `Purkinje_morph_1.Purkinje_Morph_1` Python class. In nearly the same manner as we did with the .hoc files above, we can import these Python-based single-cell models into our network to use with BMTK.\n", "\n", "As before, we must download the necessary files, but in this case, the *.py files, including the file containing the cell-model class/template, should be in the same directory as our `run_bionet.py` script so that we may import it. Also, the Python script expects the .asc morphology file to be hard-coded in the path **./morphology/soma_10c.asc**, so we'll put it there instead of the normal components directory (unless you want to edit the file).\n" ] }, { "cell_type": "markdown", "id": "629ba385-8115-498c-bb3f-d900047ddba2", "metadata": {}, "source": [ "When we build our population of Purkinje cells, the \"model_template\" will have schema value `python` and a value that is just the name of the resources, e.g., the python class `Purkinje_morph_1`.\n", "\n", "```\n", "net.add_nodes( \n", " pop_name='Scnn1a',\n", " model_type='biophysical',\n", " model_template='python:Purkinje_morph_1',\n", " spines_on=0\n", ")\n", "```\n", "\n", "So that BMTK can load the template, we will once again register a special function using the `cell_model` decorator. The class can be built with or without dendritic spines, which we are required to pass in. The `__init__` method of `Purkinje_Morpho_1` will build the model for each given cell, which we will pass back to BTMK.\n", "\n", "Also, for good measure, we added some optional logging." ] }, { "cell_type": "code", "execution_count": 7, "id": "4d416c2d-a536-408a-bd35-c476e846d547", "metadata": {}, "outputs": [], "source": [ "from bmtk.simulator import bionet\n", "from bmtk.simulator.bionet.io_tools import io\n", "from Purkinje_morpho_1 import Purkinje_Morpho_1\n", "\n", "@bionet.cell_model(directive='python:Purkinje_morph_1', model_type='biophysical')\n", "def loadPurkinjeModel(cell, template_name, dynamics_params):\n", " io.log_info(f'Loading cell {cell.node_id}, template {template_name}, with spines_on={cell[\"spines_on\"]}')\n", " cell = Purkinje_Morpho_1(cell['spines_on'])\n", " return cell" ] }, { "cell_type": "code", "execution_count": 8, "id": "004d316b-6f4f-4d99-b521-ece8c51c9bdc", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:38,556 [INFO] Created log file\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Created log file\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Mechanisms already loaded from path: ./components/mechanisms. Aborting.\n", "2024-10-21 18:40:38,613 [INFO] Building cells.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building cells.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:38,614 [INFO] Loading cell 0, tempalate Purkinje_morph_1, with spines_on=0\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Loading cell 0, tempalate Purkinje_morph_1, with spines_on=0\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n", "3856 lines read\n", "indiv number 138\n", "2024-10-21 18:40:38,784 [INFO] Loading cell 1, tempalate Purkinje_morph_1, with spines_on=1\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Loading cell 1, tempalate Purkinje_morph_1, with spines_on=1\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\n", "3856 lines read\n", "indiv number 138\n", "spine active!!\n", "dend_total_len 7680\n", "list_dend_complete 7680\n", "somma_location_spines 7680\n", "spines_placed 0\n", "spines_placed 500\n", "spines_placed 1000\n", "spines_placed 1500\n", "spines_placed 2000\n", "spines_placed 2500\n", "spines_placed 3000\n", "spines_placed 3500\n", "spines_placed 4000\n", "spines_placed 4500\n", "spines_placed 5000\n", "spines_placed 5500\n", "spines_placed 6000\n", "spines_placed 6500\n", "spines_placed 7000\n", "spines_placed 7500\n", "spines_syn: spine_head_0\n", "spines_syn: spine_head_5000\n", "spine_head_aa between 0 - 0.3 -> 0\n", "spine_head_aa_SC between 0.3 - 0.75 -> 1494\n", "spine_head_pf_SC between 0.75 - 1.5 -> 6184\n", "!!!!!!!!!!!!!!! spine_total 7678 !!!!!!!!!!!!!!!\n", "2024-10-21 18:40:39,509 [INFO] Building recurrent connections\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building recurrent connections\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:39,574 [INFO] Building virtual cell stimulations for virt_spikes\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building virtual cell stimulations for virt_spikes\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:39,590 [INFO] Running simulation for 1000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Running simulation for 1000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:39,591 [INFO] Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:40:39,592 [INFO] Block save every 5000 steps\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Block save every 5000 steps\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:43:40,420 [INFO] step:5000 t_sim:500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:5000 t_sim:500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,760 [INFO] step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,787 [INFO] Simulation completed in 5.0 minutes, 54.2 seconds \n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Simulation completed in 5.0 minutes, 54.2 seconds \n" ] } ], "source": [ "bionet.reset()\n", "conf = bionet.Config.from_json('config.purkinje.json')\n", "conf.build_env()\n", "\n", "net = bionet.BioNetwork.from_config(conf)\n", "sim = bionet.BioSimulator.from_config(conf, network=net)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "642172f8-b7f3-4216-8a67-15e530b97c94", "metadata": {}, "source": [ "### 1.4. Example: Building your own python-based cell models " ] }, { "cell_type": "markdown", "id": "ee20e24c-9767-44b8-9701-280526f7a379", "metadata": {}, "source": [ "Another option is to build a cell instance yourself using the NEURON Python API. As with above, you just need to change the **model_template** parameter for the given cell(s) you want to build from scratch and create your own `@cell_model` function that will be called prior to the simulation to generate individual NEURON cell instances for appropriate node in the network. The code can be put inside your **run_bionet.py** script or imported from another file in the same directory.\n", "\n", "The following example is a simple model taken from the [NEURON ball-and-stick tutorial](https://neuron.yale.edu/neuron/docs/ball-and-stick-model-part-1) (See *build_network.ball_and_stick.py* file check how the network was created)." ] }, { "cell_type": "code", "execution_count": 9, "id": "9a309390-dbc4-4caf-8bfc-3a0a742d77f9", "metadata": {}, "outputs": [], "source": [ "from bmtk.simulator import bionet\n", "from bmtk.simulator.bionet.io_tools import io\n", "from neuron import h\n", "\n", "class BallAndStick:\n", " def __init__(self, cell):\n", " self._gid = cell['node_id']\n", " self._setup_morphology(cell)\n", " self._setup_biophysics(cell)\n", "\n", " def _setup_morphology(self, cell):\n", " self.soma = h.Section(name='soma', cell=self)\n", " self.dend = h.Section(name='dend', cell=self)\n", " self.all = [self.soma, self.dend]\n", " self.dend.connect(self.soma)\n", " self.soma.L = self.soma.diam = 12.6157\n", " self.dend.L = 200\n", " self.dend.diam = 1\n", " \n", " def _setup_biophysics(self, cell):\n", " for sec in self.all:\n", " sec.Ra = 100 # Axial resistance in Ohm * cm\n", " sec.cm = 1 # Membrane capacitance in micro Farads / cm^2\n", " self.soma.insert('hh') \n", " for seg in self.soma:\n", " seg.hh.gnabar = cell['gnabar'] # Sodium conductance in S/cm2\n", " seg.hh.gkbar = cell['gkbar'] # Potassium conductance in S/cm2\n", " seg.hh.gl = cell['gl'] # Leak conductance in S/cm2\n", " seg.hh.el = cell['el'] # Reversal potential in mV\n", " # Insert passive current in the dendrite # <-- NEW\n", " self.dend.insert('pas') # <-- NEW\n", " for seg in self.dend: # <-- NEW\n", " seg.pas.g = cell['g_pas'] # Passive conductance in S/cm2 # <-- NEW\n", " seg.pas.e = cell['e_pas'] # Leak reversal potential mV # <-- NEW \n", " \n", " def __repr__(self):\n", " return 'BallAndStick[{}]'.format(self._gid)\n", "\n", "@bionet.cell_model(directive='python:loadBAS', model_type='biophysical')\n", "def loadPurkinjeModel(cell, template_name, dynamics_params):\n", " bas_cell = BallAndStick(cell)\n", " io.log_info(f'Adding {bas_cell} to network')\n", " return bas_cell\n" ] }, { "cell_type": "code", "execution_count": 10, "id": "dd9efc30-b0cd-4f2c-8ace-d214f43a5e16", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,816 [INFO] Created log file\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Created log file\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Mechanisms already loaded from path: ./components/mechanisms. Aborting.\n", "2024-10-21 18:46:33,859 [INFO] Building cells.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "NEURON: Biophys : a template cannot be redefined\n", " in Biophys.hoc near line 1\n", " begintemplate Biophys\n", " ^\n", " xopen(\"Biophys.hoc\")\n", " execute1(\"{xopen(\"Bi...\")\n", " load_file(\"Biophys.hoc\")\n", "NEURON: L5PCbiophys : a template cannot be redefined\n", " in L5PCbiophys4.hoc near line 10\n", " begintemplate L5PCbiophys\n", " ^\n", " xopen(\"L5PCbiophy...\")\n", " execute1(\"{xopen(\"L5...\")\n", " load_file(\"L5PCbiophy...\")\n", "NEURON: L5PCtemplate : a template cannot be redefined\n", " in L5PCtemplate.hoc near line 8\n", " begintemplate L5PCtemplate\n", " ^\n", " xopen(\"L5PCtempla...\")\n", " execute1(\"{xopen(\"L5...\")\n", " load_file(\"L5PCtempla...\")\n", "NEURON: HNTemplate : a template cannot be redefined\n", " in HNTemplate.hoc near line 1\n", " begintemplate HNTemplate\n", " ^\n", " xopen(\"HNTemplate.hoc\")\n", " execute1(\"{xopen(\"HN...\")\n", " load_file(\"HNTemplate.hoc\")\n", "INFO:NEURONIOUtils:Building cells.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,862 [INFO] Adding BallAndStick[0] to network\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Adding BallAndStick[0] to network\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,864 [INFO] Adding BallAndStick[1] to network\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Adding BallAndStick[1] to network\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,866 [INFO] Adding BallAndStick[2] to network\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Adding BallAndStick[2] to network\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,868 [INFO] Adding BallAndStick[3] to network\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Adding BallAndStick[3] to network\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,870 [INFO] Adding BallAndStick[4] to network\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Adding BallAndStick[4] to network\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,872 [INFO] Building recurrent connections\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building recurrent connections\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,935 [INFO] Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,974 [INFO] Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,975 [INFO] Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:46:33,976 [INFO] Block save every 5000 steps\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Block save every 5000 steps\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:49:33,651 [INFO] step:5000 t_sim:500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:5000 t_sim:500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:52:27,649 [INFO] step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:55:22,206 [INFO] step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:17,138 [INFO] step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:17,161 [INFO] Simulation completed in 11.0 minutes, 43.19 seconds \n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Simulation completed in 11.0 minutes, 43.19 seconds \n" ] } ], "source": [ "bionet.reset()\n", "conf = bionet.Config.from_json('config.ball_and_stick.json')\n", "conf.build_env()\n", "\n", "net = bionet.BioNetwork.from_config(conf)\n", "sim = bionet.BioSimulator.from_config(conf, network=net)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "a3f5e4e4-5321-4bd0-a0ae-7f066940ceac", "metadata": {}, "source": [ "For more information on how to build cells from scratch using NEURON see the [official documentation](https://www.neuron.yale.edu/neuron/static/py_doc/modelspec/programmatic/topology.html)." ] }, { "cell_type": "markdown", "id": "3c8bec31-7364-4dce-b6eb-f2fd9691225e", "metadata": {}, "source": [ "## 2. Modifying an existing cell model" ] }, { "cell_type": "markdown", "id": "e467baa9-9dd9-4707-8b40-d2e20f6b7d50", "metadata": {}, "source": [ "Very often, modelers may want to use an already existing cell model but make some minor changes of their own. For example, you may want to download a prebuilt channel mechanic (in the form of a .mod or .hoc file) to insert into a subset of an already existing network. You may want to edit the cell morphologies to add or remove sections of the neuron. You may want to adjust the channel densities based on the location of the section.\n", "\n", "One option to achieve this is to take an existing Hoc, Python, NeuroML, etc., cell model template and manually edit the file! This is **NOT** a good option for multiple reasons; your changes may lead to unintended side-effects - especially if you're not familiar with the language or how it was created. On top of that, having to rebuild the network and have multiple versions of a Hoc/Python template can be tedious if you are trying to test and debug your changes on the fly." ] }, { "cell_type": "markdown", "id": "efd97775-98a0-41c3-b755-91912b4de19d", "metadata": {}, "source": [ "**Solution**\n", "\n", "SONATA and BMTK provide support for making changes to an already instantiated cell model using the [**model_processing**](https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#nodes---optional-reserved-attributes) attribute. When an attribute is defined for a subpopulation of cells, it defines a directive and/or function to call on said cell immediately after it has been initialized.\n", "\n", "In BMTK, implementing your own custom function for \"model_processing\" is done in the same manner as with cell-loading. You can use the `@model_processing` decorator to a function that is inside or called in your *run_bionet.py* script.\n", "\n", "```python\n", "from bmtk.simulator.bionent import model_processing\n", "\n", "@model_processing\n", "def process_my_cell(hoc_obj, cell, dynamics_params):\n", " updated_hoc_obj = # ... modify hoc object based on parameters stored in cell and/or dynamics params.\n", " return updated_hoc_obj\n", "```\n", "\n", "Then, when building the cells (or by editing either the nodes.h5 or node_types.csv file), you can add a reference to the `process_my_cell` function.\n", "\n", "```python\n", "net.add_nodes(\n", " model_type='biophysical',\n", " model_template='hoc:Biophys1',\n", " model_processing='process_my_cell`,\n", " ...\n", ")\n", "```\n", "\n", "BMTK will also allow you to call multiple *model_process` functions in sequence by separating the calls by a comma:\n", "\n", "```python\n", "net.add_nodes(\n", " model_type='biophysical',\n", " model_template='hoc:Biophys1',\n", " model_processing='process_cell_1,process_cell_2`,\n", " ...\n", ")\n", "```" ] }, { "cell_type": "markdown", "id": "16035559-b787-464b-9dce-966715524956", "metadata": {}, "source": [ "### 2.1. Example: Adding customized mechanisms into an existing cell model " ] }, { "cell_type": "markdown", "id": "577e0532-3a4e-4d11-9837-0828b5a65b27", "metadata": {}, "source": [ "Besides cell models, repositories like ModelDB and Open Source Brain also contain a wide array of membrane density mechanisms (e.g., currents, and channels) that we may want to add to our own existing cell models. In NEURON, these are typically written as .mod files in the NMODL language and require pre-compilation using the *nrnivmodl* command. \n", "\n", "In this example, we will try downloading arbitrary sodium channel models and show how we can dynamically insert them into our L5 cells using the `@model_processing` directive." ] }, { "cell_type": "markdown", "id": "988c638f-e0d1-466a-afe9-15e4fc1a3cc4", "metadata": {}, "source": [ "##### Step 1: Downloading and compiling mechanisms\n", "\n", "First, we will find mechanisms models (e.g., .mod) files to use in our models. Here we [randomly choose sodium channels](https://modeldb.science/140249?tab=1) from ModelDB. Click on the download button to download the files.\n", "\n", "We would then need to move the downloaded .mod files into the *components/mechansism/modfiles* and rerun the command `cd components/mechanisms && nrnivmodl`. However, to make things more logical, BMTK allows us to have multiple *mechanisms* directories, so if it turns in the end, we don't want to use the new mechanisms, they will be easier to delete. Instead, we will put the .mod files into *components/dLGN_mechanisms/modfiles*, and run `nrnivmodl` from the new directory. Then, to make sure BMTK knows where to find the new mechanisms, we need to update the components section of the SONATA config:\n", "\n", "```json\n", "\n", " \"components\": {\n", " \"templates_dir\": \"$COMPONENTS_DIR/templates\",\n", " \"mechanisms_dir\": [\n", " \"$COMPONENTS_DIR/mechanisms\", \n", " \"$COMPONENTS_DIR/dLGN_mechanisms\"\n", " ]\n", " // ...\n", " }\n", "```" ] }, { "cell_type": "markdown", "id": "2022b063-a091-4963-9860-a1ffaaf448bd", "metadata": {}, "source": [ "##### Step 2: Setting directive for a population of neurons\n", "\n", "We need to make minor updates to our build network so that every subset of cells that will have these new mechanisms added will have model_processing attribute pointing to our customized post-initialization function.\n", "\n", "```python\n", "net.add_nodes(\n", " N=1,\n", " model_type='biophysical',\n", " model_template='hoc:L5PCtemplate',\n", " morphology='cell3.asc',\n", " model_processing='add_channels'\n", ")\n", "```\n", "\n", "Or if you don't want to rebuild the entire network, you can also just add a **model_processing** to the node_types.csv." ] }, { "cell_type": "markdown", "id": "a68bc00a-207d-4c46-8372-c301d5d771d2", "metadata": {}, "source": [ "#### Step 3: Add model_processing function and run\n", "\n", "Now, we can add our customized `add_channels` function, which will be called for each applicable cell right before the simulation. Like with the `@cell_model` directive, the function can be placed inside or imported into our *run_bionet.py* script, has a predefined signature, and should return an HOC instantiated cell object.\n", "\n", "Here, we will have our `add_channels` simply iterate through each section of the cell and insert the downloaded compiled IC channel:\n", "```\n", "@bionet.model_processing\n", "def add_channels(hoc_obj, cell, dynamics_params):\n", " for sec in hoc_obj.all:\n", " if 'axon' in sec.name():\n", " continue\n", "\n", " sec.insert('iahp')\n", " setattr(sec, 'gkbar_iahp', 3.0e-04)\n", " setattr(sec, 'taum_iahp', 0.5)\n", " \n", " return hoc_obj\n", "```\n", "Notes:\n", "* For most models, we can use the `.all` property to iterate through every section of the cell. Depending on the model, you may also have section iterators like `.soma`, `.axon`, `.dend`, `.apical`, `.basal`.\n", "* We don't want to insert IC channels into the axon sections. Unfortunately, there is no flag to indicate if a section is a soma, axon, dend, etc. So instead, we use the section's `name` to spike axons (Typically, a section name for a HOC or Python template will be **TemplateName\\[cell_id\\].axon\\[sec_num\\]**\n", "* Next, we use the `.insert` command to insert the channel into our section\n", "* We use the Python' setattr' function to change the default values of parameters. The specific mod file will determine which parameters can be changed and their range.\n", "\n", "You can run an example using:\n", "```\n", "$ python run.added_channels.py config.added_channels.json\n", "```" ] }, { "cell_type": "markdown", "id": "a3c29c73-4d20-4590-9a7b-f4068ef72906", "metadata": {}, "source": [ "### 2.2. Example: Modifying channel conductance in an instantiated cell. " ] }, { "cell_type": "markdown", "id": "9e082778-9f86-4e8c-b9eb-1361868abd17", "metadata": {}, "source": [ "Another thing we can also use the `@model_processing` directive is to update intrinsic properties, or even the morphology and topology, of a given cell right before running a simulation. \n", "\n", "In this example, we will want to take an already existing model and modify the conductance of the hyperpolarization-activated channels (**Ih**) in the apical dendrites based on their distance from the soma. After some investigation, we find that the conductance for our model is controlled by the parameter `gbar_Ih`. So, we want to half this parameter for all sections that are at a certain arc-length distance from the soma. We define `model_processing` function `adjust_densities`." ] }, { "cell_type": "code", "execution_count": 11, "id": "c2bd8ff4-0ed7-4cfc-aa97-453272362079", "metadata": {}, "outputs": [], "source": [ "from bmtk.simulator import bionet\n", "from bmtk.simulator.bionet.io_tools import io\n", "\n", "@bionet.model_processing\n", "def adjust_densities(hoc_obj, cell, dynamics_params):\n", " n_segs = 0\n", " n_segs_updated = 0\n", " for sec in hoc_obj.apic:\n", " for seg in sec:\n", " n_segs += 1\n", " if h.distance(seg) > 1000:\n", " n_segs_updated += 1\n", " org_cond = getattr(seg, 'gbar_Ih')\n", " new_cond = org_cond*0.5\n", " setattr(seg, 'gbar_Ih', new_cond)\n", " \n", " io.log_info(f'{n_segs_updated} out of {n_segs} apical dendritic segments updated.')\n", " return hoc_obj\n" ] }, { "cell_type": "markdown", "id": "db0eb4a8-6759-456a-becf-bc46df2b4cc9", "metadata": {}, "source": [ "Some notes to consider about this function:\n", "* To only iterate through the **apic** section types (which will ignore soma, axon, and basal section), we use `hoc_obj.apic` list instead of `hoc_obj.all` as we did with the previous example\n", "* A section may be partitioned into one or more segments. Each section will have the same attributes and inserted mechanisms. However, the actual property values of each individual segment, like distance and conductance, may vary. Hence, we need to update each individual segment of each section using the code:\n", "```python\n", " for section in hoc_obj.all:\n", " for segment in section:\n", " ....\n", "```\n", "* [h.distance(seg)](https://www.neuron.yale.edu/neuron/static/new_doc/modelspec/programmatic/topology/geometry.html#distance) is a built-in NEURON function that measures arc-length from each segment to the soma, in microns. Only segments that are >1000 um will have their Ih conductances reduced. The rest will be left to default value.\n", "* We use the built-in Python functions `getattr` and `setattr` to fetch and set the gbar_Ih value of each segment object.\n" ] }, { "cell_type": "code", "execution_count": 12, "id": "4709c87c-9bf5-400d-990c-6bb87cdbec73", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:17,186 [INFO] Created log file\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Created log file\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Mechanisms already loaded from path: ./components/mechanisms. Aborting.\n", "2024-10-21 18:58:17,220 [INFO] Building cells.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building cells.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:17,979 [INFO] 262 out of 573 apical dendritic segments updated.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:262 out of 573 apical dendritic segments updated.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:17,982 [INFO] Building recurrent connections\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building recurrent connections\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:18,045 [INFO] Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:18,065 [INFO] Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Running simulation for 2000.000 ms with the time step 0.100 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:18,067 [INFO] Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Starting timestep: 0 at t_sim: 0.000 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 18:58:18,068 [INFO] Block save every 5000 steps\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Block save every 5000 steps\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:01:19,953 [INFO] step:5000 t_sim:500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:5000 t_sim:500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:04:13,908 [INFO] step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:10000 t_sim:1000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:07:06,708 [INFO] step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:15000 t_sim:1500.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:09:59,401 [INFO] step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils: step:20000 t_sim:2000.00 ms\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:09:59,432 [INFO] Simulation completed in 11.0 minutes, 41.37 seconds \n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Simulation completed in 11.0 minutes, 41.37 seconds \n" ] } ], "source": [ "bionet.reset()\n", "conf = bionet.Config.from_json('config.modified_densities.json')\n", "conf.build_env()\n", "\n", "graph = bionet.BioNetwork.from_config(conf)\n", "sim = bionet.BioSimulator.from_config(conf, network=graph)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "d747b8e0-e8d0-49cf-9f99-21420d8e417c", "metadata": {}, "source": [ "##### Help with investigating and updating a model\n", "\n", "Trying to figure out what mechanisms, section types, and other parameters of instantiated HOC cell can be tricky, as can trying to figure out how to change an existing cell. A good place to start is by looking through the official NEURON documentation [1](https://www.neuron.yale.edu/neuron/static/new_doc/modelspec/programmatic/topology/geometry.html). One useful function is the `h.psection()` that will provide valuable information about each section/segment of a cell.\n", "\n", "Below, we can overwrite the previous version of `adjust_densities` with one that will print information about each section type (although only for the first section of each type - there are 1200+ sections in total, so we won't try to print them all out). Not only is this helpful for inspecting the cell, it shows how useful it can be to change the way cells are processed on the fly.\n" ] }, { "cell_type": "code", "execution_count": 13, "id": "5ee753b8-9267-4e0b-951c-dd7db5a785c5", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:09:59,446 [INFO] Created log file\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Created log file\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Mechanisms already loaded from path: ./components/mechanisms. Aborting.\n", "2024-10-21 19:09:59,464 [INFO] Building cells.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building cells.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "L5PCtemplate[16].apic[0]\n", "{'Ra': 100.0,\n", " 'cell': L5PCtemplate[16],\n", " 'cm': [2.0],\n", " 'density_mechs': {'CaDynamics_E2': {'decay': [35.725651],\n", " 'depth': [0.1],\n", " 'gamma': [0.000637],\n", " 'minCai': [0.0001]},\n", " 'Ca_HVA': {'g': [0.0],\n", " 'gbar': [1e-05],\n", " 'h': [0.0],\n", " 'ica': [0.0],\n", " 'm': [0.0]},\n", " 'Ca_LVAst': {'gCa_LVAst': [0.0],\n", " 'gCa_LVAstbar': [0.00141954],\n", " 'h': [0.0],\n", " 'ica': [0.0],\n", " 'm': [0.0]},\n", " 'Ih': {'g': [0.0],\n", " 'gbar': [0.0001309879],\n", " 'ihcn': [0.0],\n", " 'm': [0.0],\n", " 'shift1': [154.9],\n", " 'shift2': [11.9],\n", " 'shift3': [0.0],\n", " 'shift4': [33.1],\n", " 'shift5': [6.43],\n", " 'shift6': [193.0]},\n", " 'Im': {'g': [0.0], 'gbar': [1e-05], 'ik': [0.0], 'm': [0.0]},\n", " 'NaTs2_t': {'gNaTs2_t': [0.0],\n", " 'gNaTs2_tbar': [0.021489],\n", " 'h': [0.0],\n", " 'ina': [0.0],\n", " 'm': [0.0]},\n", " 'SK_E2': {'gSK_E2': [0.0],\n", " 'gSK_E2bar': [2e-06],\n", " 'ik': [0.0],\n", " 'z': [0.0]},\n", " 'SKv3_1': {'gSKv3_1': [0.0],\n", " 'gSKv3_1bar': [0.001808],\n", " 'ik': [0.0],\n", " 'm': [0.0]},\n", " 'pas': {'e': [-90.0], 'g': [6e-05], 'i': [0.0]}},\n", " 'hoc_internal_name': '__nrnsec_0x55555e538290',\n", " 'ions': {'ca': {'cai': [5e-05],\n", " 'cao': [2.0],\n", " 'dica_dv_': [0.0],\n", " 'eca': [132.4579341637009],\n", " 'ica': [0.0]},\n", " 'k': {'dik_dv_': [0.0],\n", " 'ek': [-85.0],\n", " 'ik': [0.0],\n", " 'ki': [54.4],\n", " 'ko': [2.5]},\n", " 'na': {'dina_dv_': [0.0],\n", " 'ena': [50.0],\n", " 'ina': [0.0],\n", " 'nai': [10.0],\n", " 'nao': [140.0]}},\n", " 'morphology': {'L': 16.729761891618992,\n", " 'diam': [8.118265357665159],\n", " 'parent': L5PCtemplate[16].soma[0](0.5),\n", " 'pts3d': [(-39.77000045776367,\n", " 29.8799991607666,\n", " -24.969999313354492,\n", " 9.550000190734863),\n", " (-39.77000045776367,\n", " 29.8799991607666,\n", " -24.969999313354492,\n", " 9.550000190734863),\n", " (-39.54999923706055,\n", " 33.040000915527344,\n", " -26.06999969482422,\n", " 8.640000343322754),\n", " (-38.86000061035156,\n", " 37.06999969482422,\n", " -27.100000381469727,\n", " 7.730000019073486),\n", " (-37.95000076293945,\n", " 39.939998626708984,\n", " -27.56999969482422,\n", " 7.730000019073486),\n", " (-37.5,\n", " 42.2400016784668,\n", " -27.56999969482422,\n", " 7.730000019073486),\n", " (-37.04999923706055,\n", " 45.689998626708984,\n", " -29.020000457763672,\n", " 7.730000019073486)],\n", " 'trueparent': L5PCtemplate[16].soma[0](0.5)},\n", " 'name': 'L5PCtemplate[16].apic[0]',\n", " 'nseg': 1,\n", " 'point_processes': {},\n", " 'regions': set(),\n", " 'species': set()}\n", "2024-10-21 19:10:00,357 [INFO] Building recurrent connections\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building recurrent connections\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "2024-10-21 19:10:00,363 [INFO] Building virtual cell stimulations for virt_exc_spikes\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:NEURONIOUtils:Building virtual cell stimulations for virt_exc_spikes\n" ] } ], "source": [ "from pprint import pprint\n", "\n", "@bionet.model_processing(name='adjust_densities')\n", "def check_mechanisms(hoc_obj, cell, dynamics_params):\n", " for sec in hoc_obj.apic:\n", " print(sec.name())\n", " pprint(sec.psection())\n", " break\n", "\n", " return hoc_obj\n", "\n", "bionet.reset()\n", "conf = bionet.Config.from_json('config.modified_densities.json')\n", "conf.build_env()\n", "\n", "graph = bionet.BioNetwork.from_config(conf)\n", "sim = bionet.BioSimulator.from_config(conf, network=graph)" ] }, { "cell_type": "code", "execution_count": null, "id": "d1dd8d48-ad1a-4790-9f19-040f053cb430", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.16" } }, "nbformat": 4, "nbformat_minor": 5 }