Supporting probability distributions of initial conditions and parameters specified in SBML

[djinnome]

Hi folks,

MIRA does not currently support distributions of initial conditions and parameters that are specified in SBML.

https://sbml.org/documents/specifications/level-3/version-1/distrib/

Here is the libsbml API documentation for the distributions package:

https://sbml.org/software/libsbml/5.20.2/cpp-api/group__distrib.html

Here is an easy way to specify distributions in SBML using SBMLutils:

https://sbmlutils.readthedocs.io/en/latest/notebooks/sbml_distrib.html

Here is another way to specify distributions in SBML using Antimony:

https://tellurium.readthedocs.io/en/latest/antimony.html#uncertainty-information

Here are the distributions that Antimony supports:

Distribution	Description
Normal (mean, sd)	Normal distribution with mean and standard deviation
truncatedNormal (mean, sd, min, max)	Limit the normal disturbing to a range
uniform (min, max)	Uniform distribution with given minimum and maximum range
exponential (rate)	Exponential distribution with given rate
truncatedExponential (rate, min, max)	Exponential distribution with given range
gamma (shape, scale)	Gamma distribution
truncatedGamma (shape, scale, min, max)	Gamma distribution with range
poisson (rate)	Poisson distribution
truncatedPoisson(rate, min, max)	Poisson distribution with range

I do not think this is needed for our use case, but I was surprised to learn that Antimony/SBML also supports the specification of static and dynamic parameter interventions:

https://www.biorxiv.org/content/10.1101/015503v1.full

To put this in concrete terms, let us imagine a model of a particular neuron. If the concentration of $S_1$ goes above $5$, a depolarization event is likely to happen, taking an average of
$2$ seconds to do so, which will reset the concentration of $S_1$ to zero. However, if the concentration of $S_1$ goes below $5$, depolarization can no longer take place. This can be modeled by
the following SBML event, written here in Antimony shorthand:

depolarization: at exponential(0.5) after S1 > 5, persistent=true: S1=0

or in SBML:

<event id="depolarization" useValuesFromTriggerTime="true">
    <trigger initialValue="true" persistent="true">
         <math xmlns="http://www.w3.org/1998/Math/MathML">
            <apply>
               <gt/>
               <ci> S1 </ci>
              <cn type="integer"> 5 </cn>
            </apply>
         </math>
     </trigger>
  <delay>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
        <apply>
          <ci> exponential </ci>
          <cn> 0.5 </cn>
        </apply>
     </math>
  </delay>
  <listOfEventAssignments>
    <eventAssignment variable="S1">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <cn type="integer"> 0 </cn>
      </math>
    </eventAssignment>
  </listOfEventAssignments>
</event>

@augeorge would you be willing to populate the gene regulatory SBML model with distribution information as an example?

[augeorge]

done @djinnome

below is an example SBML model for a simple 4 state system with uniform distributions added for the state variables and parameters.

SBML file

4 state model diagram:

related notebook

[bgyori]

@djinnome, @augeorge thanks, the issue is I can't access the SBML file and the notebook since I think those are in a private repo. Could you put those somewhere public or attach them directly to the issue here? Thanks!

[djinnome]

Sorry about that! We went through information release and software disclosure, so we are able to make the repo public, but it looks like the links are broken anyway, so I will just attach the files here.

ABCD_model.xml.gz

pyciemss_test.ipynb.gz

[bgyori]

We've been looking into this but it is tricky to implement from a technical perspective because libSBML doesn't support the elements related to distributions (the documentation above about this makes it seem like it might but in practice, these attributes are just not there). This makes it nontrivial to traverse these elements via the SBML object model - though not impossible. So it will take a bit more time.

[djinnome]

I think the issue is that you need to explicitly load the distrib package in libsbml.

Here is an example where the sbmlutils package (which is a more pythonic high level interface for libsbml) supports distributions:

https://sbmlutils.readthedocs.io/en/latest/notebooks/sbml_distrib.html

Here is an example of how to load the distrib package using the low-level python-libsbml api:

https://github.com/matthiaskoenig/sbmlutils/blob/7b3af189ed67e612b443c1a4e4254078b77fa679/src/sbmlutils/distrib/distrib_examples.py#L11-L20