NeuroML v2

The current stable version of NeuroML is v2.1, and can the schema for this be seen here. The following figure, taken from Cannon et al. 2014 ([CGC+14]) shows some of the elements defined in the NeuroML version 2 (note: these core elements haven’t changed since that publication).

Elements defined in the NeuroML schema, version 2.

Fig. 35 Elements defined in the NeuroML schema, version 2.

You can see the complete definitions of NeuroML 2 entities in the following pages. You can also search this documentation for specific entities that you may be using in your NeuroML models.

Examples of files using the NeuroML 2 schema, and some of the elements they use are:

Example file

NeuroML elements used

A simple cell with a morphology & segments arranged into groups

<cell>, <morphology>, <segment>, <segmentGroup>

A cell specifying biophysical properties (channel densities, passive electrical properties, etc.)

<membraneProperties>, <intracellularProperties>, <channelDensity>

A simple HH Na+ channel

<ionChannelHH>, <gateHHrates>, <HHExpLinearRate>

Some of the simplified spiking neuron models which are supported

<iafCell>, <izhikevich2007Cell>, <adExIaFCell>, <fitzHughNagumoCell>

Synapse models

<alphaSynapse>, <expTwoSynapse>, <blockingPlasticSynapse>, <doubleSynapse>

A network of cells positioned in 3D and synaptically connected

<network>, <population>, <projection>, <connection>, <inputList>

NeuroML files containing the XML representation of the model can be validated to ensure all of the correct tags/attributes are present.

But how do we know how the model is actually meant to use the specified attributes in an element? The schema only says that leakReversal, thresh, etc. are allowed attributes on iafCell, but how are these used to calculate the membrane potential? The answer is LEMS…

Defining dynamics in LEMS

While the valid NeuroML entities are defined in the schema, their underlying structural and mathematical information must also be defined. For this, NeuroML version 2 makes use of LEMS (Low Entropy Language Specification).

LEMS is an XML based language with interpreter originally developed by Robert Cannon for specifying generic models of hybrid dynamical systems.

  • ComponentType elements define the behaviour of a specific type of model and specify Parameters, StateVariables, and their Dynamics and Structure can be defined as templates for model elements (e.g. HH ion channels, abstract cells, etc.). Similar to a class in object oriented programming.

  • Components are instances of these with specific values of Parameters (e.g. HH squid axon Na+ channel, I&F cell with threshold -60mV, etc.). Similar to an object in object oriented programming.

Figure showing relationship between LEMS and NeuroML2

Fig. 36 This image (from Blundell et al. 2018 ([BBC+18])) shows the usage of LEMS ComponentTypes and Components in NeuroML. Elements in NeuroML v2 are Components which have a corresponding structural and mathematical definition in LEMS ComponentTypes.

In the left of the figure, examples are shown of the (truncated) XML representations of:

On the right the definition of the structure and dynamics of these elements in the LEMS language is shown. Each element has a corresponding ComponentType definition, describing the parameters (as well as their dimensions, not shown) and the dynamics in terms of the state variables, the time derivative of these, any derived variables, and the behaviour when certain conditions are met or (spiking) events are received.

NeuroML 2 Component Type definitions in LEMS

The standard set of ComponentType definitions for the core NeuroML2 elements are contained in a curated set of files (below) though users are free to define their own ComponentTypes to extend the scope of the language.

Here, for example, the izhikevich2007Cell is defined in the NeuroML schema as having the following allowed attributes:

<xs:complexType name="Izhikevich2007Cell">
    <xs:complexContent>
        <xs:extension base="BaseCellMembPotCap">
            <xs:attribute name="v0" type="Nml2Quantity_voltage" use="required"/>
            <xs:attribute name="k" type="Nml2Quantity_conductancePerVoltage" use="required"/>
            <xs:attribute name="vr" type="Nml2Quantity_voltage" use="required"/>
            <xs:attribute name="vt" type="Nml2Quantity_voltage" use="required"/>
            <xs:attribute name="vpeak" type="Nml2Quantity_voltage" use="required"/>
            <xs:attribute name="a" type="Nml2Quantity_pertime" use="required"/>
            <xs:attribute name="b" type="Nml2Quantity_conductance" use="required"/>
            <xs:attribute name="c" type="Nml2Quantity_voltage" use="required"/>
            <xs:attribute name="d" type="Nml2Quantity_current" use="required"/>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>

