GENESIS: Documentation

Related Documentation:

• Creating GENESIS 3 Simulations with Python
• Perfect Clamp
• Tutorial 1
• Tutorial 2
• Tutorials

Convert a GENESIS 2 Simulation to GENESIS 3

Background

In Tutorial 1, you learned to use the GENESIS Interactive Shell (G-shell) to create a simple cell, explore it, and run the simulation from the G-shell command line.

Tutorial 2 continues to show how to use the G-shell to load and simulate predefined model neurons that come bundled with the GENESIS distribution in the single cell model library. As with the Purkinje cell model used in the tutorial these have been saved in the library in NDF format.

Of course, as mentioned in Tutorial 2, it would be very difficult to create a large multi-compartmental cell model by entering commands in the G-shell.

In the future, GENESIS will support import of models represented in neural exchange formats such as NeuroML, and from scripts that use a Python-based scripting language. This tutorial is devoted to the process of loading existing GENESIS 2 simulation scripts into the G-shell, running them, and converting them to GENESIS 3 NDF format.

In GENESIS 2, scripts are interpreted by the Script Language Interpreter (SLI), so these scripts are in the “SLI format”. The process of creating a simulation in this format is described with examples in the GENESIS Modeling Tutorial for GENESIS 2. This is part of a larger package The Ultimate GENESIS Tutorial Distribution that is gradually being converted to GENESIS 3. Some familiarity with the GENESIS Modeling Tutorial section ”Building a cell the easy way”, is assumed in what follows below.

The simulation script used as an example in ”Building a cell the easy way” is called simplecell.g, and it uses the cell reader with the file cell.p to create a simple two-compartment neuron. The soma compartment /cell/soma contains Hodgkin-Huxley type voltage-activated sodium and potassium channels (implemented as tabchannels), and the single dendrite compartment /cell/dend contains excitatory and inhibitory synaptically activated channels (implemented as synchans).

Although many GENESIS 2 scripts may be run or imported with little or no modification, there are a few differences between GENESIS 2 and GENESIS 3 that may require some changes.

In GENESIS 2, there is no distinction between objects that are used to represent biological models (e.g. compartments and channels), device objects that are used to provide input to the model (e.g. a pulsegen or randomspike), those that provide output (e.g. asc_file or disk_out), analysis objects (e.g. various modes of the table object, interspike, autocorr, or peristim objects), or graphical objects for control or visualization. All of these may be freely combined in any desired manner in a GENESIS 2 script. This accounts for the great versatility and flexibility of scripted GENESIS simulations.

Although GENESIS 3 aims for nearly complete backwards compatibility with GENESIS 2, this does not extend to the XODUS graphical objects and commands, which are based on 1990’s X window system widgets. Modern Python-based graphics have now been developed for GENESIS 3, which allows the scriptable construction of custom GUIs by the user. However, these do not attempt to reproduce the old XODUS widgets and command syntax to the point of allowing automatic conversion of existing scripts that use XODUS. The scripting of XODUS-like GUIs for G-3 simulations in Python is taken up in the tutorial Creating a G-3 GUI with Python.

Also, the GENESIS 3 User Workflow makes a distinction between these different functionalities, based on a modeling or experimental paradigm involving an iterative process of model design, experimental design (e.g. providing stimuli to the model), running the simulation, and output and analysis of results. The Overview of the G-3 CBI Architecture describes how this separation of functionality is incorporated into the internal representation of the simulation. Commands given in the G-shell allow these to be incorporated into G-3, while retaining the flexibility of GENESIS 2.

For these reasons, it is best to separate these functional categories by making changes to the SLI script which will facilitate the conversion.

Excluding the initial comments, the original simplecell.g script reads:

Fortunately, as in most GENESIS 2 scripts, the graphical commands have been isolated to the included script graphics.g. For use with GENESIS 3, this file should not be included, and there will need to be commands that write equivalent simulation results to files, instead of a graph.

The example script simplecell-g3.g illustrates how the orignal script can be reorganized to run under either GENESIS 2 or 3. When creating GENESIS 2 scripts that will eventually be converted to run under GENESIS 3, the organization described below will help you to avoid potential problems under GENESIS 3.

