Overview
Here we present an Open Source tool for the creation of SNN and RCN models in the SpineML format based on a Graphical User Interface (GUI), called SpineCreator (SPIking NEuron/NEtwork CREATOR). The tool is written in C++ using the Qt cross platform libraries and development tools. Qt was chosen to allow the creation of an application for cross-platform deployment (Windows, OSX and Linux). SpineCreator is designed to fit into the SpineML toolchain as shown in Fig. 2↓. The source code is available online at https://github.com/SpineML/SpineCreator.
Outline of the SpineCreator Interface
The SpineCreator GUI provides an interface with a one-to-one mapping between XML tags and the GUI interface elements. The stages of the modelling process are also analogous to the levels of description used to investigate architectures in the brain, from individual neurons to complete sensori-motor systems, followed by an external experimental paradigm. The GUI elements are implemented to allow a user to apply their existing knowledge of software UI design features such as undo/redo, recently opened file lists, drag and drop and property editing.
SpineCreator uses the ‘interface metaphor’ (a user interface function that utilises specific knowledge that users have from other domains) of a Project to contain a SpineML model (a single SpineML Network which references a set of SpineML Components) and a complete SpineML Experiment (or set of Experiments). Multiple Projects can be open simultaneously in SpineCreator. The elements of a Project are stored in a single working directory as individual SpineML XML files, along with an XML Project Description File that contains a list of the Project files. In addition SpineCreator stores additional information it needs to visualise the model or describe complex connectivity in XML Annotations tags within the SpineML. This allows the model to be easily edited using other software, while the XML structure of the Project and Annotations allows these elements to be easily utilised by other editing software. To facilitate this the XML format used in Project files and Annotations is described on the SpineCreator website at http://spineml.github.io/spinecreator/ (Fig. 3).
SpineCreator’s functionality consists of five main functions, each of which occupies a separate tab in the left hand bar of the main program window (see Fig. 2↑). The tabs comprise:
-
Component Creation. SpineML Components representing neuron body dynamics, weight update rules, synaptic dynamics, or general dynamical processes, which can be created or imported, and modified using a graphical interface.
-
Network Creation. SpineML Network files can be imported and combined, or created. SpineML Components in the same project can be used in the network.
-
Experiment Creation. SpineML Experiments for each project can be created and modified.
-
Graphing. Plots Analog or Event data logged from experiment runs. The plots update automatically when new experiments are run. Line and raster plots of logged data can be visualised and saved as Portable Document Format (.pdf) or Portable Network Graphics (.png) files.
-
3D visualisation. The 3D layout of the network can be constructed and visualised. The neurons in Populations can be assigned locations in 3D space using procedural layout descriptions which can be created in SpineCreator. Connectivity patterns can be visualised, and the extended connection types that SpineCreator supports can be configured (see “Extended connectivity types↓” section). This visualisation can be output as a Portable Networks Graphic (png) or Scalable Vector Graphics (svg) image file.
We shall now demonstrate the workflow of SpineCreator for creating an SNN model using an example.
Component Creation
The Component Creation tab of SpineCreator is used to author SpineML Components. The interface is shown in Fig. 4↓.
The Component list provides an overview of the Components in the current Project, and is colour coded to provide immediate visual feedback to show which Components are valid (i.e. have complete definitions), invalid, and are in use in the Network, allowing the user to quickly detect errors in Components. Component dynamics are displayed graphically, as shown in Fig. 4↓, where they describe the Striatum model’s FSI neuron behaviour (replicated from Humphries et al. (2009b)). Importantly, Components can be modified, renamed and duplicated here even if they are in use. In the Striatum Model, all neuron types are extended versions of a form of the Izhikevich neuron model (Izhikevich 2007). This means that the process of creating the individual neuron types can be simplified by first creating or importing a SpineML Component for this neuron type, and then duplicating and modifying this component to form the three neuron types in the Striatal Model. By reusing an existing Izhikevich Component, the time taken to create the Components is significantly reduced, as is the likelihood of errors. Finished Components can be exported as separate SpineML files, for use in other Networks and Projects. To prevent mistakes such as deleting an element of a Component being costly in terms of development time there are separate undo stacks provided for each Component.
It should be noted that dimensionality units can be added to Parameters, State Variables and ports, and is used in the Network Creation section of the software to reduce errors by only allowing ports with matching types (event/analog/impulse) and dimensions (mV/pA etc…) to be connected.
After creation, the Components can be used to build networks in the Network Creation section of SpineCreator to build the model.
Network Creation
Components created in the Component Creation section of SpineCreator, or imported from the file menu, are added to the Components available within the Project. These components can then be used in the Network Creation section of SpineCreator to construct SNN models.
Figure 2↑ (C) shows the Network Creation section of SpineCreator with the Striatal model. The left hand section of the interface shows a large 2D view of the model, topped by a toolbar allowing the addition of new objects to the network or the removal of existing objects. The right hand section of the interface shows a context sensitive panel for detailed configuration of the Network. An undo stack is also provided for the Network, allowing mistakes such as unintentional deleting of objects to be rectified easily.
Not all information about the model is presented to the user at the same time, in order to provide an uncluttered interface where useful information is not obscured by irrelevant information. The organisation of the information presented is as follows.
2D Interface
This high level structural overview of the model is always present, which includes the Populations comprising the model, the Projections between them, and the Generic Inputs connecting components. These are presented in a 2D graphic which the user can arrange to form a flow diagram, as shown in Fig. 2↑. The user can therefore arrange the 2D layout using drag and drop to match the conceptual diagrams of the model; in Fig. 1↑ the correspondence between the conceptual diagram for the GPR model and the 2D Network Creation visualisation of the model can be seen. By presenting the model structure in 2D, the objects that make up the model can be arranged to clearly show their relationships to other objects, avoiding the possibility of objects obscuring each other as can occur in a 3D projected view. In addition the Populations have further information presented in this view: the Population name, the number of neurons in the Population, and the component type used by the Population. Populations can be assigned a display colour to facilitate visual identification and grouping. Projections also display extra information: thicker lines and a set of dots at the start of the projection indicate the number of Synapses in a Projection with more than one Synapse, and line colour is used to indicate the connection type used for Projections. Displaying this information ensures that the user always has an overview of the structure of the model, which can then be actively interrogated to retrieve or alter detailed information on single objects through the second level - selection.
Objects in the 2D graphic can be selected individually, or as a group (using the shift key to add to the selection, or the right mouse button to select objects inside a dragged box). Selecting a group of objects allows these objects to be moved together in the 2D graphic. Individual selection displays an interface with information about the selected object in the panel to the right of the 2D view. These diagrams can be exported for inclusion in manuscripts as either Portable Networks Graphic (png) or Scalable Vector Graphics (svg) image files.
Context Sensitive Properties Panel
The interface presented in this panel is different depending on the class of object selected, and allows the object to be configured. For example, selecting a Population object presents an interface where the name, size, colour and Component of the Population can be set. Once a Component is assigned for the Population, the input interface changes to present an interface for configuring the available Properties (StateVariables and Parameters) of the assigned Component (see Fig. 2↑). If several Populations need to share the same Properties (even if the Components differ) the copy and paste buttons can be used to copy and paste the Property configuration from one Population to another.
3D Visualisation
The 2D Network Creation interface provides an efficient and clear method of creating a model. However for some models, such as the Striatal Model described here, 3D information about neuron locations within a Population or connectivity between Populations is structurally important, and the 3D interface provides a more natural way to configure and observe connectivity.
3D Model Visualisation Interface
3D visualisation is provided in the Visualisation pane of SpineCreator. The interface consists of a 3D viewport to the left of the interface, topped by a toolbar with options to toggle the display of neuron indices and to toggle isometric projection of the model. To the right is a panel with a tree diagram of the network for selecting objects to configure and toggling which objects are visible. Below the tree diagram is a section with a configuration interface for the currently selected object. Figure 2↑ (B) shows the Visualisation interface.
The advantages of the 3D visualisation over lists is illustrated in Fig. 5↓ for an example set of connections between two populations of neurons: it is clear that the representation of connectivity for the Projection presented in A is clearer and more informative than that in B, in which only a few of several thousand connections are shown, and topographic mappings cannot be discerned. The highlighting in the 3D diagram demonstrates the context sensitive highlighting of connectivity in the 3D visualisation - connectivity can be highlighted by source neuron, destination neuron, or the individual connection. This more informative method of presentation reduces the chances of errors due to incorrect data entry or connection parameterisation through visual validation.
Another example, this time with interdigitated populations, is shown in Figs. 6 and 7↓. This example shows the connectivity between one FSI and its target MSN D1s. The visualisation allows the 3D structure of the connections to be seen.
3D Location Generation
To describe the 3D layout of neurons within a Population, SpineCreator provides a procedural method, which iterates through each neuron in turn and calculates the x, y and z co-ordinates using a set of user specified equations to advance values from their previous states. The process can be considered as an animation, with each subsequent frame representing the location of the subsequent indexed neuron in the population. In addition to x, y and z extra state variables can be added and updated each iteration. If a variable is used in an equation then the value from the previous iteration will be inserted (or zero for the first iteration), unless the value has been updated in the current iteration. Figure 6↓ shows a diagram of the procedural method for a grid with a row length of 3 μm. This layout was used in the BG SNN model to create six channels consisting of seven neurons each. New types of layout generation are specified using a graphical interface.
The equations used in a layout can also include uniform random numbers by using the rand() term. A seed can be specified in order to generate consistent random layouts, and a minimum distance can be specified to prevent neuron co-ordinates from being closer than is biologically realistic. A 3D layout, using random numbers to specify the x, y and z co-ordinates of each neuron, was used to generate the co-ordinates of the neurons in the Striatal Model. Using procedural layouts increases the speed of specifying co-ordinates in comparison with entering explicit co-ordinate lists, and the neuron co-ordinates can then be used with SpineCreator’s extended connectivity types, which will now be described.
Extended Connectivity Types
One advantage of a creation tool is that it can provide functionality that is not present in the underlying XML format. SpineML describes several connectivity types, however most forms of connectivity must be specified as an explicit list of [source index, destination index, delay] triplets (ensuring that any model can be supported with minimal simulator functionality). This requirement makes specifying connection types such as Gaussian receptive fields difficult, as explicit lists must be generated for the connections, with a corresponding list for the weights. To simplify this process, SpineCreator provides a means of extending the connectivity types of SpineML via Python scripts. These scripts are added to SpineCreator through the Settings/Preferences dialog, and once added appear in the list of connection types. Although the creation of an extended connectivity type requires knowledge of programming in Python, using and configuring one does not. To allow non-programmers to use and configure extended connectivity types a set of formatted comments is added to the top of the Python script: these specify parameters to pass to the script, and define how SpineCreator should provide a graphical interface for these parameters. An example script is shown below:
Adding parameters to the SpineCreator GUI is performed using the #PARNAME comment, which gives a name used as a label for the parameter, and a #LOC which describes the row and column where the parameter should be added in a grid for laying out the parameters. The order of the parameters in the code denotes the order they have in the corresponding Python function call, and allows the label to have a more descriptive name than the variable used in the function. In addition there are two more comments that are parsed; #HASWEIGHT and #HASDELAY, which inform SpineCreator if the script needs to generate a weight and/or a delay. If a weight is generated SpineCreator will provide a drop-down list of the corresponding Properties in the WeightUpdate Component, and the selected Property will have the weight values inserted when the connectivity is generated.
The function itself has arguments srclocs and dstlocs, which are Lists of Tuples, each Tuple containing the x, y, and z co-ordinates of the neuron at that index in the List.
Generating the explicit list of connections for larger Populations is slow, requiring a lot of computation to be performed, and therefore we minimise the amount of generation using the following strategies. Within SpineCreator the connectivity lists are not regenerated unless the script text, script parameters, or the source or destination sizes change. When writing the model out for simulation or storage, it is important that SpineCreator stores both the means of generating these extended connectivities, as well as the full ConnectionList in order that the XML version of the model is always a valid and accurate SpineML model. To achieve this, only if the connectivity has not already been generated by SpineCreator is it generated, and the full connectivity is saved in the SpineML model as a ConnectionList, and the Python script and parameter values are saved separately in the ConnectionList Annotations tag. This method has two main advantages. Firstly it guarantees an accurate SpineML model is always saved, and can therefore be loaded into other creation tools. Secondly, it speeds the process of loading a model into SpineCreator, as the connectivity does not need to be generated each time.
It should additionally be noted that Python scripting is defined in SpineCreator’s codebase as a ‘generator’ class, which acts via a ConnectionList class. This method of constructing the codebase allows that future standardised connectivity description formats can be added with minimal effort to the developers. Pragmatically, however, any future additional specification methods should still store the connectivity as a ConnectionList in the XML to maximise simulator support. Standardisation of certain Annotations within the ConnectionList tag could then provide a means of sharing the generation method between tools.
Experiment Creation, Simulation and Simulation Data Visualisation
Experiment Creation
In SpineML, Experiments are separated from the model description: a feature encouraged in other model formats (Gleeson et al. 2010; Cannon et al. 2014; Raikov et al. 2011). This separation can be conceptualised as the difference between an experimental animal (the model) and the experimental paradigm (electrodes used to record data, what stimuli to present, what neuropharmacological manipulations to apply) (Waltemath et al. 2011). A single animal can be involved in a range of experiments, and therefore it is important to have a separate layer to describe the experimental procedure. SpineML Experiments can be managed in the Experiment Creation section of SpineCreator, with the ability to add experiments and specify their names and text descriptions. An example of an Experiment for the GPR model is shown in Fig. 8↓. Here a time-varying signal is added to the first two channels of the model, and the responses of several nuclei are recorded, with only the activity of the first two neurons in the D1 Striatal Population recorded. The effect of randomised values for the D1 Striatum dopamine input are investigated using a Property Change to override the value in the model. By using Property Changes, collaborators can investigate the effect of different property values without changing the Network.
The interface is based on the interface metaphor of a workbook, with the panel to the left of the interface listing the Experiment entries. When these are selected the columns to the right fill with text descriptions of the manipulations for the Experiment. By using sentences with bold fonts to emphasise key data, information about the Experiment can be found at a glance.
Simulation
As SpineML is a simulator independent model storage format it aims to support a wide range of simulators. As support for simulators increases it is important that SpineCreator allows easy addition of simulators by the user. Access to simulators from the graphical interface is not essential, but is required to meet SpineCreator’s of making modelling more accessible. To this end simulators are supported through scripts (for example, BASH on UNIX and Batch file on Windows) that operate on a model stored in SpineML. These scripts can be configured using an extensible list of system environment variables. Thus the user can be given a simple set of instructions by a simulator author that allows them to add support for that simulator to SpineCreator. This script based system also allows the same scripts to be used by other SpineML model creation tools or from the command line with a hand written SpineML model.
The BRAHMS code generation target is provided as the Reference simulator, and supports all features of the SpineML language.. The results of simulation for the GPR model using BRAHMS via SpineML code generation can be seen in Fig. 9.
Other simulators are supported as described in the original SpineML paper (Richmond et al 2013), and ongoing development and support of simulator targets for SpineML is kept up to date on the SpineML website at http://spineml.github.io/simulators/, where installation instructions for the SpineML BRAHMS code generation target can be found.
Logging and Graphing
SpineCreator enables simulation data to be logged through the SpineML Experiment layer. These logs are then presented within the Graphing panel to the user, and can be plotted as line graphs for analog data and raster plots for event data. Graph drawing is undertaken using QCustomPlot (Eichhammer 2015). This facility is intended to provide immediate visualisation of the data for greater accessibility and for more rapid iteration of model development than is possible with external programs, as the process of loading logs and updating graphs between simulation runs is handled automatically by SpineCreator through communication with the simulator, while external programs are likely to require manual updating of graph plots. However, more complex analysis is possible using external programs, aided by an XML file written alongside the data file for each log that describes the source, type, and quantity of data logged. Figure 10 shows the interface while plotting the results of the experiment from “Experiment Creation, Simulation and Simulation Data Visualisation↑” section.
Features to Facilitate Collaboration and Dissemination
Version Control
In any collaborative or shared model creation software, versioning is important. We therefore have integrated the Mercurial version control system (VCS) ( http://mercurial.selenic.com/) into SpineCreator using a unified versioning structure that will support additional VCS in the future. The VCS is automatically detected on the user’s computer and these options for version control are only presented if Mercurial is present. Currently repositories for SpineCreator Projects must be created outside of SpineCreator, but subsequently the repository can be managed and queried from within the tool.
Publication Quality Diagram Output
Currently there is no standardisation of the diagrams used in publications to describe models. A review (Nordlie et al. 2009) tried to identify themes and good practice; see Figs. 10↑ and 11↓ for diagrams of Components and Networks output from SpineCreator. There is currently only one diagram export format for Components (shared with lib9ML (Raikov et al. 2011) and compatible with LEMS (Gleeson et al. 2010; Cannon et al. 2014)) and two for Networks based on the recommendations found in the review. The support of Scalable Vector Graphics output allows vector graphics images to be created, which can then be edited and annotated.