Correspondingly, its ComponentType dynamics are defined in the LEMS file, Cells.xml. (Note: you do not need to read the XML LEMS definitions, you can see this information in a well formatted form here in the documentation itself)

<ComponentType name="izhikevich2007Cell"
    extends="baseCellMembPotCap"
    description="Cell based on the modified Izhikevich model in Izhikevich 2007, Dynamical systems in neuroscience, MIT Press">

    <Parameter name="v0" dimension="voltage"/>

    <!--
    Defined in baseCellMembPotCap:
    <Parameter name="C" dimension="capacitance"/>
    -->
    <Parameter name="k" dimension="conductance_per_voltage"/>

    <Parameter name="vr" dimension="voltage"/>
    <Parameter name="vt" dimension="voltage"/>
    <Parameter name="vpeak" dimension="voltage"/>

    <Parameter name="a" dimension="per_time"/>
    <Parameter name="b" dimension="conductance"/>
    <Parameter name="c" dimension="voltage"/>
    <Parameter name="d" dimension="current"/>

    <Attachments name="synapses" type="basePointCurrent"/>

    <Exposure name="u" dimension="current"/>

    <Dynamics>

        <StateVariable name="v" dimension="voltage" exposure="v"/>
        <StateVariable name="u" dimension="current" exposure="u"/>

        <DerivedVariable name="iSyn"  dimension="current" exposure="iSyn" select="synapses[*]/i" reduce="add" />

        <DerivedVariable name="iMemb" dimension="current" exposure="iMemb" value="k * (v-vr) * (v-vt) + iSyn - u"/>

        <TimeDerivative variable="v" value="iMemb / C"/>
        <TimeDerivative variable="u" value="a * (b * (v-vr) - u)"/>

        <OnStart>
            <StateAssignment variable="v" value="v0"/>
            <StateAssignment variable="u" value="0"/>
        </OnStart>

        <OnCondition test="v .gt. vpeak">
            <StateAssignment variable="v" value="c"/>
            <StateAssignment variable="u" value="u + d"/>
            <EventOut port="spike"/>
        </OnCondition>

    </Dynamics>

</ComponentType>

We can define Components of the izhikevich2007Cell ComponentType with the parameters we need. For example, the izhikevich2007Cell neuron model can exhibit different spiking behaviours, so we can define a regular spiking Component, or another Component that exhibits bursting.

<izhikevich2007Cell id="iz2007RS" v0 = "-60mV" C="100 pF" k = "0.7 nS_per_mV"
                    vr = "-60 mV" vt = "-40 mV" vpeak = "35 mV"
                    a = "0.03 per_ms" b = "-2 nS" c = "-50 mV" d = "100 pA"/>

Once these Components are defined in the NeuroML document, we can use Instances of them to create populations and networks, and so on.

You don’t have to write in XML…

A quick reminder that while XML files can be edited in a standard text editor, you generally don’t have to create/update them by hand. This guide goes through the steps of creating an example using the izhikevich2007Cell model in Python using libNeuroML and pyNeuroML

Using LEMS to specify the core of NeuroML version 2 has the following significant advantages:

  • NeuroML 2 XML files can be used standalone by applications (exported/imported) in the same way as NeuroML v1.x, without reference to the LEMS definitions, easing the transition for v1.x compliant applications

  • Any NeuroML 2 ComponentType can be extended and will be usable/translatable by any application (e.g. jLEMS) which understands LEMS

The first point above means that a parsing application does not necessarily have to natively read the LEMS type definition for, e.g. an izhikevich2007Cell element, it just has to map the NeuroML element parameters onto its own object implementing that entity. The behaviour should be the same of course and should be tested against the reference LEMS implementation (jLEMS).

The second point above means that if an application does support LEMS, it can automatically parse (and generate code for) a wide range of NeuroML 2 cells, channels and synapses, including any new ComponentType derived from these, without having to natively know anything about channels, cell models, etc.

jnml and pynml handle both LEMS and NeuroML 2.

jNeuroML and pynml handle both LEMS and NeuroML 2. They bundle jLEMS together with the LEMS definitions for NeuroML 2 ComponentTypes, and can simulate any LEMS model as well as many NeuroML 2 models.