Extending NeuroML
One of the most frequently asked questions we get is: How can I extend NeuroML to support my model?
The following information is intended to clarify the various options which are available at present and outline the procedures for incorporating native support for new model features into NeuroML.
Clarifying the question
NeuroML is intended to be an open and evolving language which will increase in scope with time. It is however a model description language which is built on a number of key concepts commonly used in biophysically detailed computational neuroscience modelling (neuronal morphologies, ion channels, synaptic connections) and provides a way to represent these entities in a structured language which can be used by applications which also deal with these physiological entities.
This has the advantage of providing an efficient way to represent the key elements of models which can be exchanged between applications and researchers (e.g. without needing the Hodgkin Huxley model to be redefined in full for every channel). This approach is different to that of languages like SBML and CellML where more generic dynamical (biological) model systems can be described in terms of interacting entities and rates of change of variables. While a multicompartment cell with multiple ion channels can be expressed in one of these languages, it would be difficult to extract the key neuroscience elements out of them in a standardised way, or to simulate the models as efficiently as a dedicated compartmental modelling simulator could.
While the approach of SBML and CellML has some clear advantages, in particular the flexibility afforded for developing custom models, the benefits of the current approach with NeuroML (ease of portability and efficiency of simulations) have driven the developments in the initiative to date. It does mean however that if a concept is not present in NeuroML (e.g. a firing rate model of a neuron; a voltage dependent gap junction) it is more difficult to express that type of model in "pure" NeuroML
The list below gives a number of options for those who wish to use NeuroML but find that some features of their models are not currently natively supported in the language.
- Annotate NeuroML files with model/application specific data
- Create models with a subset of components in NeuroML
- Create a domain specific schema
- Propose extensions to current version of NeuroML
- Propose major changes for NeuroML v2.0
If there are additional scenarios which also need to be included/discussed please get in touch via the mailing lists.
Annotate files with model/application specific data
There are multiple ways to add metadata to a NeuroML file. While much of the metadata that can be added is in the form of text strings to explain the contents to humans, it is also possible to add more structured data which can give the model developer's own tools (or a subset of similar tools) extra information about how to visualise/simulate the model.
This has the advantage that the files remain "pure" NeuroML, and another application can simply ignore the metadata and only use the core NeuroML infomation contained in the file. This is the case with a number of SBML compliant applications, e.g. CellDesigner which uses annotation blocks in the SBML file to add application specific data on its graphical layout of species, compartments, etc.
If a number of applications start using structured metadata for the same types of data, the core language could be updated to support those concepts (or a new separate language created, as in the case of SBGN).
An example of using metadata in a NeuroML file is the annotation of Level 3 NeuroML files exported by neuroConstruct. Information is included in a <meta:annotation> tag which will contains all of the information needed to create a new neuroConstruct project from the NeuroML file, includign non core NeuroML information such as the colours of cell populations, simulation configurations etc. This information can be ignored by other applications which just use the cell and network information.
The metadata group of elements in the Metadata schema provides a useful set of base elements for this type of extra data. The following presents examples of some options for adding custom metadata to a NeuroML file:
The example below shows how to embed a custom model into an existing element in NeuroML. This allows a modeller to encode a new model in valid NeuroML. Note that if a simulator which doesn't support the extension it will produce different results. If multiple users require the same types of custom extensions they can be incorporated into the core language.
<synapse_type name="VoltDepGapJunc" xmlns="http://morphml.org/channelml/schema"> |
The full NeuroML file can be viewed here.
Create models with a subset of components in NeuroML
While there are a number of model types which are currently supported in NeuroML, and while a number of cell and network models can be fully expressed in NeuroML (see here) some components of a cell model might not be supported in the current version of the language (e.g. a custom channel type created with NMODL for NEURON).
If these types of models are sufficiently widely used they can be incorporated into the language (see below), but it can take some time for the updates to be made.
NeuroML is intended to be just one of many tools used in the computational modelling pipeline of data acquisition/model creation/simulation/analysis/publication/reuse. It won't be the case that full specification in NeuroML will be possible (or desirable) for every model, and the choice of model specification language will be a trade off between the amount of flexibility required and how much the various model elements fit into NeuroML's data model of common neurophysiolgical entities (or another standardised representation):
Some of the options for model specification which mix NeuroML and native scripts include:
- The native NeuroML import function (e.g. NEURON, PSICS) of the application can be used for the NeuroML based model components and the "traditional" script format for the rest of the model. The example file presented in the previous section shows how a channel in a native simulator script (Na_Channel_NMODL) could be referenced in a valid Level 2 cell description.
- A number of channels can be expressed in ChannelML and (Python) scripts used to convert these to native simulator format (e.g. see "Conversion of ChannelML at the command line") before including them as normal in a native simulation script
- Cell models developed in neuroConstruct can transparently mix ChannelML and native File based Cell Mechanisms
These options have the advantage that the components of the model which are in NeuroML can be readily reused by other researchers.
Create a domain specific schema
This method is appropriate if you have a new class of data structures for which you need a defined specification, but want to reuse a number of NeuroML elements. An example would be if you want to define models which have neuronal elements but also concepts outside of the current scope of NeuroML, e.g. the 3D shape of blood vessels and blood flow; detailed electrical probes with 3D extent; interaction of neuropil with external electrical fields.
This can be accomplished by defining a new schema and including the existing NeuroML schemas as appropriate.
In the example below "VasculatureML" is defined. This new dummy language is intended to incorporate models of both neurons and vasculature.
Schema of the new language:
<?xml version="1.0" encoding="UTF-8"?> |
Example of typical "VasculatureML" file:
This approach has the advantage that communities focusing on a specific domain can define and update their schemas independent of the NeuroML initiative and reuse only the elements of this language that are appropriate.
It also means that the neuronal elements of this new language can be easily extracted and used in a NeuroML only application.
If there are any communities taking this approach (or planning to) we'd love to hear about it.
Propose extensions to current version of NeuroML
While work is already started defining the scope of NeuroML version 2.0, it it still possible that some minor extensions could be incorporated into the existing version v1.x schemas. General requirements for making additions to the language this at this stage would include:
- The model element can be expressed relatively easily in one (ideally two or more) simulators which already support NeuroML
- Executable examples of the model elements are available
- Published models exist using the model element in the simulator(s)
- The extension would not require restructuring to any of the existing elements (i.e. making present NeuroML files invalid)
Most of these types of extensions would involve minor alterations to existing elements for subcases which weren't built in initially, e.g. allowing the q10 factor to be expressed independently per gate.
Other adjustments which are currently planned include allowing a table of experimental data to be used for gating variables (see here, planned for v1.8.2).
Anyone who identifies such an extension should get in contact via the neuroml-technology mailing list. While it has mainly been members of the NeuroML Team who have been active in implementing changes, proposers of new features are encouraged to supply example simulator code and even suggest a new form of the appropriate NeuroML schema incorporating the change.
Propose major changes for NeuroML v2.0
New types of model which require major changes to the language (or restructuring of the existing elements) will have to wait for NeuroML version 2.0.
The scope of version 2.0 will encompass all models currently supported in the language and allow new and more complex models to be produced with greater detail on subcellular signalling pathways and more complex network creation algorithms. The changes which are planned to date were discussed at the second NeuroML Development Workshop. The minutes for that meeting and information on future plans will be posted on the page for the roadmap to NeuroML version 2.0.
Once concrete proposals for the new form of NeuroML are created, we will be seeking feedback from the wider computational neuroscience community on the proposed extensions, so join the mailing list!