Create Matlab API/Toolbox for NeuroML

[pgleeson]

Matlab API/Toolbox for reading/editing/writing NeuroML2

Priorities will be:

• Ease of (re)generation from latest Schema
• Ease of installation
• Lack of external dependencies
• Examples (based on https://github.com/NeuralEnsemble/libNeuroML/tree/master/neuroml/examples)

An initial version of this be worked on by @jonc125 under https://github.com/NeuroML/NeuroMLToolbox

Is there an existing XSD -> Matlab code generation option?

The best option may be to use JAXB and access the Java classes from Matlab

[jonc125]

Following documentation at http://uk.mathworks.com/help/matlab/matlab_external/static-path.html I've created a javaclasspath.txt file in my prefdir containing /full/path/to/jNeuroMLJar/jNeuroML-0.7.7-jar-with-dependencies.jar.

Following http://uk.mathworks.com/help/matlab/matlab_external/accessing-your-own-java-classes.html I can do some very simple test calls:

• org.neuroml.JNeuroML.JNML_VERSION -> 0.7.7
• org.neuroml.JNeuroML.main() -> No matching signature; need to figure out how to create a java string array in Matlab to try this!

[jonc125]

Running

validator = org.neuroml.model.util.NeuroML2Validator();
file = java.io.File('/Users/jonc/projects/OpenSourceBrain/NeuroML_API/test/samples/Purk2M9s.nml');
validator.validateWithTests(file);
disp(validator.getValidity());

yields Valid against schema and all tests

Similarly

file = java.io.File('/Users/jonc/projects/OpenSourceBrain/neuroml2_matlab/dev/jLEMS/src/test/resources/hhmodels.xml');
org.neuroml.export.utils.Utils.runLemsFile(file, false);

gives

Mar 20, 2017 3:23:06 PM org.lemsml.jlems.core.logging.MinimalMessageHandler msg
INFO:  (INFO) Loading LEMS file from: /Users/jonc/projects/OpenSourceBrain/neuroml2_matlab/dev/jLEMS/src/test/resources/example1.xml at: org.lemsml.jlems.viz.datadisplay.ControlPanel.initialise(ControlPanel.java:135)
Mar 20, 2017 3:23:06 PM org.lemsml.jlems.core.logging.MinimalMessageHandler msg
INFO:  (INFO) Reading from: /Users/jonc/projects/OpenSourceBrain/neuroml2_matlab/dev/jLEMS/src/test/resources/example1.xml at: org.neuroml.export.utils.Utils.readLemsNeuroMLFile(Utils.java:238)
Mar 20, 2017 3:23:06 PM org.lemsml.jlems.core.logging.MinimalMessageHandler msg
WARNING:  (WARNING) Unused attribute in Component(id=p1-p3 type=EventConnectivity): XMLAttribute(source, p1)  at: org.lemsml.jlems.core.type.Component.resolve(Component.java:538)
Mar 20, 2017 3:23:06 PM org.lemsml.jlems.core.logging.MinimalMessageHandler msg
WARNING:  (WARNING) Unused attribute in Component(id=p1-p3 type=EventConnectivity): XMLAttribute(target, p3)  at: 
Mar 20, 2017 3:23:07 PM org.lemsml.jlems.core.logging.MinimalMessageHandler msg
INFO:  (INFO) Finished 8000 steps in 0.862 seconds (sim duration: 80.0ms; dt: 0.01ms) at: org.lemsml.jlems.core.sim.Sim.run(Sim.java:332)
Mar 20, 2017 3:23:07 PM org.lemsml.jlems.core.logging.MinimalMessageHandler msg
INFO:  (INFO) Finished reading, building, running and displaying LEMS model at: org.neuroml.export.utils.Utils.loadLemsFile(Utils.java:393)

So it does look like this approach will let us do everything that the Java API can do.

[jonc125]

Things to look into further:

• Using imports to avoid having to type full package names all the time.
• Make it easy to run LEMS, perform a simulation, load the results into Matlab, and plot. Similarly to what can be done with the Python API.
• Generating a NeuroML/LEMS file from scratch, c.f build_3D_network.py. This is likely to be messier than the Python version as JAXB (deliberately) only creates default constructors, so you have to do lots of set calls.

Places to look at for inspiration:

• run_lems_with_jneuroml in pynml.py
• https://github.com/NeuroML/pyNeuroML/blob/master/examples/run_jneuroml_plot_matplotlib.py
• https://github.com/NeuroML/pyNeuroML/blob/master/examples/create_new_lems_file.py

[jonc125]

I've made a start on documentation and a few examples. Some issues making this hard:

• The java.io.File class, when accessed from Matlab, doesn't resolve relative paths relative to cwd but to ~/Documents/MATLAB. So jNeuroML keeps trying to write results under there.
• Any jNeuroML errors seem to call System.exit() which quits Matlab! Is there a way to tell it not to do this? It's hard to see what the error messages are when Matlab quits immediately. Using the diary command helped somewhat, although the latest error doesn't seem to be captured by diary.
• The reload_saved_data method in pynml.py resorts to XML parsing to figure out what the output files are, and what the columns represent. If we're working with the Java classes directly, can we get a list from somewhere? The Sim class doesn't seem to expose this information, alas. It might end up being easiest to write a new FileResultWriterFactory that tracks files written (and ensures relative paths are sane)...

Running without the GUI helps somewhat with this - the results folder is resolved relative to the current dir and Matlab doesn't quit when the simulation finishes / GUI exits. But there's still the issue of figuring out what the results were.

[jonc125]

Of course, another approach would be to access the Python API from Matlab, as we're doing for NWB...

This would mean a bit more conversion between Python & Matlab types than seems to happen with Java APIs, but if the Python API is nicer to work with, particularly for creating models, and is going to be better supported in the future, that may well be the better option.

[pgleeson]

I've tested this locally and some NML files validate correctly, others, incl ones in the examples folder here, don't with a strange error:

Apr 12, 2017 11:57:16 AM com.sun.xml.bind.v2.util.XmlFactory createTransformerFactory
SEVERE: null
javax.xml.transform.TransformerConfigurationException: Unsupported feature: http://javax.xml.XMLConstants/feature/secure-processing
	at com.icl.saxon.TransformerFactoryImpl.setFeature(TransformerFactoryImpl.java:373)
	at com.sun.xml.bind.v2.util.XmlFactory.createTransformerFactory(XmlFactory.java:176)

Will investigate further.

Also, the closing of Matlab on an error in jNeuroML is annoying, i'll purge the code of these exit(1) calls, and maybe set an option to close on exit.

There could certainly be a map returned with the filenames and names of variables when Utils.runLemsFile() is called. Will add this..