The Channel Model Database (ChannelDB)

ChannelDB is an implementation of a database of ionic conductance models stored in simulator-independent NeuroML format. It was developed as a means of sharing channel models between different neural simulators. I is also one of the first core components of the Modelers Workspace (MWS). At present, ChannelDB is implemented as a stand-alone module, with its own graphical user interface to the database, which is implemented with MySQL. After further development, the ChannelDB GUI will be merged into the MWS.

The MWS (http://www.modelersworkspace.org) is intended to be a graphical user interface to a collection of software tools that enable users to interact over the WWW with databases of models and data. It will provide facilities for searching multiple remote databases for model components based on various criteria; visualizing the characteristics of the components retrieved; creating new components, either from scratch or derived from existing models; combining components into new models; linking models to experimental data as well as online publications; and interacting with simulation packages such as GENESIS to simulate the new constructs.

Two of the main components of the MWS design are a detailed design for the GUI (http://www.modelersworkspace.org/mws-overview/mws-overview.html), and the simulator-independent repesentation scheme for neural models in XML. (http://www.modelersworkspace.org/mws-rep/mws-rep.html). In a collaboration with the group led by Nigel Goddard, our representation was incorporated into the jointly-developed NeuroML language for model specification. (For details, see http://www.neuroml.org.)

The NeuroML development kit parser (from http://www.neuroml.org/docs) is used to create Java objects from the NeuroML format (XML) files stored in the database. These are then accessed with Java software to create simulation scripts for the particular simulator. The first implementation of a parser to create simulation scripts is (of course) for GENESIS.

We are releasing version 1.0 of ChannelDB with all source code in the hope that others will contribute to its development.

The files in this package will let you

• Search a small remote database of ion channel models to retrieve and view their descriptions and NeuroML representations, and generate simulator scripts from the model representation.
• Set up your own database of ion channel models
• Extend ChannelDB with the addition of parsers for other simulators, and with Java classes to cover other types of channels.

To use ChannelDB, you need to:

• Unpack the distribution ChannelDB.tgz
• Install a recent version of Java (from http://java.sun.com/). The ChannelDB software was developed with Java version 1.4, but will likely work with version 1.3.
• Download the NeuroML development kit from http://www.neuroml.org/docs, and install it. You will need the July 9, 2002 or later version, in order to have the additional channel classes that were created for ChannelDB.
• Download and install the MM.MySQL JDBC driver. This will allow Java programs to access MySQL databases. (From http://mmmysql.sourceforge.net.)
• Set the proper CLASSPATH environment variable to allow Java to find the needed classes. This can be simplified if you:
  • As suggested in the MM.MySQL documentation, copy the jar file for MM.MySQL into $JAVA_HOME/jre/lib/ext. ($JAVA_HOME is the path to your java distribution, e.g. "/usr/java/j2sdk1.4.0/).
  • Either install neuroml in the ChannelDB directory, or make a symbolic link so that it appears to be in ChannelDB.
  • set your CLASSPATH environment variable to "./neuroml/classes:./neuroml/jars/jdomxerces.jar:./jep-2.21.jar:." and execute the programs from the ChannelDB directory.

ChannelDB.java and ChannelDB.class are the main source and class files for the ChannelDB GUI. If everything has been installed as described above, you should be able to bring it up by typing

    java ChannelDB

within the ChannelDB directory.

The Graphical User Interface for the Channel Database consists of a menu bar with File and Help menus, and main three panels.

The File menu has a "Connect" entry that must be used to connect to the database before a database search can be performed. It brings up a dialog that has default values that will connect to a small example database ("chan1") that is readable (but not modifiable) by any remote user. If you connect to your own database, you will want to change these values. File/Exit is used to quit.

The top "Search" panel has fields for specifying the Principal Ion(s) (one or more, separated by spaces) and space-separated Keywords to search for in the datbase "ion" and "keywords" fields. At present, the search is just a simple OR of these, so that all entries will be returned that match one of the ions or one of the keywords. If both fields are blank, all database entries will be returned,

The results of clicking on the "Search" button are displayed in the middle "Results" panel, with each search result that is returned displayed on a line giving the channel name and description. A result is selected for further inspection by clicking on it.

After a result has been selected, the "Show Details", Show XML" or "Show Simulator Script" button can be clicked. This will display the appropriate text in the scrollable text area in the bottom "Parse" panel.

• Show Details - Retrieves the XML description of the selected channel from the database, parses it, and displays detailed information about the channel that is contained only in the XML description.
• Show XML - Retrieves the XML description of the selected channel and displays it.
• Show Simulator Script - Retrieves the XML description of the selected channel from the database, parses it, and generates a simulator script that implements the channel. The simulator is selected from the pull-down list at the right. At present, the only simulator on the list is GENESIS.

The bottom text area is also pressed into service for display of Help information, and status, warning, or error messages.

The "Save to File" button writes the text that is displayed into the file spedified in the text field to its right. The default name of the file (which can be changed) is the channel name, plus a "dot" extension appropriate to a plain text description, XML description, or simulator script. Note that the text area is editable, so that the XML or script can be modified before it is saved.

Setting up your own channel database

To set up your own database, you will need a simple relational database that uses standard SQL syntax for database queries. ChannelDB was implemented using MySQL, but it should probably work with small modifications for other databases, such as PostgreSQL. You can get MySQL from http://www.mysql.com. It is also provided with many Linux distributions. Once you have MySQL up and running, you will need to create a database and set up privileges for users. The procedure is described in detail in the HTML MySQL documentation.

For the database at dogstar.colorado.edu, I used the commands

  GRANT SELECT ON ChannelDB.* TO testuser@localhost IDENTIFIED BY 'labrat';
  GRANT SELECT ON ChannelDB.* TO testuser@"%" IDENTIFIED BY 'labrat';

You will also want to grant ALL PRIVILEGES to the database administrator.

Then

  use ChannelDB;

  CREATE TABLE chan1 (uniqueID VARCHAR(64), name VARCHAR(32), ion
  VARCHAR(32), keywords VARCHAR(255), description VARCHAR(255),
  xml_document TEXT);

Test your database by running "mysql -u testuser -p". Enter the password "labrat" to the prompt, and give the commands:

mysql> use ChannelDB;
mysql> describe chan1;

You should get

+--------------+--------------+------+-----+---------+-------+
| Field        | Type         | Null | Key | Default | Extra |
| uniqueID     | varchar(64)  | YES  |     | NULL    |       |
| name         | varchar(32)  | YES  |     | NULL    |       |
| ion          | varchar(32)  | YES  |     | NULL    |       |
| keywords     | varchar(255) | YES  |     | NULL    |       |
| description  | varchar(255) | YES  |     | NULL    |       |
| xml_document | text         | YES  |     | NULL    |       |
+--------------+--------------+------+-----+---------+-------+

Before you can try out "SELECT" queries, you will need to populate the database.

Entering channel models into the database

To enter a channel model into the database, you need to:

1. Create an xml file in proper NeuroML format that describes the channel parameters, and other descriptive information.
2. Put the xml file into the database along with the information for the uniqueID, name, ion, keywords, and description fields.

The second step is easy. The java program Neuroml2database takes an XML (NeuroML) file name as an argument and stores the XML text along with descriptive information into the database. The easily-accessed descripive information is used to search the database.

Neuroml2database.java defines the host to be "localhost", and the user to be "testuser" with password "labrat". You probably don't want to give "testuser" permission to add items to the database, so change these to refer to the database administrator.

Of course, you should expect ChannelDB to include a sophisticated GUI for entering channel model specifications and descriptive information, in order to generate the xml representation. Unfortunately, this hasn't yet been implemented. (See the request for contributions to the development above!)

The directory ChannelDB/MakeChannels includes a number of separate Java programs to create the NeuroML descriptions. Presently, when I want to implement a new channel, I edit (hack) the file for a channel that is similar. The file "Make_Kc_hip_traub91.java" is a good example of the implementation of a voltage and Ca concentration dependent channel. (The C current from the 1991 Traub hippocampal CA3 pyramidal cell model)

Implementation and programming notes

These are some rough notes to help those who would like to modifiy or extend ChannelDB. The ChannelDB GUI was implemented using the "Swing" Java Foundation Classes.

The main file ChannelDB.java uses:

• ConPanel.java defines the JDialog that is used for entering the host, username, password, database, and table for the database, and making the database connection.
• SearchPanel.java defines the JPanel for specifying search criteria. It could certainly be improved, with JToggleButtons to select between OR and AND searches of ions and keywords.
• ResultsPanel.java defines the JPanel used to display the results of a database query. It uses a JList in a JScrollPane.
• ParsePanel.java is used to display the description, xml source, or simulator script of the selected channel.
• Neuroml2GENESIS.java is the class that contains the method neuroml2genesis, used to convert a NeuroML (XML) string into a string that holds a GENESIS script to create a channel. It is fairly well commented, and could be used as a start for the development of Neuroml2NEURON, Neuroml2SurfHippo, etc.
• TestNeuroml2genesis.java is not used by ChannelDB, but is a useful tool for testing the use of Neuroml2GENESIS directly on NeuroML files, without the need for a database or GUI. It could easily be modified to test parsers for other simulators.
• jep-2.21.jar is a GPL Java Expression Parser that is used by Neuroml2GENESIS to evaluate an equation for a channel rate variable (obtained from an EquationHHRate class), so that it can be implemented as a tabulated channel. You can get the latest version from http://jep.sourceforge.net.
• Exp.java is an extension to the Java Expression Parser (JEP) to allow an exponential function to be expressed as "exp(x)", rather than "e^x". Newer versions of JEP may include this extension.

In addition, there are the "Make_*.java" files mentioned above, in ChannelDB/MakeChannels, and a directory ChannelDB/xml that contains NeuroML files for some of the channels in the database.

The ChannelDB/docs directory contains the HTML documentation for ChannelDB, (this file) with links to the javadoc documentation for the classes defined for ChannelDB.

How it works

You will want to look at the javadoc documentation (within the NeuroML development kit) for the documentation of the neuroml.model.channel classes that are used by ChannelDB.

The channel classes used by ChannelDB are:

• DBChannel.java - This is a wrapper class for channels that will be stored in a database, similar to NeuromlPkg or ChannelPkg, but with additional descriptive fields, and without other more general model fields. It is used for all models that are stored in ChannelDB.
• HHChannel - This is the class used for all the (Hodgkin-Huxley type) channels in the database, with the exception of the "channel" ConcenPool, which is a concentration pool, not really a channel.
• HHVGate.java - This is used as a member of the gates set of a HHChannel, instead of ParameterizedHHVGate or TabulatedHHGate to provide more flexibility in the choice of what Rate classes are used for forwardRate and backwardRate. This is done by casting them to The appropriate subclass of HHRate. It also provides additional fields to describe the gate.
• HHCGate.java - An ionic concentration-dependent gate, analogous to the voltage-dependent HHVGate. It provides an additional field for a reference to the object that provides the source of the ionic concentration.
• HHRate - The superclass for the specialized forms for the rate variables.
• ParameterizedHHRate - A subclass of HHRate that expresses rate variables in a parameterized form "rate = (A + BV) / (C + D exp((E + V)/F))". Many Hodgkin-Huxley type rate equations can be cast into this general form.
• TabulatedHHRate.java - A subclass of HHRate to complement the existing ParameterizedHHRate and EquationHHRate classes. It allows a gate's forwardRate or backwardRate to be specified by a table at equally spaced voltage (or concentration) points.
• EquationHHRate - A subclass of HHRate that expresses the rate variables as equations.

Notes on the EquationHHRate rateExpression: In principle, rateExpression can be any String expression. In practice, it should conform to the equation syntax defined for the Modelers Workspace (http://www.genesis-sim.org/hbp/mws-rep/mws-rep.html), in order to allow it to be parsed by any conforming equation parser. The syntax is similar to that used in C and Java, with the compact version of the "if" statement that is used in Java, e.g.

           (x >  Erest) ? 5*exp(-50*(x - Erest)) : 5.0

where the expression following "?" is executed if the condition is true, and the expression after ":" is executed if the condition is false. However, this syntax, and any other one using "<" to denote "less than", presents problems for the JDOM XML parser, unless "<" is encoded as "&lt;". For this reason, it is best to change the order of the expressions to allow the use of ">" or ">=". Another assumption made here is that the independent variable for a voltage or concentration is "x", and that an optional constant "Erest" is allowed in equations.

• ConcenPool.java - Describes a single shell model for a concentration pool, with a buildup of concentration proportional to an incoming current and a time constant for decay, similar to the GENESIS Ca_concen object. The object providing the source of concentration to a HHCGate is typically formed from this class. The source of currents is provided by a set of objects of class CurrentSource.
• CurrentSource.java - Used by ionic concentration pools to provide information about the object providing an ionic current.

NeuroML description files are generated by creating Java objects that represent the channel description. This is a declarative representation that describes everything about the model, not a procedural description of how to implement the model. For use with ChannelDB, the object is of class DBChannel, which contains fields for the HHChannel, ConcenPool, gate and rate objects that are used. Once this Java object that uses known NeuroML classes is created, it is converted to XML with a single statement such as "XMLOut.toString(dbc)" or "XMLOut.toFile(dbc, filename)".

NeuroML descriptions are parsed and converted to the original DBChannel objects so that the descriptive information may be obtained, or once the model parameters are accessible within a DBChannel object, some simple string manipulation can be used to describe the procedure for creating the model in the desired simulator scripting language.

The process is illustrated in this diagram.

Please send any comments, questions, and improvements to: