search

Kappa-Dev / KappaTools

Tool suite for kappa models. Documentation and binaries can be found in the release section. Try it online at
http://kappalanguage.org/
GNU Lesser General Public License v3.0
113 stars 41 forks source link

Output ODEs for Kappa model in SBML format #316

Closed yarden closed 7 years ago

yarden commented 7 years ago

Hello,

It would be great if there was an option to export ODEs corresponding to a Kappa model (via kade?) in SBML format, an XML-based format that can be read by both free (e.g., CellDesigner) and commercial packages (e.g., MATLAB). The text-based format is nice for checking in models into version control repositories and for sharing models with other people.

Thanks, Yarden

feret commented 7 years ago

Dear Yarden,

Thank you for your feedback. You are right.
Internally, we have the reaction networks and the set of species.

I am not familiar with SBML. One issue is that there seems to be several SBML format, and also several conventions (even for CellDesigner indeed). Could you provide us an example of SBML output? Also I would need to know if there is, which characters are forbidden in which fields ?

Thank you. Jérôme.

yarden commented 7 years ago

Hi Jérôme,

Thanks very much for your response. You're absolutely right that different programs produce SBML files using different conventions. However, I believe that there's a "core" specification of ODEs and rate constants in SBML that can be parsed to retrieve the kinetic model while ignoring the rest. As an example, in our recent paper we use an ODE model that was drawn up in CellDesigner and serialized as this SBML file. CellDesigner puts in a lot of information about the visualization of the model into the SBML file that can be safely ignored; the relevant bits are the ones describing the kinetic laws and rate constants. For instance, the information related to reactions can be used to automatically generate documents that describe the model using tools like SBML2LaTeX (which we used to generate this document from our SBML file).

To generate SBML files, I believe that you'd only need to use the very basic SBML tags that describe the ODEs, which would result in SBML files that are much less cluttered than the ones CellDesigner produces. This is the latest SBML specification (see Section 2).

Best, Yarden

feret commented 7 years ago

Dear Yarden,

This is very helpful. Thank you, I will try to get an SBML output shortly.

Best Jérôme.

feret commented 7 years ago

It should work now.

Could you test and give me your feedback about it ?

I have three know Issues:

yarden commented 7 years ago

Thank you for this wonderful Christmas gift, Jérôme. I'll test it out and get back to you.

feret commented 7 years ago

I wish you will like it. :-)

yarden commented 7 years ago

Apologies for delayed response, still somewhat recovering from bad flu. KaDE ran smoothly on my very simple model toy_model.ka:

$ KaDE -i ./toy_model.ka--ode-backend SBML
Parsing ./toy_model.ka...
done
+ Sanity checks
+ Compiling...
+ Building initial simulation conditions...
     -simulation parameters
     -variable declarations
     -rules
     -perturbations
     -observables
     -update_domain construction
     5 (sub)observables 0 navigation steps
     -initial conditions
+ generate the network... 
     -initial states 
     -saturating the set of molecular species 
     -tokens 
     -variables 
     -observables 
+ exporting the network... 
     -main function 
     -initial state 
     -ode system 
     -observables

It gives this SBML file. When I try to load it into CellDesigner (ver 4.4) to visualize and simulate the ODEs, it produces the following error:

line 105 [Error(SBML)] : The order of subelements within a <model> must be the following 
(where any one may be optional, but the ordering must be maintained): <listOfFunctionDefinitions>, <listOfUnitDefinitions>, <listOfCompartmentTypes>, 
<listOfSpeciesTypes>, <listOfCompartments>, <listOfSpecies>, <listOfParameters>, 
<listOfInitialAssignments>, <listOfRules>, <listOfConstraints>, <listOfReactions> and 
<listOfEvents>. (References: L2V2 Section 4.2; L2V3 Section 4.2; L2V4 Section 4.2)

