Merge branch 'master' into arbor_integration

Author: lukasgd

bluepyopt/neuroml/biophys.py

@@ -192,21 +192,57 @@ def add_nml_channel_to_nml_cell_file(
         channel_nml2_file = f"{channel_name}.channel.nml"
 
     if channel_nml2_file not in included_channels:
-        nml_mech_dir = get_nml_mech_dir()
         channel_new_path = Path(channel_dir) / channel_nml2_file
         cell_doc.includes.append(neuroml.IncludeType(href=channel_new_path))
 
         # for some reason, pynml cannot accept absolute paths in IncludeType,
         # so copy paste files in current directory for the simulation to work
         if not skip_channels_copy:
             Path(channel_dir).mkdir(exist_ok=True)
-            channel_path = Path(nml_mech_dir) / channel_nml2_file
+            nml_mech_dir = Path(get_nml_mech_dir())
+            channel_path = nml_mech_dir / channel_nml2_file
             if channel_path.is_file():
                 shutil.copy(channel_path, channel_new_path)
 
         included_channels.append(channel_nml2_file)
 
 
+def get_channel_ion(channel, custom_channel_ion=None):
+    """Get ion name given channel name.
+
+    Arguments:
+        channel (str): ion channel (e.g. StochKv)
+        custom_channel_ion (dict): dict mapping channel to ion
+    """
+    ion = channel_ions.get(channel, None)
+    if ion is None and custom_channel_ion is not None:
+        ion = custom_channel_ion.get(channel, None)
+    if ion is None:
+        raise KeyError(
+            f"Ion not found for channel {channel}."
+            " Please set channel-ion mapping using custom_channel_ion."
+        )
+    return ion
+
+
+def get_erev(ion, custom_ion_erevs=None):
+    """Get reversal potential as str given ion name.
+
+    Arguments:
+        ion (str): ion name (e.g. na)
+        custom_ion_erevs (dict): dict mapping ion to erev (reversal potential)
+    """
+    erev = ion_erevs.get(ion, None)
+    if erev is None and custom_ion_erevs is not None:
+        erev = custom_ion_erevs.get(ion, None)
+    if erev is None:
+        raise KeyError(
+            f"Reversal potential not found for ion {ion}."
+            " Please set ion-erev mapping using custom_ion_erevs."
+        )
+    return erev
+
+
 def get_arguments(
     params,
     parameter_name,
@@ -216,6 +252,8 @@ def get_arguments(
     variable_parameters,
     cond_density,
     release_params,
+    custom_channel_ion=None,
+    custom_ion_erevs=None,
 ):
     """Get arguments for channel density function.
 
@@ -230,11 +268,13 @@ def get_arguments(
             parameters for non-uniform distributions
         cond_density (str): conductance density
         release_params (dict): optimized parameters
+        custom_channel_ion (dict): dict mapping channel to ion
+        custom_ion_erevs (dict): dict mapping ion to erev (reversal potential)
     """
     arguments = {}
 
-    arguments["ion"] = channel_ions[channel]
-    erev = ion_erevs[arguments["ion"]]
+    arguments["ion"] = get_channel_ion(channel, custom_channel_ion)
+    erev = get_erev(arguments["ion"], custom_ion_erevs)
 
     channel_class = "ChannelDensity"
 
@@ -331,12 +371,14 @@ def get_density(
     skip_non_uniform,
     release_params,
     skip_channels_copy,
+    custom_channel_ion=None,
+    custom_ion_erevs=None,
 ):
     """Return density.
 
     Arguments:
         cell_doc (NeuroMLDocument): nml document of the cell model
-        cell (ephys.CellModel)
+        cell (ephys.CellModel): bluepyopt cell
         parameter (ephys.parameters)
         section_list (str): location
         included_channels (list): list of channels already included
@@ -345,6 +387,8 @@ def get_density(
         release_params (dict): optimized parameters
         skip_channels_copy (bool): True to skip the copy pasting
             of the neuroml channel files
+        custom_channel_ion (dict): dict mapping channel to ion
+        custom_ion_erevs (dict): dict mapping ion to erev (reversal potential)
     """
     channel = get_channel_from_param_name(parameter.param_name)
 
@@ -375,6 +419,8 @@ def get_density(
         variable_parameters=variable_parameters,
         cond_density=cond_density,
         release_params=release_params,
+        custom_channel_ion=custom_channel_ion,
+        custom_ion_erevs=custom_ion_erevs,
     )
 
     density = getattr(neuroml, channel_class)(**arguments)
@@ -413,16 +459,20 @@ def get_biophys(
     release_params,
     skip_non_uniform=False,
     skip_channels_copy=False,
+    custom_channel_ion=None,
+    custom_ion_erevs=None,
 ):
     """Get biophys in neuroml format.
 
     Arguments:
-        cell (ephys.CellModel)
+        cell (ephys.CellModel): bluepyopt cell
         cell_doc (NeuroMLDocument): nml document of the cell model
-        skip_non_uniform (bool): True to skip non uniform distributions
         release_params (dict): optimized parameters
+        skip_non_uniform (bool): True to skip non uniform distributions
         skip_channels_copy (bool): True to skip the copy pasting
             of the neuroml channel files
+        custom_channel_ion (dict): dict mapping channel to ion
+        custom_ion_erevs (dict): dict mapping ion to erev (reversal potential)
     """
     concentrationModels = {}
 
@@ -458,6 +508,8 @@ def get_biophys(
                         skip_non_uniform,
                         release_params,
                         skip_channels_copy,
+                        custom_channel_ion,
+                        custom_ion_erevs,
                     )
 
                     if density is not None:

bluepyopt/neuroml/cell.py

@@ -27,16 +27,22 @@
 logger = logging.getLogger(__name__)
 
 
-def create_neuroml_cell(bpo_cell, release_params, skip_channels_copy=False):
+def create_neuroml_cell(
+    bpo_cell,
+    release_params,
+    skip_channels_copy=False,
+    custom_channel_ion=None,
+    custom_ion_erevs=None,
+):
     """Create the cell.
 
     Arguments:
-        nml_mech_files (list): paths to the nml files
-            containing the mechanisms
-        bpo_cell
+        bpo_cell (ephys.CellModel): bluepyopt cell
         release_params (dict): the optimized parameters
         skip_channels_copy (bool): True to skip the copy pasting
             of the neuroml channel files
+        custom_channel_ion (dict): dict mapping channel to ion
+        custom_ion_erevs (dict): dict mapping ion to erev (reversal potential)
 
     :returns: name of the cell nml file
     """
@@ -76,6 +82,8 @@ def create_neuroml_cell(bpo_cell, release_params, skip_channels_copy=False):
         release_params,
         skip_non_uniform=True,
         skip_channels_copy=skip_channels_copy,
+        custom_channel_ion=custom_channel_ion,
+        custom_ion_erevs=custom_ion_erevs,
     )
 
     # Append biophys to cell

bluepyopt/neuroml/morphology.py

@@ -28,7 +28,15 @@
 def create_loadcell_hoc(
     loadcell_hoc_filename, hoc_filename, morphology_path, v_init, cell_name
 ):
-    """Create a hoc file able to load the cell."""
+    """Create a hoc file able to load the cell.
+
+    Arguments:
+        loadcell_hoc_filename (str): path to the loadcell hoc file to output
+        hoc_filename (str): file name of the cell hoc file
+        morphology_path (str): path to the morphology file
+        v_init (float): inital voltage in mV
+        cell_name (str): cell name
+    """
     morph_path = Path(morphology_path)
     morph_dir = morph_path.parent
     morph_file = morph_path.name
@@ -56,7 +64,13 @@ def create_loadcell_hoc(
 
 
 def create_morph_nml(bpo_cell, network_filename, release_params):
-    """Create cell hoc file, then cell nml file."""
+    """Create cell hoc file, then cell nml file.
+
+    Arguments:
+        bpo_cell (ephys.CellModel): bluepyopt cell
+        network_filename (str): name of the neuroml network file
+        release_params (dict): name and values of optimised parameters
+    """
     import pebble
 
     hoc_filename = f"{bpo_cell.name}.hoc"

examples/neuroml/neuroml.ipynb

@@ -29,13 +29,15 @@
    ]
   },
   {
+   "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"
+    "- axon replacement\n",
+    "- stochasticity"
    ]
   },
   {
@@ -57,7 +59,6 @@
     "import sys\n",
     "\n",
     "from pyneuroml import pynml\n",
-    "from bluepyopt.ephys import models\n",
     "from bluepyopt.neuroml import cell\n",
     "from bluepyopt.neuroml import simulation"
    ]
@@ -174,7 +175,7 @@
     "- 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",
-    "Note that the `create_neuroml_cell` function is designed to work with the mechanisms present in `bluepyopt/neuroml/NeuroML2_mechanisms/` and will likely crash if you try to use it with custom mechanisms."
+    "Skip this step if you want to use custom mechanisms not present in `bluepyopt/neuroml/NeuroML2_mechanisms/`."
    ]
   },
   {
@@ -185,7 +186,38 @@
    "outputs": [],
    "source": [
     "cell.create_neuroml_cell(\n",
-    "    l5pc_cell, release_params, skip_channels_copy=False\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",
     ")"
    ]
   },
@@ -385,7 +417,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.10.8 (main, Oct 13 2022, 10:17:43) [Clang 14.0.0 (clang-1400.0.29.102)]"
   },
   "vscode": {
    "interpreter": {