Allow custom mechanism in neuroml conversion

Author: Jaquier Aurélien Tristan

bluepyopt/neuroml/biophys.py

@@ -207,6 +207,38 @@ def add_nml_channel_to_nml_cell_file(
         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 potentail not found for ion {ion}."
+        " Please set ion-erev mapping using custom_ion_erevs.")
+    return erev
+
+
 def get_arguments(
     params,
     parameter_name,
@@ -216,6 +248,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 +264,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,6 +367,8 @@ def get_density(
     skip_non_uniform,
     release_params,
     skip_channels_copy,
+    custom_channel_ion=None,
+    custom_ion_erevs=None,
 ):
     """Return density.
 
@@ -345,6 +383,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 +415,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,6 +455,8 @@ 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.
 
@@ -423,6 +467,8 @@ def get_biophys(
         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 +504,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,14 +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:
         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
     """
@@ -74,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

examples/neuroml/neuroml.ipynb

@@ -176,7 +176,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/`."
    ]
   },
   {
@@ -187,7 +187,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",
     ")"
    ]
   },
@@ -387,7 +418,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": {