Specifying dimensions (as in LEMS?)
Closed this issue · 18 comments
Since parameter and state variable dimensions have been included into the NineML paper we should decide on a list of acceptable dimensions, and have a means of representing compound dimensions.
LEMS has a method for specifying compound dimensions, which is described in Robert and Padraig's recent paper (see Figure 1B) and also here [http://www.psics.org/lems/example1.html]. I am happy to adopt this approach as it seems a reasonable way to do it and it is nice to keep the two standards as close as possible.
@tclose the curated list of units/dimensions as used by LEMS is here: https://github.com/NeuroML/NeuroML2/blob/master/NeuroML2CoreTypes/NeuroMLCoreDimensions.xml (see also
http://www.neuroml.org/NeuroML2CoreTypes/NeuroMLCoreDimensions.html). A user can add their own new dimensions in a LEMS file, but this list should be sufficient for any conductance based neuronal model including concentration dependent channels using SI or physiological units. Happy to add any more you feel are needed.
You've stumbled across some ancient documentation there though. An updated version of that is here: http://lems.github.io/LEMS/example1.html. @robertcannon, can you remove those pages on psics.org?
@pgleeson thanks for the updated links! Have you thought about allowing anonymous inline combinations of existing units eg. dimension="length/time^2"?
Personally I don't see a need for this. Defining dimensions is something a modeller does once at the start of a project and usually doesn't have to look at again. Working out the correct dimensionality in terms of MLT etc. isn't too difficult.
The disadvantage of adding more complexity to the unit/dimension infrastructure is that application developers are more likely to not want to support it. The elements used here https://github.com/NeuroML/NeuroML2/blob/master/NeuroML2CoreTypes/NeuroMLCoreDimensions.xml are simple for anyone to understand and once they can handle that they have a solid basis for supporting units/dimensions in LEMS or any other language using these.
Fair enough, I suppose you would also be duplicating the ways you can define the same dimension.
How do you reference the dimensions and units xml file in the model file? Maybe it would make sense to have units as an sub-element rather than attribute in this scheme (although this does become quite verbose) in which case you could define them anonymously or reference the file they are defined in at the places where they are used if you wanted to.
I think there's a good case for including statements like 'dimension="length/time^2"' in the model file somewhere, but I don't think they should be used as the primary definition or you get non-canonical representations of fundamental things. In LEMS there is an Assert element which lets you add relationships between dimensions that are already defined. So once you've defined length, time and accelleration, you can assert that accelleration = length/time^2. This proves to be quite useful - it is surprising how often some of the assertions faile the first time you try setting up a file of dimensions!
@tclose: "How do you reference the dimensions and units xml file in the model file?"
The standard NML2 definitions can be added with an statement as here: https://github.com/NeuroML/NeuroML2/blob/master/LEMSexamples/LEMS_NML2_Ex1_HH.xml
Note Cells.xml includes in turn NeuroMLCoreDimensions.xml with units/dimensions. The models are usually structured so that NeuroML files only contain Component definitions (e.g. https://github.com/OpenSourceBrain/GranuleCell/blob/master/neuroConstruct/generatedNeuroML2/Gran_H_98.channel.nml) not any of the LEMS ComponentType/dimension definitions. This keeps them short, readable and only requires the modeller to use the predefined set of units in the definitions above in attributes (e.g. conductance="10pS").
The models will throw an error if incorrect string are used both when parsed by jLEMS (or PyLEMS) and when validated against the schema (e.g see https://github.com/NeuroML/NeuroML2/blob/master/Schemas/NeuroML2/NeuroML_v2beta3.xsd#L46)
Just a note - but the current specs say that dimensions if omitted take a value of 1 - should this not be 0?
Good point, I have fixed this on my branch.
@pgleeson What is the Dimension abbreviation attribute for luminous intensity, I wasn't able to spot it in any of the LEMS examples you linked to?
For defining a dimension & unit:
<Dimension name="luminousIntensity" j="1"/>
<Unit symbol="cd" dimension="luminousIntensity" power="0"/>
See https://github.com/LEMS/jLEMS/blob/master/src/main/java/org/lemsml/jlems/core/type/Dimension.java
or https://github.com/LEMS/pylems/blob/master/lems/model/fundamental.py#L56
@pgleeson thanks. One more question, how do you handle absolute vs relative temperature values, so that you can appropriately offset the conversion from degrees Celsius to Kelvins (if absolute but not if relative)?
It allows attributes offset and scale, e.g. here
<Unit symbol="degC" dimension="temperature" offset="273.15"/>
<Unit symbol="min" dimension="time" power="0" scale="60"/>
Fahrenheit could be implemented using both.
In the google hangout last Friday it was decided to adopt the LEMS format for units & dimensions for version 1.0 but to consider switching to the NASA-sponsored QUDT (http://qudt.org/) ontology in future versions (@pgleeson, have you looked into this?).
PR #55 addresses implements this for the python library. Note that the dimensions and units must be copied into the file where they are used at this point.
@tclose Thanks for the tip about QUDT. Can't see the advantage of moving to the more verbose format though, almost all the features there seem to be in the LEMS format, with the added advantage that it's easy to read and write (without reading the docs...).
I wouldn't underestimate this advantage; it can always be mapped to/annotated with the corresponding QUDT elements...
Yes, LEMS is mainly intended to be written by hand and read by model developers, just like a programming language. As such, we shouldn't include any formats that are intended mainly for machine-machine communication (this is also why it doesn't use MathML).
However QUDT it could definitely be a useful output target for communicating to a system that does not want to read LEMS, and I can see it being quite useful in NineML which is much more machine-machine focused.
Thanks for the comments Padraig, Robert (sorry I meant to write back to your last comment as well). It does seem conceptually quite similar to the LEMS units format but perhaps a little more verbose. We will probably have to discuss whether there will be any benefit of adopting a wider standard or not.
@robertcannon Yes, I wouldn't want to write MathML by hand that is for sure. At the moment we only use inline math as well but the longstanding plan is to move to MathML at some point in the future. At the last meeting we discussed the idea of supported "extensions" (I still think there might be a better name but can't think of it), which are free to adopt their own syntax as long as there is a standard tool (in my mind ideally XSLT if possible but not required) that converts them into "core 9ml" (i.e. easily machine readable) and back again, storing any required information in annotations (potentially just the original code) to allow the reverse conversion. So I expect inline math will fall into this category in the end.
Along this line of thought, I had been thinking that when we settle everything down at our end it could be good to work out some such conversion scripts LEMS/NeuroML2 -> 9ml and back again. In this case, from the 9ml perspective NeuroML/LEMS would become supported "extension" for people wanting to write xml by hand, and from the LEMS/NeuroML perspective the 9ML tool chains we have been working on would become supported back-ends. I realise defining extensions in this way is very loose when it is essentially just a couple of conversion scripts but it might be a nice way to pitch it to the community at large and tie the development of the two projects together. Anyway, just a thought.
Sure. As mentioned there is already a NML2/LEMS converter to NineML (and SpineML) here and some examples of this have been put here: https://github.com/OpenSourceBrain/NineMLShowcase/tree/master/NineML.
This can be updated to use the latest formats when the new release of 9ml is stable.
Re NineML to LEMS, this is probably best done using the python APIs for both packages. There is a very old version of this here using an earlier lems python api: http://sourceforge.net/p/neuroml/code/HEAD/tree/NeuroML2/python/libneuroml/lems/util.py#l212