List of suggestions for NeuroML v2.0 network elements/NineML User Layer

The following are some initial thoughts on the elements needed for network descriptions in NeuroML v2.0 based on discussions in the INCF Multiscale Modelling Program.

See here for how this package relates to other developments towards NeuroML 2.

A key distinction in NetworkML version 1.x is between:

Template based representations: a concise description of a network in terms of a template from which to generate many instances of cell positions and connections, e.g. "place 200 cells randomly in a 3D region" (example in v1.8.1).
Instance based representations: an explicit listing of all instances of cell positions and connections (example in v1.8.1).

While there are an increasing number of tools which support the instance based representation of NetworkML v1.x, one of the main drawbacks of this version is the narrow range of templates for expressing the wide range of structures and connectivities encountered in neuronal network models. Another shortcoming of the current version is that it is not possible to create hierarchical networks, e.g. "create a subnetwork of 3 populations (2 laid out on regular 3D grids, and one randomly placed in a rectangular box above the others) and repeat that network on a 3x3 grid". Below is an image of the type of network which needs to be created.

Members of the NeuroML initiative are participating in the INCF Multiscale Modelling Program which is developing standards for expressing large scale network models (under the name NineML) and the elements for describing networks in NeuroML v2.0 will be compatible with the standards developed there.

The following are some elements which would extend the range of network structures which could be expressed in NeuroML version 2.0, and which could be useful input into the specification of the NineML User Layer. They are based on initial discussions between Robert Cannon, Padraig Gleeson and Hans Ekkehard Plesser at CNS09 in Berlin, and further developed by Robert and Padraig after the meeting.

A basic Java API has also been developed which can generate XML examples in this format.

Elements in network descriptions

The proposed network elements here follow the conventions being used in the development of NeuroML version 2.0 (e.g. using the attribute id for identifying each element and the element name for referencing; using camelCaseNaming for elements and attributes) which in turn are based on SBML conventions. The NineML examples are based on the latest proposed NineML User Layer document.

<population>

A population consists of a homogeneous collection of cells or sub-networks etc. It is always contained within a network. This element indicates that a single unit should be instantiated one or more times. A population contains:

An id attribute that is unique within this network.
An attribute to reference to the unit to be repeated which is either a cell definition, or a network. The cell could potentially be defined in NeuroML version 2.0 in the same file, or be linked to an external definition (e.g. in the NineML Abstraction Layer, or an abstract cell model in SBML). If the unit is a network, this would normally be defined in the same file. Note that all cell positions, connections, etc. defined in the network are repeated for each unit instance of the population. If the network unit contains stochastic elements (e.g. randomly placed cells, random connections) it is assumed that a different instance of the network is generated for each population unit.
A layout subelement which specifies how the population should be laid out on some space.

<space>

This refers to the medium/space in which elements can be placed. Examples include 1D to 3D grids, and 1D to 3D Euclidean space. For now, the following spaces are assumed to be predefined: Euclidean_1D, Euclidean_2D, Euclidean_3D, Grid_1D, Grid_2D, Grid_3D. The space element could potentially include some extra information giving structure to the space, e.g. how the grid is laid out in 3D.

Other examples of spaces which may need to be added in future include 2D manifolds in 3D space.

<region>

A subset of a space into which to place cells, e.g. rectangular box defining a region in 3D space.

<layout>

How population elements should be laid out on (a region of) its space. Examples include: a grid based layout (which specifies the size of the grid in x, y, z dimensions); random layout of a number of cells in a 3D region.

<network>

A network is a unit which contains a number of cells in populations, sub- and supersets of those cells and synaptic connections between the cells. A network element contains:

A unique attribute id.
A set of space definitions relevant for the populations in that network.
A set of regions associated with the spaces.
A number of population elements to create the cells of the network (or to create instances of subnetworks of cells & connections).
A number of cellSet elements to define convenient sets of cells (within or across populations) for making connections, applying inputs, recording variables, etc.
A number of connection elements, for the synaptic connections between populations or cellSets.
A number of input elements for applying electrical or synaptic stimulation to the populations or cellSets.

