Menu
▾
▴
[sbml-svn] SF.net SVN: sbml:[26293] trunk/specifications/sbml-level-3/version-1/ distrib
|
From: <luc...@us...> - 2020-03-25 02:25:23
|
Revision: 26293
http://sourceforge.net/p/sbml/code/26293
Author: luciansmith
Date: 2020-03-25 02:25:21 +0000 (Wed, 25 Mar 2020)
Log Message:
-----------
Have 'UncertParameter' not have mathematical meaning; add one-argument versions of two distributions for Chris.
Modified Paths:
--------------
trunk/specifications/sbml-level-3/version-1/distrib/figs/uncertParameter.pdf
trunk/specifications/sbml-level-3/version-1/distrib/sbml-level-3-distrib-package-proposal.pdf
trunk/specifications/sbml-level-3/version-1/distrib/sbml-level-3-distrib-package-proposal.tex
Modified: trunk/specifications/sbml-level-3/version-1/distrib/figs/uncertParameter.pdf
===================================================================
(Binary files differ)
Modified: trunk/specifications/sbml-level-3/version-1/distrib/sbml-level-3-distrib-package-proposal.pdf
===================================================================
(Binary files differ)
Modified: trunk/specifications/sbml-level-3/version-1/distrib/sbml-level-3-distrib-package-proposal.tex
===================================================================
--- trunk/specifications/sbml-level-3/version-1/distrib/sbml-level-3-distrib-package-proposal.tex 2020-03-11 15:25:03 UTC (rev 26292)
+++ trunk/specifications/sbml-level-3/version-1/distrib/sbml-level-3-distrib-package-proposal.tex 2020-03-25 02:25:21 UTC (rev 26293)
@@ -51,8 +51,8 @@
\packageTitle{The Distributions Package\\for SBML Level 3}
-\packageVersion{Version \changed{0.25} (Draft)}
-\packageVersionDate{\changed{June XX, 2019}}
+\packageVersion{Version \changed{0.26} (Draft)}
+\packageVersionDate{\changed{July 29, 2019}}
%\packageGeneralURL{http://sbml.org/Community/Wiki/SBML_Level_3_Proposals/Distributions_and_Ranges}
%\packageThisVersionURL{}
@@ -147,6 +147,8 @@
0.23 (Draft) & February 2019 & Lucian Smith and Michael Hucka & Removal of Distribution and all subclasses; replaced with a \Math element instead; collapsed UncertStatistics into Uncertainty; some other edits.\\
\midrule
0.24 (Draft) & April 2019 & Lucian Smith & Removal of second distrib namespace, and consolidation of the \UncertParameter class based on HARMONY 2019 discussions.\\
+\midrule
+0.25 (Draft) & July 2019 & Lucian Smith & The \token{id} of a \UncertParameter no longer has mathematical meaning in any other context.\\
\bottomrule
\end{edtable}
\end{table}
@@ -159,8 +161,8 @@
\subsection{What is the Distributions package?}
-The \distrib package (also known as \distribshort) provides an extension to SBML Level 3 that \changed{extends MathML to allow draws from distributions, and also provides the ability to annotate model elements with information about the distribution their
-values were drawn from.}
+The \distrib package (also known as \distribshort) provides an extension to SBML Level 3 that extends MathML to allow draws from distributions, and also provides the ability to annotate model elements with information about the distribution their
+values were drawn from.
\subsection{Scope}
@@ -168,8 +170,8 @@
probability distribution. In particular the following are in scope:
\begin{itemize}
-\item Sampling from a \changed{univariate} continuous distribution
-\item Sampling from a \changed{univariate} discrete distribution
+\item Sampling from a univariate continuous distribution
+\item Sampling from a univariate discrete distribution
\item Sampling from a user-defined discrete probability density function
\item Specification of descriptive statistics (mean, standard
deviation, standard error, etc.)
@@ -179,8 +181,8 @@
package but are now \textbf{out of scope}:
\begin{itemize}
-\item \changed{Sampling from a multivariate distribution}
-\item Definitions of ranges \changed{as new first-order objects (the 'Arrays' package now fills that objective)}
+\item Sampling from a multivariate distribution
+\item Definitions of ranges as new first-order objects (the 'Arrays' package now fills that objective)
\item Sampling from user-defined probability density function
\item Stochastic differential equations
\item Other functions used to characterise a probability distribution,
@@ -340,7 +342,7 @@
together to work out the details of how this package would work in
detail. Dan Cornford from the \uncertml
project\footnote{\url{http://www.uncertml.org/}} attended the meeting
-and described how \changed{UncertML} could be used to describe uncertainty
+and described how UncertML could be used to describe uncertainty
and in particular probability distributions. Perhaps the most
significant decision at this meeting was to adopt the \uncertml
resource as a controlled vocabulary that is referenced by the \distrib package.
@@ -572,13 +574,13 @@
\subsubsection{The approach}
-The \distrib package has two simple purposes. First, it provides a mechanism for sampling a random value from a probability distribution. This implies that it must define the probability distribution and then must sample a random value from that distribution. Second, it provides a mechanism for describing elements with information about their uncertainty. \changed{An example} use case for this is to provide the standard deviation for a value. Another \changed{might be} describing a parameter's distribution \changed{so it could be used in a} parameter scan experiment.
+The \distrib package has two simple purposes. First, it provides a mechanism for sampling a random value from a probability distribution. This implies that it must define the probability distribution and then must sample a random value from that distribution. Second, it provides a mechanism for describing elements with information about their uncertainty. An example use case for this is to provide the standard deviation for a value. Another might be describing a parameter's distribution so it could be used in a parameter scan experiment.
-\changed{Sampling from probability distributions} is achieved by allowing new \mathml elements, and \changed{encoding uncertainty} by extending \SBase, which in turn uses the \Uncertainty class. Several distributions and statistics are defined explicitly in this specification, but more can be defined by referencing an external ontology such as ProbOnto through the \UncertParameter class.
+Sampling from probability distributions is achieved by allowing new \mathml elements, and encoding uncertainty by extending \SBase, which in turn uses the \Uncertainty class. Several distributions and statistics are defined explicitly in this specification, but more can be defined by referencing an external ontology such as ProbOnto through the \UncertParameter class.
%It is hoped that with this approach, modelers may use the extensions defined in this specification with a reasonable expectation that most other software packages will also recognize them. However, if another distribution is required, those distributions may still be encoded through reference to an external ontology, even if this makes the model less exchangeable.
-When a call to a distribution is defined in the extended \Math, it is sampled when it is invoked. If a particular \changed{sampled value should be used multiple times}, that value must be assigned to a parameter first, such as through the use of an \InitialAssignment or \EventAssignment. When an \changed{external} distribution is defined, \changed{it is not used in the math of the model, but may be used externally where appropriate.}
+When a call to a distribution is defined in the extended \Math, it is sampled when it is invoked. If a particular sampled value should be used multiple times, that value must be assigned to a parameter first, such as through the use of an \InitialAssignment or \EventAssignment. When an external distribution is defined, it is not used in the math of the model, but may be used externally where appropriate.
\begin{table}[]
@@ -589,39 +591,41 @@
\toprule
\textbf{URI} & \textbf{\textsf{\textup{Possible arguments}}} \\
\midrule
-http://www.sbml.org/sbml/symbols/distrib/normal & normal(mean, stdev) \\
- & normal(mean, stdev, min, max)
+http://www.sbml.org/sbml/symbols/distrib/normal & normal(mean, stdev) \\
+ & normal(mean, stdev, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/uniform & uniform(min, max)
+http://www.sbml.org/sbml/symbols/distrib/uniform & uniform(min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/bernoulli & bernoulli(prob)
+http://www.sbml.org/sbml/symbols/distrib/bernoulli & bernoulli(prob)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/binomial & binomial(nTrials, probabilityOfSuccess) \\
- & binomial(nTrials, probabilityOfSuccess, min, max)
+http://www.sbml.org/sbml/symbols/distrib/binomial & binomial(nTrials, probabilityOfSuccess) \\
+ & binomial(nTrials, probabilityOfSuccess, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/cauchy & cauchy(location, scale) \\
- & cauchy(location, scale, min, max)
+http://www.sbml.org/sbml/symbols/distrib/cauchy & cauchy(scale) \\
+ & cauchy(location, scale) \\
+ & cauchy(location, scale, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/chisquare & chisquare(degreesOfFreedom) \\
- & chisquare(degreesOfFreedom, min, max)
+http://www.sbml.org/sbml/symbols/distrib/chisquare & chisquare(degreesOfFreedom) \\
+ & chisquare(degreesOfFreedom, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/exponential & exponential(rate)\\
- & exponential(rate, min, max)
+http://www.sbml.org/sbml/symbols/distrib/exponential & exponential(rate)\\
+ & exponential(rate, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/gamma & gamma(shape, scale) \\
- & gamma(shape, scale, min, max)
+http://www.sbml.org/sbml/symbols/distrib/gamma & gamma(shape, scale) \\
+ & gamma(shape, scale, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/laplace & laplace(location, scale) \\
- & laplace(location, scale, min, max)
+http://www.sbml.org/sbml/symbols/distrib/laplace & laplace(scale) \\
+ & laplace(location, scale) \\
+ & laplace(location, scale, min, max) \\
+\midrule
+http://www.sbml.org/sbml/symbols/distrib/lognormal & lognormal(mean, stdev) \\
+ & lognormal(mean, stdev, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/lognormal & lognormal(mean, stdev) \\
- & lognormal(mean, stdev, min, max)
+http://www.sbml.org/sbml/symbols/distrib/poisson & poisson(rate) \\
+ & poisson(rate, min, max)
\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/poisson & poisson(rate) \\
- & poisson(rate, min, max)
-\\ \midrule
-http://www.sbml.org/sbml/symbols/distrib/rayleigh & rayleigh(scale) \\
- & rayleigh(scale, min, max)
+http://www.sbml.org/sbml/symbols/distrib/rayleigh & rayleigh(scale) \\
+ & rayleigh(scale, min, max)
\\
\bottomrule
\label{tab:csymbols}
@@ -640,6 +644,8 @@
To define a distribution with only one bound, the other bound should be defined as INF or -INF, as appropriate. For those distributions that have an intrisic lower bound of 0, setting \token{min} to 0 or any negative number will have no effect, but is legal.
+\changed{The versions of \token{cauchy} and \token{laplace} with one argument draw from the corresponding distribution with that argument as its scale value, and a value of \val{0} for its \token{location}.}
+
\paragraph{Fallback functions}
If an SBML interpreter is unable to calculate one or more of the above extended \mathml functions, it may simply fail, or it might choose to return the mean of the given function instead. In either case, it is a good idea to inform the user that the model cannot be interpreted by the software as intended. Note that the mean of a discrete distribution is not necessarily a legal return value for that function, as it may not be an integer.
@@ -892,7 +898,7 @@
\paragraph{Propagation of error}
-It may be possible to \changed{propagate the error defined in \Uncertainty elements through the mathematics defined in a simulation of the model}. Be advised that this will be a complicated system, and may involve calculating partial derivates of equations that are not explicitly encoded. Many simulators choose instead to estimate the error through stochastic simulations. Either approach should be possible with a properly encoded \distribshort model.
+It may be possible to propagate the error defined in \Uncertainty elements through the mathematics defined in a simulation of the model. Be advised that this will be a complicated system, and may involve calculating partial derivates of equations that are not explicitly encoded. Many simulators choose instead to estimate the error through stochastic simulations. Either approach should be possible with a properly encoded \distribshort model.
\subsubsection{Attributes inherited from \SBase}
@@ -984,7 +990,7 @@
The optional \token{definitionURL} attribute (of type \primtype{ExternalRef}) may be used when the \token{type} of the \UncertParameter is \val{distribution}, and must be used when the \token{type} of the \UncertParameter is \val{externalParameter}. The \primtype{ExternalRef} should point to an ontology URL, distribution \token{csymbol}, or other unique definition string that defines what is meant by this \UncertParameter. The \token{definitionURL} must not be defined if the \token{type} is any other value: the other types are already completely defined.
\subsubsection{Attributes inherited from \SBase}
-An \UncertParameter always inherits the optional \token{metaid} and \token{sboTerm} attributes, and inherits optional \token{id} and \token{name} attributes as described in \sec{sec:idname}. The \token{id} of a \UncertParameter takes the mathematical value of its \token{value} attribute if that attribute is defined, and the mathematical value of the corresponding \token{var} if that attribute is defined. This meaning may be used in other contexts, but that meaning may not be set directly by any other SBML element of any Level, Version, or package. If setting the value is desired, the \token{var} attribute should be used, and that referenced element set as per normal SBML procedures. The meaning is provided mostly to allow access to the \token{val} attribute, which otherwise would be undiscoverable to any other SBML element.
+An \UncertParameter always inherits the optional \token{metaid} and \token{sboTerm} attributes, and inherits optional \token{id} and \token{name} attributes as described in \sec{sec:idname}. The \token{id} of a \UncertParameter \changed{does not take on the mathematical value of its \token{value} attribute, and may not be used in mathematical contexts. Instead, if the value of the element is to be used elsewhere, the \token{var} attribute should be used instead, and that referenced value used in other contexts.}
\subsubsection{The child \token{math} element}
The optional \token{math} element contains MathML, and may only be used for an \UncertParameter of type \val{distribution} or \val{externalParameter}. When defined for a \val{distribution}, the MathML should define that distribution, such as by using one of the extended \token{csymbol} definitions from this specification.
@@ -1202,7 +1208,7 @@
In this example, the initial amount of 3.22 is noted as having a mean of 3.2, a standard deviation of 0.3, and a variance of 0.09. Note that the standard deviation can be calculated from the variance (or visa versa), but the modeler has chosen to include both here for convenience. Note too that this use of the \Uncertainty element does not imply that the species amount comes from a normal distribution with a mean of 3.2 and standard deviation of 0.3, but rather that the species amount comes from an unknown distribution with those qualities. If it is known that the value was drawn from a particular distribution, an \UncertParameter of type \val{distribution} should be used, rather than \UncertParameter elements of type \val{mean} and \val{standardDeviation}.
-Note also that 3.22 (the \token{initialAmount}) is different from 3.2 (the \token{mean}): evidently, this model was constructed as a realization of the underlying uncertainty, instead of \changed{simply using the mean}.
+Note also that 3.22 (the \token{initialAmount}) is different from 3.2 (the \token{mean}): evidently, this model was constructed as a realization of the underlying uncertainty, instead of simply using the mean.
\subsubsection{Defining a random variable}
@@ -1434,7 +1440,7 @@
\subsection{The \arrays package}
This package is dependent on no other package, but might rely on the \arrays package
-to provide vector and matrix structures if those are desired/used. Note that currently, the only \changed{case where arrays could be used is when} an \UncertParameter of type \val{externalParameter} is defined that requires array input or output.
+to provide vector and matrix structures if those are desired/used. Note that currently, the only case where arrays could be used is when an \UncertParameter of type \val{externalParameter} is defined that requires array input or output.
\subsection{SBML Level~3 Version~2}
This package may be used with either SBML Level~3 Version~1 Core, or SBML Level~3 Version~2 Core, and no construct in this package changes as a result: the addition of \token{id} and \token{name} to \DistribBase means that the addition of those attributes to \SBase in SBML Level~3 Version~2 Core is redundant.
|
