Importing existing NEURON/GENESIS models into neuroConstruct

Outlined here is the process for taking an existing cell model in NEURON (hoc and mod files) and reimplementing it in neuroConstruct (a very similar process is used for importing GENESIS models). At the moment it can be a complicated process but the advantages of doing it are:

  • It is easier to incorporate single cell models into networks of arbitrary size and complexity once they are in neuroConstruct
  • It simplifies making the model available for multiple simulators (e.g. GENESIS too). Once in neuroConstruct/NeuroML format, the cell model will be available for any other simulator supported by these in the future (e.g. GENESIS 3/MOOSE/Parallel NEURON), provided the cell mechanisms can be implemented in that simulator.
  • All of the inbuilt functionality for storing, browsing and analysing simulations neuroConstruct is available
  • A neuroConstruct project including the model description, results of the simulation, plots of the figures in published papers, etc. can be distributed in a single zipped file
  • The model can be easily rerun and model parameters changed by those without knowledge of the native scripting environment

Note: Exporting NeuroML from simulators will facilitate this process. NEURON 6.1 allows export of cell morphologies together with channel densities in NeuroML format from ModelView. See here for the latest version.

Bringing NEURON models into neuroConstruct

  1. With a fully tested NEURON model, ensure the hoc code is split between separate files containing a) the morphologies of the cells, b) the mod files containing the cell mechanisms (including default values for all parameters, e.g. max conductance densities) c) the main hoc file which creates the cells, places the channels on the cells, adds the stimulations, etc. and runs the main simulation and d) a file which creates any GUI elements for plotting data, (re)running the simulation and changing parameters. This is the standard way to split functionality between files (generally used for the models in ModelDB), and if a model is published with everything in a single large file, there is little chance of reusing much in neuroConstruct.
  2. In general neuroConstruct should be able to import files a) above and include b) as the NEURON implementation of Cell Mechanisms. The simulation parameters in c) will be set through the neuroConstruct GUI by hand, and any plots of data can also be specified through the interface.
  3. Select File->New Project, and enter the name and location of your new project.
  4. To import a NEURON *.hoc/*.nrn morphology file Go to Cell Types -> Add New Cell Type and select NeuronMorphReader in the first drop down box. Select the morphology file by entering the path into the text field or pressing the ... button and selecting the file manually. Note that the biggest problem in importing files is that there is no prescribed way to write NEURON morphology files, unlike the *.p (readcell) file format in GENESIS. For the importation process, it assumes the form of a file similar to that generated by NTS cable (usually a *.nrn file). This will normally contain only create statements, pt3dadd commands, connect commands and the fscan function. Other commands e.g. insert are ignored in this version. More details here. It wasn't an easy matter creating an importer for general NEURON morphology files, so not every *.hoc/*.nrn file will work first time. If you have specific problems, send me the morphology file and I'll try to adjust the importer to deal with it, or I can suggest ways to rewrite the file in a simpler format. Alternatively for cells with a small number of sections (<10), you can add a Simple Cell (via tab Cell Types -> Add New Cell to Project), rename it, press View this cell in 3D, click on a section, press Edit... and add/delete sections as appropriate, building your morphology as you go.
  5. As an alternative to the above, the cell could be loaded into NEURON 6.1 (with the updated files from here) using the original hoc/mod files and exported from ModelView (Tools -> ModelView -> File -> Export to NeuroML). This works best if there is just one cell loaded in NEURON. The function define_shape() should be run before export to ensure all NEURON sections have full 3D info. Level 1 exports will have just the cell morphology, Level 2 will include info on channel densities. The NeuroML file exported can then be imported into neuroConstruct similar to the manner above, via Cell Types -> Add New Cell Type and selecting the NeuroMLConverter option. If a Level 2 export is used, there should already be channel mechanisms in the neuroConstruct project with the same names as those in the NEURON model (see below).
  6. To include a Channel Mechanism (e.g. a voltage dependent ion channel) or a Synaptic Mechanism based on an existing mod file go to tab Cell Mechanisms, select Create File Based Mechanism. Enter the name of the Cell Mechanism. If the mod file is a density mechanism, choose "Channel Mechanism". If it represents the end point of a synaptic connection, choose "Synaptic Mechanism". Select the *.mod file which implements the Channel Mechanism/Synapse when prompted. Existing Channel Mechanisms implemented in NMODL can be reused with a few small changes. In the line specifying the the name of the mechanism in the original NMODL file, replace the name string with %Name%, so for example in Exp3Syn.mod the line
      POINT_PROCESS %Name%
    and in a channel mechanism NaFast.mod
      SUFFIX NaFast
      SUFFIX %Name%
    In general any value between %'s will be replaced with another value by neuroConstruct. Another change which should be made in your NMODL files is to replace the value of the max conductance density with %Max Conductance Density% in channel mechanisms and the max conductance with %Max Conductance% in synapses. Note: the variable name gmax should be used for the max conduction density in channels and max conductance in synapses, so that neuroConstruct will know the public variable name so it can access it from the hoc. To get a better idea of what's going on, open (via Edit selected Cell Mechanism) any of the File Based Cell Mechanisms included in examples/Ex8-DentateGyrus, paying attention to the NEURON template code. More information is available here
  7. To put the channel mechanisms on to the cell you have imported (if you haven't used a NeuroML import detailing channel placement), go to Visualisation, select the cell name in the drop down box and press View. Select Groups in the bottom right drop down box. There are some basic groups defined, but to add others, click Edit Groups. In this way Section Groups (corresponding to SectionLists as used in NEURON) which will have similar biophysical properties can be defined. Now select Cell density mechanisms in the drop down box, and click Edit Density Mechanisms. You can now place the Channel Mechanisms on the groups you have created. If it's a single compartment cell, just use the group all.
  8. Finally create a new Region, create a new Cell Group (the default values will create a single randomly placed cell) and press Generate. You can also add an electrophysiological input (e.g. an IClamp) and a graph of the cell voltage via the tab Input/Output. Again the default values should be a good starting point.
  9. Hopefully all of this will be successful and you can go to tab Export and generate the NEURON code.
  10. This description only concerns placing one cell in 3D. Once each cell works as expected, networks can be built. See the description of Network Connections for more information.

Converting mod file/GENESIS script channels into ChannelML

  1. The goal of this is to create a ChannelML file with the same mechanism as one present in an existing mod file/GENESIS script. Look at the included example Ex10-MainenEtAl which contains a Simulation Configuration SimpleCells which shows an example of this procedure.
  2. Instead of trying to match the channels using the full cell morphology, start with a single section (ideally just one segment), e.g. the soma of the cell to be converted. You can use the imported morphology (e.g. Cell1), create a copy of it (Cell1_original) and delete all sections, just leaving the soma section.
  3. Create a cell group with a single instance of the soma section (CG_original).
  4. Get the passive properties working properly. Use psection() on the corresponding section in your original NEURON model to get values for cm, Ra etc. and update the values of these on your neuroConstruct version (use the LeakConductance built in ChannelML mechanism for the passive conductance, as in the examples). Add a small current pulse to the section and add a plot for the voltage. Generate the network and check the section's basic parameters using psection().
  5. Make a copy of the cell (Cell1_CML) and a new cell group with that cell (CG_CML). Add a current pulse and a plot of the voltage and generate the network again to ensure the 2 plots overlap (the Graph Window property of the plot can be altered in neuroConstruct to get the 2 traces in the same window in NEURON).
  6. Convert a simple channel first, e.g. non-Ca2+ dependent K channel. Use the original mod file for a File based Cell Mechanism as outlined above and here
  7. Add this mechanism to Cell1_original (View cell in 3D, select Cell density mechanisms in drop down box, then Edit Density Mechanisms). Use the cell density on your original soma section. See menu item Help -> Units for units in neuroConstruct and NEURON, or (after placing the mechanism on the section) select Pick Sections/Segments in the drop down box, click on the section, click on Biophysics, which will show a list of the biophsical quantities associated with the section.
  8. Add a plot of the internal state variables of the channel, e.g. KChannel:n. See Ex4-NEURONGENESIS or Ex10-MainenEtAl for examples. Run the network again and you should see a difference between the cell with the active channel and that with only a passive conductance.
  9. Add an initial version of the channel as a ChannelML based Cell Mechanism. Select Add ChannelML from Template, selecting KConductance, and give the channel an appropriate name. Add a plot of its internal variable (see Ex10-MainenEtAl) and put this in the same graph as the prevous channel's.
  10. Now edit the values in the XML to match the equations in the mod file (preferably in an external text editor). With a simple channel it should just be a case of altering the parameters for the linoid, sigmoid etc. descriptions of the rate equations, the reversal potential and the gate powers. Don't forget to add lots of comments and metadata! For more complicated channels, see the examples in Ex7-GranuleCell and online.
  11. Make sure to reload the ChannelML into neuroConstruct after you've edited the XML externally. Add this channel to Cell1_CML and rerun the simulation with this new channel. Looking at the mod file generated from the XML will help in debugging.
  12. Getting good agreement can depend on the accuracy k value in Akd, make sure there is an accurate value for this in case 1/k is used in the original file.
  13. For complete accuracy, use table impl prefs taken from original mod file, i.e. from TABLE minf, mexp DEPEND dt, celsius FROM -100 TO 100 WITH 200. Note: if comparing values of v > 100mV use a bigger table (since values for v past the end of the table will use earlier alpha value, etc.)
  14. Make sure the units are set correctly in the ChannelML file.
  15. Be careful to use the temperature, ek, ena of the previous models!
  16. Once you have agreement on NEURON to the original mod, create another Simulation Configuration with only the ChannelML based cell (and the plots, etc.) and try running it on GENESIS.
  17. If you've gotten this far, congratulations. If you have specific problems or think something is outside the scope of the NeuroML specifications, please get in touch