line 54 [Error(General Consistency)] : The value of a <species>'s 'units' attribute is restricted. 
(References: L2V1 Section 4.6.4; L2V2 Section 4.8.5; L2V3 Section 4.8.5; L2V4 Section 4.8.5) 
The value of a <species>'s 'substanceUnits' attribute can only be one of the following: 
'substance', 'mole', 'item', 'gram', 'kilogram', 'dimensionless', or the identifier of a 
<unitDefinition> derived from 'mole' (with an 'exponent' of '1'), 'item' 
(with an 'exponent' of '1'), 'gram' (with an 'exponent' of '1'), 'kilogram' 
(with an 'exponent' of '1'), or 'dimensionless'.

My understanding is that CellDesigner tries to parse the SBML file with libSBML, which is the gold standard library for parsing these files, and the error is thrown by libSBML.

This is the visualization that CellDesigner produces from KaDE's SBML file:

celldesigner_toy_model_kappa_viz

I'm not sure I understand the reaction where the variable time is produced, which perhaps comes from this in the SBML file: 

<reaction id="re3" name="time advance" reversible="false" fast="false">                                                                                                                                        
<listOfProducts>                                                                                                                                                                                               
<speciesReference metaid="CMD24" species="time"/>                                                                                                                                                              
</listOfProducts>

Any thoughts on this? Perhaps my example is not the best Kappa model to use as test case, but I've tried to pick something trivial to make sure a standard SBML-parsing tool like CellDesigner can grok what KaDE is producing.

(Minor comment: it currently outputs a file network.xml, it'd be nice if the default was the name of the input file with .xml suffix, or if you could choose name of output file or just print it to stdout).

Thanks very much, Yarden

feret commented 7 years ago

No problem for the delay. I have no difficulty to fill my working time…

Indeed CellDesigner is much more faithful to SBML requirements than SBML2Latex…

line 105 [Error(SBML)] : The order of subelements within a must be the following (where any one may be optional, but the ordering must be maintained): , , , , , , , , , , and . (References: L2V2 Section 4.2; L2V3 Section 4.2; L2V4 Section 4.2) -> OK done, I put the before line 54 [Error(General Consistency)] : The value of a 's 'units' attribute is restricted. (References: L2V1 Section 4.6.4; L2V2 Section 4.8.5; L2V3 Section 4.8.5; L2V4 Section 4.8.5) The value of a 's 'substanceUnits' attribute can only be one of the following: 'substance', 'mole', 'item', 'gram', 'kilogram', 'dimensionless', or the identifier of a derived from 'mole' (with an 'exponent' of '1'), 'item' (with an 'exponent' of '1'), 'gram' (with an 'exponent' of '1'), 'kilogram' (with an 'exponent' of '1'), or 'dimensionless’. -> This one was not fun. If the model is not time-homogeneous, there is a need for a fictitious species to encode time advance. Its value is expressed in second (not mole).
To please SBML requirements, I now declare it as a substance, but when I use it I multiply it by a constant parameter which value is 1 and which dimension is time.mol^{-1} It is not very elegant, but I do not know how to do differently. I'm not sure I understand the reaction where the variable time is produced, which perhaps comes from this in the SBML file:

It was the reaction to model time advance.

It just encode d [t*] ------ = 1 dt

where t* is the fictitious specious encoding for time-advance.

For the sake of clarity, I now check beforehand whether the system is time-homogeneous or not. If if is, I introduce neither the fictitious species, nor the fictitious reaction. (I also avoid to introduce their dimension). I also neglect obs in the kappa files, most of the time, the model is not time-homogenous because we always plot time advance.

Otherwise, I introduce them.

I have checked, and now it seems to work well in CellDesigner.

Could you have a look and tell me if you encounter further issues ?

Thank you very much. Jérôme.

Le 8 janv. 2017 à 22:26, Yarden Katz notifications@github.com a écrit :

Apologies for delayed response, still somewhat recovering from bad flu. KaDE ran smoothly on my very simple model toy_model.ka https://gist.github.com/yarden/0545523d2bcd16cb2f45ad2165a0b69a:

$ KaDE -i ./toy_model.ka--ode-backend SBML Parsing ./toy_model.ka... done

  • Sanity checks
  • Compiling...
  • Building initial simulation conditions... -simulation parameters -variable declarations -rules -perturbations -observables -update_domain construction 5 (sub)observables 0 navigation steps -initial conditions
  • generate the network... -initial states -saturating the set of molecular species -tokens -variables -observables
  • exporting the network... -main function -initial state -ode system -observables It gives this SBML file https://gist.github.com/yarden/71e7ead02d275ae1b3b74373631c3818. When I try to load it into CellDesigner (ver 4.4) to visualize and simulate the ODEs, it produces the following error:

line 105 [Error(SBML)] : The order of subelements within a must be the following (where any one may be optional, but the ordering must be maintained): , , , , , , , , , , and . (References: L2V2 Section 4.2; L2V3 Section 4.2; L2V4 Section 4.2)

line 54 [Error(General Consistency)] : The value of a 's 'units' attribute is restricted. (References: L2V1 Section 4.6.4; L2V2 Section 4.8.5; L2V3 Section 4.8.5; L2V4 Section 4.8.5) The value of a 's 'substanceUnits' attribute can only be one of the following: 'substance', 'mole', 'item', 'gram', 'kilogram', 'dimensionless', or the identifier of a derived from 'mole' (with an 'exponent' of '1'), 'item' (with an 'exponent' of '1'), 'gram' (with an 'exponent' of '1'), 'kilogram' (with an 'exponent' of '1'), or 'dimensionless'. My understanding is that CellDesigner tries to parse the SBML file with libSBML, which is the gold standard library for parsing these files, and the error is thrown by libSBML.

This is the visualization that CellDesigner produces from KaDE's SBML file:

https://cloud.githubusercontent.com/assets/96318/21753604/8a13ed02-d5be-11e6-9f64-1d2880ffdb09.png I'm not sure I understand the reaction where the variable time is produced, which perhaps comes from this in the SBML file:

Any thoughts on this? Perhaps this is not the best Kappa model to test things with, but I've tried to pick something trivial just to make sure a standard SBML-parsing tool like CellDesigner can grok what KaDE is producing. (Minor comment: it currently outputs a file network.xml, it'd be nice if the default was the name of the input file with .xml suffix, or if you could choose name of output file or just print it to stdout). Thanks very much, Yarden — You are receiving this because you commented. Reply to this email directly, view it on GitHub , or mute the thread .
yarden commented 7 years ago