By defining some Boolean constants at the begining of the script, you can easily change between running with GENESIS 2 and XODUS graphics, and GENESIS 3 in batch mode with output to a file.

The script defines and uses the functions

• make_cell Creates the cell, using readcell and the cell parameter file cell.p. The protodefs.g file defines the prototype channels and other elements referenced by cell.p.
• make_input Provides input to the cell. In this case it merely sets the /cell/soma inject field to the desired value of injection current.
• make_output Provides output of the /cell/soma Vm to a file, using an asc_file object.
• step_tmax Runs the simulation for a time tmax, and optionally echoes information to the G-shell, such as start and end times of a run.

These are used in the main section of the simulation, which reads:

Running the simulation in backwards compatibility mode

The first step in converting the simulation is to verify that it will execute without errors under the G-shell using the ns-sli module. This runs the simulation under the backwards compatibility mode. This will be somewhat slower than in native G3 mode, and does not provide the advanced features of G3, but is recommended, to be sure that the model can be converted. The steps are simply:

The output should be similar to that when running under GENESIS 2. In fact, it was not strictly necessary to isolate the code for providing input and output to separate functions, in order for the simulation to run properly in NS-SLI mode.

Converting the cell model to NDF format

To make full use of the capabilities of GENESIS, the cell model should be converted into NDF format. This can be done with the sli_load and ndf_save commands that are available in the G-shell:

To be sure that you remember the name that was assigned to your cell model (/cell, in the simplecell-g3.g script) give the command:

These are in fact the element trees that were created when the simulation was run in GENESIS 2, or with sli_run in the G-shell. If you like, you can dig deeper with commands such as list_elements /cell/soma.

At this point you can explore the loaded model with some of the other tools provided by the G-shell. Don’t forget to use help commands to obtain a list of commands available in the current version of the G-shell, in addition to those described in Tutorials 1 and 2.

The final step is to save the cell representation to NDF format, specifying the file name for the saved representation:

Running the converted cell model in the G-shell

Now, we are ready to load and run the model in NDF format.

At this point, you can explore the model as before, using the examples given in Tutorial 2 for the /Purkinje model. The simplest way to provide stimuli to the model and to output the results is to use the built-in G-shell tools for this, rather than scripting your own input and output functions. Some of these are also illustrated in Tutorial 2.

Provide current injection:

Provide output of the soma membrane potential to a file, specifying a filename or path other than the default of /tmp/output:

Heccer, the numerical solver used by G-3 for compartmental cell models and channels, uses a default simulation time step of 20 microseconds. To set the time step to the 50 microsecond value used in the original GENESIS 2 simulation, give the command:

Finally, run the simulation on the model /cell for 0.5 seconds:

The G3Plot toolkit is a suite of Python-based tools under development for visualizing and analyzing the output of GENESIS simulations. Many of the tools are based on Matplotlib that allow analysis capabilities similar to Matlab to be provided within GENESIS. As they are developed, they are being integrated into G-3 for direct use without the necessity of creating files.

At present, if G3Plot has been installed, the results from simplecell-g3.ndf may be compared with those from the GENESIS 2 run of simplecell-g3.g with the command

Converting user-defined input and output functions

Although the G-shell will continue to gain more paradigms for model input or output that will be sufficient for most single cell modeling, it will sometimes be necessary to script custom functions in GENESIS 2 to provide unique capabilities. This is particularly likely to be true with network and subcellular level simulations.

Recent advances in the development of the G-3 SSPy module now include an Applications Programming Interface (API) for scripting G-3 simulation in Python. This allows models to be interfaced with objects from the Experiment module, including a variety of output objects and input objects such as pulse generators and voltage or current clamps. Thus, there are no immediate plans to extend the capabilities of the G-shell sli_load and ndf_save commands to convert the make_input and make_output functions that are used in the script simplecell-g3.g into G-3.

The next tutorial in this series Creating GENESIS 3 Simulations with Python demonstrates how to do the equivalent of these functions in Python, including the plotting of results.