libNeuroML and PyLEMS: using Python to combine procedural and declarative modeling approaches in computational neuroscience

Abstract

NeuroML is an XML-based model description language, which provides a powerful common data format for defining and exchanging models of neurons and neuronal networks. In the latest version of NeuroML, the structure and behavior of ion channel, synapse, cell, and network model descriptions are based on underlying definitions provided in LEMS, a domain-independent language for expressing hierarchical mathematical models of physical entities. While declarative approaches for describing models have led to greater exchange of model elements among software tools in computational neuroscience, a frequent criticism of XML-based languages is that they are difficult to work with directly. Here we describe two Application Programming Interfaces (APIs) written in Python (http://www.python.org), which simplify the process of developing and modifying models expressed in NeuroML and LEMS. The libNeuroML API provides a Python object model with a direct mapping to all NeuroML concepts defined by the NeuroML Schema, which facilitates reading and writing the XML equivalents. In addition, it offers a memory-efficient, array-based internal representation, which is useful for handling large-scale connectomics data. The libNeuroML API also includes support for performing common operations that are required when working with NeuroML documents. Access to the LEMS data model is provided by the PyLEMS API, which provides a Python implementation of the LEMS language, including the ability to simulate most models expressed in LEMS. Together, libNeuroML and PyLEMS provide a comprehensive solution for interacting with NeuroML models in a Python environment.

Keywords: API; LEMS; NeuroML; Python; SWC; model specification; modeling; standardization.

Figure 1

Structure of NeuroML v2. (A) Overall structure of NeuroML v2. The top-level element of NeuroML, neuroml, contains a number of child elements of various types. A morphology element contains lists of segment and segmentGroup elements defining the structure of the neuronal morphology. Various cell types are allowed including point neurons such as izhikevichCell, but also cell elements which can have detailed morphologies and biophysicalProperties for ion channel densities etc. Ion channels of two main types can be specified, based on either the Hodgkin-Huxley formalism or using a kinetic scheme-based description. Allowed synapse models include single and double exponential conductance waveform models. Current inputs to cells include square pulse and sine waves. Networks contain populations of cells, with projections between them and lists of inputs. Lines ending in diamonds show containment of elements. Filled diamonds indicate that multiple child elements of that type are permitted, unfilled diamonds indicate only one child of that type is permitted. Not all elements in NeuroML v2 are shown. A full description of all elements in NeuroML v2 is available at http://www.neuroml.org/NeuroML2CoreTypes. (B) A partial example of a NeuroML v2 file in XML. This model contains a cell with a morphology, an ion channel mechanism and a synapse as well as a network with a population of the cells and a projection for synaptic connections between them.

Figure 2

Relationship between NeuroML v2 and LEMS. (A) Model definitions in NeuroML v1.x are specified as textual descriptions in human-readable documentation. (B) In NeuroML v2, components have a corresponding structural and mathematical definition in LEMS. A number of examples of ComponentTypes in LEMS are shown. A ComponentType izhikevichCell is defined in LEMS (i), and its parameters are specified as a, b, c, d, and thresh. The Dynamics of the ComponentType defines the state variables v and U. LEMS specifies how these vary with time. Conditions such as when the membrane potential crosses firing threshold are also defined using OnConditions. This example of izhikevichCell has been simplified to remove scaling factors for unit correctness. Shortened examples of a synapse (ii) and an ion channel model (iii) are also shown. Instances of LEMS ComponentTypes can be created by specifying the values for each of the parameters. These instances are represented in NeuroML files. The full NeuroML v2 ComponentType definitions are contained in XML files (including Cells.xml, Synapses.xml, Channels.xml as shown here), which have been developed by the NeuroML project and are available at http://www.neuroml.org/NeuroML2CoreTypes.

Figure 3

Examples of NeuroML and LEMS models specified in XML and equivalent models specified with Python using the libNeuroML and PyLEMS APIs, respectively. The XML code on the left is generated automatically by the Python code on the right. The NeuroML example describes a soma segment as a 3D cylinder. The LEMS example illustrates how a simple integrate and fire cell can be defined.

Figure 4

An overview of the structure of the libNeuroML API. The API is divided into four main modules (left), the largest of which (neuroml) consists of Python classes generated from the NeuroML XML Schema Document. There is roughly a one to one correspondence between the NeuroML elements and Python classes. These classes can be split into a number of broad classifications (right) based on the types of models they represent. Examples of Python code using the classes is also shown on the right. Extra modules have been created to facilitate loading or writing NeuroML (in XML or other serialization formats) and for validating NeuroML files.

Figure 5

An overview of the structure of the PyLEMS API. Classes are present for each of the main elements of the LEMS language (left). Examples of using these in a Python script are shown on the right. The Model class is a container which can be used to hold the model and can export this to an XML file. Generated or other LEMS files can also be validated through the API. More information about the LEMS elements on which the classes above are based can be found here: http://lems.github.io/LEMS/elements.

Figure 6

Disk write time for synthetic morphologies in different serialization formats. Error bars represent one standard deviation (sample size = 10).

Figure 7

Example of creation of a network of integrate-and-fire neurons using libNeuroML (right) and the equivalent XML representation (left). The network consists of two populations of five cells each. The cell type is a simple integrate-and-fire cell using the NeuroML element iafCell. A prototype component is created for this setting all of the parameters, along with a prototype synapse based on expTwoSynapse. A projection is created between the two populations and for each cell in the presynaptic population, an input current is applied, and connections are made to the postsynaptic cells with probability 0.3. The XML on the left is an example of one network instance which can be generated from this script.

List 1

Example of loading a NeuroML multicompartmental cell morphology with libNeuroML and using helper functions to calculate some of the properties (area and volume) of the cell. Methods to calculate area and volume have been inserted into the code generated from the NeuroML Schema.

Figure 8

Use of NeuroML and libNeuroML in the OpenWorm project. (A) The full set of 302 neurons in the OpenWorm model are available in NeuroML format and are visualized here. Each cell, together with its spherical soma, is a different uniform color. Connections between neurons are shown as straight lines varying in color from presynaptic point (green) to postsynaptic point (red). These connections were generated by a Python script using libNeuroML based on connectivity data for pairs of cells. The long straight connections from cells in the midpoint of the worm to the head indicate an error in the connections in the data. (B) Same network as (A), but only the somas of the cells, along with the synaptic connections are shown. The majority of connections are a short length due to the overlap between the neurites of the presynaptic and postsynaptic cells.

Figure 9

The Hindmarsh and Rose spiking neuron model. A LEMS ComponentType for this model is built adding the three state variables (x, y, z) and the eight fixed parameters required for instances of the model. Time derivatives for the state variables are specified using derived variables to shorten the required expressions. One Component with a particular set of parameters is created. This Python script produces valid LEMS XML which can be used by any LEMS-compliant simulator to simulate the model. The inset shows the behavior of the state variable x (corresponding to the model neuron's membrane potential) when the model is executed in PyLEMS.