Hi Jérôme,

Thank you very much, and sorry for all the pain related to this. Also, thank you for clarifying the time-homogeneity aspect.

I checked it with CellDesigner and it parses with no errors, and CellDesigner parses the correct reactions! This is the diagram it makes (which is not intuitive, but that's inevitable in any conversion from a Kappa model to ODEs):

celldesigner_works

Thanks again; this will be a very useful feature.

Best, Yarden

feret commented 7 years ago

Great thank you. Would you have any comment or suggestion, please let me know.

Le 19 janv. 2017 à 20:09, Yarden Katz notifications@github.com a écrit :

Hi Jérôme,

Thank you very much, and sorry for all the pain related to this. Also, thank you for clarifying the time-homogeneity aspect.

I checked it with CellDesigner and it parses with no errors, and CellDesigner parses the correct reactions! This is the diagram it makes (which is not intuitive, but that's inevitable in any conversion from a Kappa model to ODEs):

https://cloud.githubusercontent.com/assets/96318/22121124/a705a348-de50-11e6-83af-911289bfeb6d.png Thanks again; this will be a very useful feature.

Best, Yarden

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/Kappa-Dev/KaSim/issues/316#issuecomment-273868570, or mute the thread https://github.com/notifications/unsubscribe-auth/AARts-g7R7mCOdI7pKntsMAfGOPitZiiks5rT7T1gaJpZM4LGmTL.