<cellSet>

A convenient way to build sets of cells from existing populations (this element does not create any new cells!) which can be used, e.g. as the source or target of connections, a target for inputs, etc. It is envisioned that a type of XPath can be used to select across populations (e.g. select="NetworkA/PopulationB[0-10] | NetworkA/PopulationC[*]) but this needs further work.

The name cellSet is used as opposed to set since <cellSet id="mySet" select="NetworkA"> should refer to all cells as opposed to all cells & connections, etc.

Examples shown below and the Java API do not include this element yet.

<connection>

A set of synaptic connections between a source population or cellSet and a target population or cellSet.

Examples shown below and the Java API do not include this element yet.

<input>

Used for applying electrical or synaptic stimulation to a specified population or cellSet.

Examples shown below and the Java API do not include this element yet.

Relation to NineML

The scope of the elements described is close to that of the NineML User Layer. This language allows definitions of groups of components (which could themselves be groups or cells/spiking nodes defined in the NineML Abstraction Layer) which can be linked by connections. This generic structure should allow a wider range of models beyond neural networks to be defined in the language, NeuroML v2.0 will focus on neuron models connected by synapses, and so the structure reflects those entities. There will hopefully be a direct mapping from network elements in NeuroML v2.0 to the corresponding elements in NineML, as illustrated in the example files below.

Java API for generating networks in NeuroML v2.0/NineML

A basic API in Java for generating NeuroML v2.0 network files (and NineML User Layer files) based on the above elements is available from the NeuroML SourceForge Subversion repository. To check this out use:

svn co https://neuroml.svn.sourceforge.net/svnroot/neuroml/DemoVer2.0/NMLVer2_Test .

Some "handmade" NeuroML v2.0 network description files are available in the web/NeuroMLFiles directory. Included there are some other NeuroML version 2 example files for cells, ion channels etc. See here for more details.

The main Java classes for creating networks are in the src/java/org/neuroml/network/ folder.

Once checked out, these files can be compiled using ./make.sh (Linux/Mac) or make.bat (Win).

To execute a basic demo which generates a number of NeuroML v2.0/NetworkML v1.0 and NineML files, type: ./run.sh -test (Linux/Mac) or run.bat -test (Win). This demo also checks the validity of these generated files as well as the "handmade" example files against the NetworkML v1.x Schema, a prototype NeuroML v2.0 Schema and a very simple NineML v0.1 Schema.

Example of hierarchical network in NeuroML version 2.0

This is one of the examples of the files in NeuroML v2.0 format generated by the Java API. It can be downloaded here.

<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 http://sourceforge.net/apps/trac/neuroml/export/809/NeuroML2/Schemas/NeuroML2/NeuroML_v2alpha.xsd" id="HyperColumnNet">

    
    <network id="OneColumnNet">

        <space id="3D_Grid_1" basedOn="Grid_3D">
            <structure xSpacing="40.0" ySpacing="40.0" zSpacing="40.0" xStart="0.0" yStart="0.0" zStart="0.0"/>
        </space>

        <space id="3D_Grid_2" basedOn="Grid_3D">
            <structure xSpacing="20.0" ySpacing="20.0" zSpacing="20.0" xStart="10.0" yStart="10.0" zStart="10.0"/>
        </space>

        <space id="Euclidean_3D"/> 

        <region id="BoxA">
            <extent xStart="0.0" yStart="300.0" zStart="0.0" xLength="80.0" yLength="120.0" zLength="80.0"/>
        </region>

        <population id="ExcCells" cell="ExcCell">

            <layout space="3D_Grid_1">
                <grid xSize="3" ySize="5" zSize="3"/>
            </layout>

        </population>

        <population id="InhCells" cell="InhCell">

            <layout space="3D_Grid_2">
                <grid xSize="4" ySize="6" zSize="4"/>
            </layout>

        </population>

        <population id="RandCells" cell="RandCell">

            <layout space="Euclidean_3D">
                <random number="40" region="BoxA" />
            </layout>

        </population>

    </network>

    <network id="HyperColumnNet">

        <space id="3D_Grid_3" basedOn="Grid_3D">
            <structure xSpacing="200.0" ySpacing="500.0" zSpacing="200.0" xStart="0.0" yStart="0.0" zStart="0.0"/>
        </space>

        <population id="HyperColumns"  network="OneColumnNet">

            <layout space="3D_Grid_3">
                <grid xSize="3" ySize="1" zSize="3"/>
            </layout>

        </population>

    </network>

</neuroml>

Example of hierarchical network in NineML

This is one of the examples of the files in NineML format generated by the Java API. It can be downloaded here.

<nineml xmlns="http://nineml.org/9ML/0.1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://nineml.org/9ML/0.1 ../NineML/NineML_v0.1.xsd" name="HyperColumnNet">

    
    <group name="OneColumnNet">

        <population name="ExcCells" >
            <prototype><reference>ExcCell</reference></prototype>
            <structure>3D_Grid_1</structure>
            <layout>gridLayout</layout>
            <xSize>3</xSize>
            <xSpacing>40.0</xSpacing>
            <xStart>0.0</xStart>
            <ySize>5</ySize>
            <ySpacing>40.0</ySpacing>
            <yStart>0.0</yStart>
            <zSize>3</zSize>
            <zSpacing>40.0</zSpacing>
            <zStart>0.0</zStart>
        </population>

        <population name="InhCells" >
            <prototype><reference>InhCell</reference></prototype>
            <structure>3D_Grid_2</structure>
            <layout>gridLayout</layout>
            <xSize>4</xSize>
            <xSpacing>20.0</xSpacing>
            <xStart>10.0</xStart>
            <ySize>6</ySize>
            <ySpacing>20.0</ySpacing>
            <yStart>10.0</yStart>
            <zSize>4</zSize>
            <zSpacing>20.0</zSpacing>
            <zStart>10.0</zStart>
        </population>

        <population name="RandCells" >
            <prototype><reference>RandCell</reference></prototype>
            <structure>Euclidean_3D</structure>
            <layout>randomLayout</layout>
            <number>40</number>
            <xSize>80.0</xSize>
            <xStart>0.0</xStart>
            <ySize>120.0</ySize>
            <yStart>300.0</yStart>
            <zSize>80.0</zSize>
            <zStart>0.0</zStart>
        </population>

    </group>

    <group name="HyperColumnNet">

        <population name="HyperColumns" >
            <prototype><reference>OneColumnNet</reference></prototype>
            <structure>3D_Grid_3</structure>
            <layout>gridLayout</layout>
            <xSize>3</xSize>
            <xSpacing>200.0</xSpacing>
            <xStart>0.0</xStart>
            <ySize>1</ySize>
            <ySpacing>500.0</ySpacing>
            <yStart>0.0</yStart>
            <zSize>3</zSize>
            <zSpacing>200.0</zSpacing>
            <zStart>0.0</zStart>
        </population>

    </group>

</nineml>

Generating the network

Once a network description is generated with this API, the instances of the network can be generate by calling generate(seed) on the Network class. Using a different seed will produce a different network for stochastic layouts (e.g. randomly placed in a 3D region).

The generated network can be saved in a provisional NeuroML v2.0 instance based network file or as a valid NeuroML v1.x instance based file.

The generated NetworkML v1.x representation of the network can be visualised in compatible applications, e.g. neuroConstruct as in the figure above, or the X3D visualisation tool on the NeuroML website. A screenshot of the generated X3D file viewed in the OctagaPlayer is shown below: