examples/neuroml/neuroml.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0eb6d681-8042-48fa-9a7e-d094b5b13eb2",
   "metadata": {},
   "source": [
    "# Exporting a cell in the neuroml format and running it"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5eddcf29-5590-48d5-a936-bef388601471",
   "metadata": {},
   "source": [
    "To run this notebook, it is necessary to have bluepyopt, pyneuroml and libNeuroML installed. This can be achieved with the following pip install:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee91d4f4-1bba-4cc1-a172-90aab83c38f7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pip install bluepyopt[neuroml]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "63d69fd0-dd92-424b-b38a-be50f03e3dd7",
   "metadata": {},
   "source": [
    "Note that the bluepyopt neuroml module cannot yet handle:\n",
    "- non uniform parameter\n",
    "- axon replacement\n",
    "- stochasticity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8027678b-0701-467f-b90f-dfb6530d2969",
   "metadata": {},
   "source": [
    "## Exporting a cell to neuroml"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "487c93d9-ba25-4b1b-9c69-2b4fb7ecb9e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import sys\n",
    "\n",
    "from pyneuroml import pynml\n",
    "from bluepyopt.neuroml import cell\n",
    "from bluepyopt.neuroml import simulation"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "00917451-185c-4885-ab95-7256f195190e",
   "metadata": {},
   "source": [
    "For simplicity, in this notebook we will use the cell from bluepyopt's l5pc example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "10394750-fd29-43fa-ac7f-3910ebf2b433",
   "metadata": {},
   "outputs": [],
   "source": [
    "L5PC_PATH = os.path.abspath(\"../l5pc\")\n",
    "sys.path.insert(0, L5PC_PATH)\n",
    "\n",
    "import l5pc_model\n",
    "\n",
    "l5pc_cell = l5pc_model.create()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "2d9c3323-c1da-4272-b3ab-9eeac3391743",
   "metadata": {},
   "source": [
    "We have to disable replace_axon, since it is not supported by bluepyopt's neuroml module yet:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "ac925939-fd13-480b-ae05-ce744330f51e",
   "metadata": {},
   "outputs": [],
   "source": [
    "l5pc_cell.morphology.do_replace_axon = False"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73b4697a-a403-45cf-b0ff-e22564cd14e6",
   "metadata": {},
   "source": [
    "We have to define the cell's optimised parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "218482bc-9a2f-4627-9c4b-3ffaa3b9e595",
   "metadata": {},
   "outputs": [],
   "source": [
    "release_params = {\n",
    "    \"gNaTs2_tbar_NaTs2_t.apical\": 0.026145,\n",
    "    \"gSKv3_1bar_SKv3_1.apical\": 0.004226,\n",
    "    \"gImbar_Im.apical\": 0.000143,\n",
    "    \"gNaTa_tbar_NaTa_t.axonal\": 3.137968,\n",
    "    \"gK_Tstbar_K_Tst.axonal\": 0.089259,\n",
    "    \"gamma_CaDynamics_E2.axonal\": 0.002910,\n",
    "    \"gNap_Et2bar_Nap_Et2.axonal\": 0.006827,\n",
    "    \"gSK_E2bar_SK_E2.axonal\": 0.007104,\n",
    "    \"gCa_HVAbar_Ca_HVA.axonal\": 0.000990,\n",
    "    \"gK_Pstbar_K_Pst.axonal\": 0.973538,\n",
    "    \"gSKv3_1bar_SKv3_1.axonal\": 1.021945,\n",
    "    \"decay_CaDynamics_E2.axonal\": 287.198731,\n",
    "    \"gCa_LVAstbar_Ca_LVAst.axonal\": 0.008752,\n",
    "    \"gamma_CaDynamics_E2.somatic\": 0.000609,\n",
    "    \"gSKv3_1bar_SKv3_1.somatic\": 0.303472,\n",
    "    \"gSK_E2bar_SK_E2.somatic\": 0.008407,\n",
    "    \"gCa_HVAbar_Ca_HVA.somatic\": 0.000994,\n",
    "    \"gNaTs2_tbar_NaTs2_t.somatic\": 0.983955,\n",
    "    \"decay_CaDynamics_E2.somatic\": 210.485284,\n",
    "    \"gCa_LVAstbar_Ca_LVAst.somatic\": 0.000333,\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3bdf4cd0-6ebd-4294-9f95-5accaf76c098",
   "metadata": {},
   "source": [
    "And we have to compile the mechanisms:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4728e2d-a890-40f3-b8a7-4dad84eb8a2f",
   "metadata": {},
   "outputs": [],
   "source": [
    "os.system(\"nrnivmodl ../l5pc/mechanisms/\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "5a08bdc0-66da-486b-a91a-52be1ec01385",
   "metadata": {},
   "source": [
    "Finally, we can create the neuroml cell. Using `skip_channels_copy=False` will copy the neuroml mechanisms from `bluepyopt/neuroml/NeuroML2_mechanisms/` to a folder named `channels`.\n",
    "\n",
    "This creates:\n",
    "- a neuroml cell file named after the bluepyopt cell's name: Here, `l5pc_0_0.cell.nml`.\n",
    "- a neuroml network file containing the neuroml cell, named after the bluepyopt cell's name. Here, `l5pc.net.nml`.\n",
    "\n",
    "Skip this step if you want to use custom mechanisms not present in `bluepyopt/neuroml/NeuroML2_mechanisms/`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7d2469c6-8931-4da3-9dae-f89c59ee10d6",
   "metadata": {},
   "outputs": [],
   "source": [
    "cell.create_neuroml_cell(\n",
    "    l5pc_cell, release_params, skip_channels_copy=False,\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "a0db4c6b",
   "metadata": {},
   "source": [
    "If you want to create a neuroml cell with custom mechanisms that are not present in `bluepyopt/neuroml/NeuroML2_mechanisms/`, you will have to:\n",
    "- copy your custom mechanisms in the `.nml` format in the `./channels` directory\n",
    "- give as argument `custom_channel_ion`, a dict mapping channel name to ion name, e.g. `custom_channel_ion = {\"NaCustom\": \"na\"}`\n",
    "- if one of the ion in `custom_channel_ion` is not in pre-registered ions (na, k, hcn, ca, pas), you'll also have to give as argument `custom_ion_erevs`, a dict mapping ions to their reversal potential\n",
    "\n",
    "Below is an example of how to use the `create_neuroml_cell` function with custom mechanisms.\n",
    "\n",
    "However, be aware that `create_neuroml_cell` might not be able to deal with any given custom mechanism, and some might break it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "adf01098",
   "metadata": {},
   "outputs": [],
   "source": [
    "custom_channel_ion = {\"Cl_custom_mech_name\": \"cl\"}\n",
    "custom_ion_erevs = {\"cl\": \"-60.0 mV\"}\n",
    "\n",
    "cell.create_neuroml_cell(\n",
    "    l5pc_cell, release_params, skip_channels_copy=False, custom_channel_ion=custom_channel_ion, custom_ion_erevs=custom_ion_erevs,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "192726fa-6809-4667-8ff7-b786537528b8",
   "metadata": {},
   "source": [
    "## Creating a LEMS simulation able to run the neuroml cell"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec02ca3a-fc6c-4155-83c4-2925d89e013e",
   "metadata": {},
   "source": [
    "First, we have to input the name of the neuroml network created with the cell at the previous step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "aec6b630-1239-4234-a425-06405e4a1e8e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "network_filename = f\"{l5pc_cell.name}.net.nml\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1574c6b-9fe1-4d1d-9a55-36bd26bb0c3f",
   "metadata": {},
   "source": [
    "We have to get the protocols. Here, we can get the ones from the bluepyopt l5pc example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "51c0cb30-4de6-4df7-9519-9a6027e39ea1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import l5pc_evaluator\n",
    "\n",
    "protocols = l5pc_evaluator.define_protocols()\n",
    "protocol_name = \"Step3\"\n",
    "bpo_test_protocol = protocols[protocol_name]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88b8e31f-146b-40cf-8a23-6e7a00531cca",
   "metadata": {},
   "source": [
    "We also have to define a timestep."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "80a4b756-3091-4643-99ea-300603632f78",
   "metadata": {},
   "outputs": [],
   "source": [
    "dt = 0.025"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "725c81cf-bc9a-4989-b3e4-68aae28a1cca",
   "metadata": {},
   "source": [
    "Finally, we have to define the name of the LEMS simulation file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "b8364c84-6438-4b81-9c48-984070baa74e",
   "metadata": {},
   "outputs": [],
   "source": [
    "lems_filename = f\"LEMS_{l5pc_cell.name}.xml\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "369f1a56-5a0d-4ce6-a6d4-648d2c68e16a",
   "metadata": {},
   "source": [
    "We can  now create the LEMS simulation file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "05416e97-7167-48d6-8b1d-14b4fe465d92",
   "metadata": {},
   "outputs": [],
   "source": [
    "simulation.create_neuroml_simulation(\n",
    "    network_filename, bpo_test_protocol, dt, l5pc_cell.name, lems_filename\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bce6ca89-4eb3-41d3-9f2d-ffaad46910c1",
   "metadata": {},
   "source": [
    "## Run the simulation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53225126-af48-4729-8715-d7cd53f0b888",
   "metadata": {},
   "source": [
    "First, we have to remove the compiled mechanisms for the LEMS simulation to run without issues."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8a06da11-ef5d-41ce-99ae-c683661ddd4c",
   "metadata": {},
   "outputs": [],
   "source": [
    "os.system(\"rm -rf x86_64/\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "8ca18971",
   "metadata": {},
   "source": [
    "Before running the LEMS simulation, you might have to set the env variable NEURON_HOME in your jupyter kernel. Change the following jupyter cell accordingly to set your NEURON_HOME variable. It should link to the parent directory of the nrniv executable, up to but not including bin."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6f182b5",
   "metadata": {},
   "outputs": [],
   "source": [
    "%env NEURON_HOME=path/to/neuron/home"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2162fbeb-4eb3-4fac-8bac-c23f47f5faee",
   "metadata": {},
   "source": [
    "Since the default jNeuroML simulator can only simulate single compartment cells, we will run the simulation with the NEURON simulator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7eec49fb-5dd5-4675-bb23-8bb1c5087f16",
   "metadata": {},
   "outputs": [],
   "source": [
    "pynml.run_lems_with_jneuroml_neuron(\n",
    "    lems_filename, nogui=True, plot=False\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "170d1c75-40f8-4415-9244-5688a8d497d3",
   "metadata": {},
   "source": [
    "This will output a trace in the following file: `l5pc.Pop_l5pc_0_0.v.dat`. Note that the data are recorded in volts and seconds."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "myenv-py310",
   "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.8 (main, Oct 13 2022, 10:17:43) [Clang 14.0.0 (clang-1400.0.29.102)]"
  },
  "vscode": {
   "interpreter": {
    "hash": "891adc0cb08a4acf2327ce13c187b82b86b16ff1d60877363e9705a5e6a5aa86"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}