Download Links

Simulate 3D | SBW (Win32) | Bifurcation Discovery | FluxBalance

Thursday, September 6, 2012

Custom Annotation for using Distribution Functions in SBML Models

Drawing random numbers is a task occasionally encountered. However, there is no standard way to do that in SBML. Of course that is precisely what the SBML Level 3 package for Distributions and Ranges is for. But what to do in the meantime, or what to do when you want it working for SBML Level 2? This is precisely what I encountered a couple of weeks back, and that is why below you will find a specification for a very short custom annotation, that allows to tag an SBML function definition as distribution function. Here an example:

<functionDefinition id="normal" name="Normal distribution">
  <annotation>
    <distribution xmlns="
http://sbml.org/annotations/distribution" definition="http://en.wikipedia.org/wiki/Normal_distribution" />
  </annotation>
  <math xmlns="
http://www.w3.org/1998/Math/MathML">
    <lambda>
      <bvar>
        <ci> m </ci>
      </bvar>
      <bvar>
        <ci> s </ci>
      </bvar>
      <ci> m </ci>
    </lambda>
  </math>
</functionDefinition>

The annotation (in the namespace http://sbml.org/annotations/distribution) contains one attribute definition, whose value tells us precisely which distribution we would like to draw numbers from. All software that supports it will know that we are dealing with a distribution and know what to do with it. Other software at least get the mean whenever they invoke the function.

2012-09-06_-_Result

Here the full specification of the Custom Distribution Annotation. (and here the SBML model). The annotation is so far supported by JarnacLite and RoadRunner (Windows Installer). As the same functionality is available in other software packages it would be great if they could be tagged with the annotation as well.

8 comments:

Unknown said...

Hey Frank,

Are you stealing my thunder? ;-) My only comment would be to use UncertML for the link rather than Wikipedia. I think we will be using UncertML URLs for distrib as the definition is clearer. For example it's not clear from your definition if the second argument should be a stddev or variance.

Cheers,

Stuart.

Your name Nicolas Le Novere said...

Yes, I agree. The favoured method to support packages in L2 is to put their constructs in annotation. Cf the layout package. It eases the migration when the package becomes official.

Penrodyn said...

What is the second argument, stddev or variance, I assume stddev?

I'm going to start implementing this weekend, it requires more work than I expected but it will mean I can easily include new user functions in the future, eg mod.

Herbert

Frank said...

Indeed stddev is the one. I still did not think you would have to do anything special in JDesigner. If it would allow us to use custom functions of the SBML file in all expressions, then it would all be taken care of!

Penrodyn said...

I've been working on getting things ready with JD. User defined functions have been reworked and I am now about to put in your noise functions.

Penrodyn said...

I was a bit worried about where one can use these noise generators in a simulator that doesn't explicitly support solving SDE. I talked to Kyung and the feeling is they can only be use in between integration steps. This means they cannot be used in any kind of rule that feeds into a kinetic law. As far as I remember SBML has no concept of rules being executed between integration steps, ie between calls to oneStep?

Frank said...

I found it to be save to call these functions in:

AssignmentRules (as long as the variables assigned to do not occur in any kinetics),
EventAssignments,
InitialAssignments,
Event Priorities
.
That matches with Kyungs feelings.

Penrodyn said...

The new JD is pretty much ready I just need to test it more.