From 8428e00ff98d999709adf5a57d61662c5978f82e Mon Sep 17 00:00:00 2001 From: Jonathan Karr Date: Wed, 6 May 2020 13:20:31 -0400 Subject: [PATCH 01/10] generalizing targets beyond XML XPATHs to any unambiguous address --- specification/level-1-version-4/sources/concepts.tex | 2 +- specification/level-1-version-4/sources/data.tex | 2 +- .../level-1-version-4/sources/generalElements.tex | 8 ++++---- specification/level-1-version-4/sources/introduction.tex | 2 +- specification/level-1-version-4/sources/model.tex | 8 ++++---- .../level-1-version-4/sources/styles/latex-macros.tex | 1 + specification/level-1-version-4/sources/task.tex | 2 +- 7 files changed, 13 insertions(+), 12 deletions(-) diff --git a/specification/level-1-version-4/sources/concepts.tex b/specification/level-1-version-4/sources/concepts.tex index cdf37d04..7fafd379 100644 --- a/specification/level-1-version-4/sources/concepts.tex +++ b/specification/level-1-version-4/sources/concepts.tex @@ -379,7 +379,7 @@ \subsection{Annotation Scheme} % ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \section{XPath} \label{sec:xpath} -\concept{XPath} is a language for finding and referencing information in an XML document \citep{xpath:1999}. Within SED-ML \currentLV, XPath version 1 expressions are used to identify nodes and attributes within an XML representation in the following ways: +\concept{XPath} is a language for finding and referencing information in an XML document \citep{xpath:1999}. Within SED-ML \currentLV, XPath version 1 expressions can be used to identify nodes and attributes within an XML representation of an XML-encoded model in the following ways: \begin{itemize} \item {Within a \Variable definition, where \concept{XPath} identifies the model variable required for manipulation in SED-ML.} diff --git a/specification/level-1-version-4/sources/data.tex b/specification/level-1-version-4/sources/data.tex index c2382447..c11fffc4 100644 --- a/specification/level-1-version-4/sources/data.tex +++ b/specification/level-1-version-4/sources/data.tex @@ -106,7 +106,7 @@ \subsubsection{\element{DataSource}} This represents a change from \LoneVone and \LoneVtwo, in which a \token{taskReference} was always present for a \token{variable} in a \DataGenerator. -To indicate that the \hyperref[sec:target]{\element{target}} of the \Variable is an entity defined within the current SED-ML description (and not an \hyperref[sec:xpath]{Xpath} expression) the hashtag (\#) with the reference to an \hyperref[type:id]{\element{id}} is used. +To indicate that the \hyperref[sec:target]{\element{target}} of the \Variable is an entity defined within the current SED-ML description (and not an entity in an external document, such as referenced by a \hyperref[sec:xpath]{Xpath} expression) the hashtag (\#) with the reference to an \hyperref[type:id]{\element{id}} is used. In addition, this example uses the \hyperref[sec:modelReference]{\element{modelReference}}, in order to facilitate a mapping of the data with a given model. diff --git a/specification/level-1-version-4/sources/generalElements.tex b/specification/level-1-version-4/sources/generalElements.tex index 74b940ed..40d22e2c 100644 --- a/specification/level-1-version-4/sources/generalElements.tex +++ b/specification/level-1-version-4/sources/generalElements.tex @@ -338,7 +338,7 @@ \subsection{\element{Variable}} - + [FURTHER VARIABLE DEFINITIONS] [..] @@ -364,11 +364,11 @@ \subsection{\element{Variable}} % ~~~ TARGET ~~~ \paragraph*{\element{target}} \label{sec:target} -An instance of \Variable can refer to a model constituent inside a particular \hyperref[class:model]{model} through an \code{\hyperref[type:xpath]{XPath}} expression stored in the \concept{\element{target}} attribute. +An instance of \Variable can refer to a model constituent inside a particular \hyperref[class:model]{model} through the address stored in the \concept{\element{target}} attribute, such as an \code{\hyperref[type:xpath]{XPath}} expression. The \concept{\element{target}} attribute may also be used to reference an entity within the SED-ML file itself, by containing a fragment identifier consisting of a hash character (\code{\#}) followed by the \SId of the targeted element. As of SED-ML \currentLV this is used to refer to a \hyperref[class:dataSource]{DataSource} in a \Variable or to refer to \hyperref[class:listOfRanges]{ranges} within a \hyperref[class:repeatedTask]{repeatedTask} (see Listing~\ref{lst:repeatedTask}). -Note that while it is possible to write \code{\hyperref[type:xpath]{XPath}} expressions that select multiple nodes within a referenced model, when used within a \concept{\element{target}} attribute a single element or attribute \emph{must} be selected by the expression. +Note that while it is possible to write addresses that select multiple nodes within a referenced model, when used within a \concept{\element{target}} attribute a single element or attribute \emph{must} be selected by the expression. \lsttexta{target}{target} In the example the \concept{\element{target}} is used to reference a species with \element{id='PY'} in an SBML model. @@ -459,7 +459,7 @@ \subsection{\element{RemainingDimension}} \subsection{\element{DependentVariable}} \label{class:dependentVariable} -The \DependentVariable object is a child of the \Variable class, extending it to include three new attributes: \element{term} (of type \element{URN}), \element{target2} (of type XPath), and \element{symbol2} (of type URN). A dependent variable is necessary when the desired variable is a composite of two other variables, such as 'the rate of change of S1 with respect to time'. +The \DependentVariable object is a child of the \Variable class, extending it to include three new attributes: \element{term} (of type \element{URN}), \element{target2} (of type Target), and \element{symbol2} (of type URN). A dependent variable is necessary when the desired variable is a composite of two other variables, such as 'the rate of change of S1 with respect to time'. In a \DependentVariable, the \element{term} is used to define the relationship of the two variables (i.e. 'rate of change'), the \element{target} or \element{symbol} attributes are used to define the first such variable, and the new \element{target2} and \element{symbol2} is used to define the second variable. diff --git a/specification/level-1-version-4/sources/introduction.tex b/specification/level-1-version-4/sources/introduction.tex index 69f8b135..aa396d23 100644 --- a/specification/level-1-version-4/sources/introduction.tex +++ b/specification/level-1-version-4/sources/introduction.tex @@ -36,7 +36,7 @@ \section{SED-ML overview} \paragraph*{\Model} The \Model class allows to reference the models used in a simulation experiment. -The \hyperref[class:change]{Change} class allows to modify models (pre-processing), i.e., changing the value of an observable, computing the change of a value using mathematics, or general changes on any XML element of the model representation that is addressable by \hyperref[sec:xpath]{XPath} expressions, e.g., substituting a piece of XML by an updated one. +The \hyperref[class:change]{Change} class allows to modify models (pre-processing), i.e., changing the value of an observable, computing the change of a value using mathematics, or general changes on any element of the model representation that is addressable by an unambiguous target, such as an \hyperref[sec:xpath]{XPath} expression for an entity in an XML-encoded model, e.g., substituting a piece of XML by an updated one. \paragraph*{\Simulation} The \Simulation class defines the simulation settings and the steps taken during simulation. These include the particular type of simulation, the algorithm, and the algorithm parameters used for the execution of the simulation. diff --git a/specification/level-1-version-4/sources/model.tex b/specification/level-1-version-4/sources/model.tex index caeacad5..810cba56 100644 --- a/specification/level-1-version-4/sources/model.tex +++ b/specification/level-1-version-4/sources/model.tex @@ -108,7 +108,7 @@ \subsection{\element{Change}} The \concept{Change} class is abstract and serves as the base class for different types of changes, the \hyperref[class:changeAttribute]{ChangeAttribute}, \hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML}, and \ComputeChange. -The \concept{Change} class has the mandatory attribute \hyperref[sec:changeTarget]{target} which defines the target of the change. The \hyperref[sec:changeTarget]{\element{target}} attribute holds a valid \hyperref[sec:xpath]{XPath} expression pointing to the XML element or XML attribute that is to undergo the defined changes. Except for the cases of \hyperref[class:changeXml]{ChangeXML} and \hyperref[class:removeXml]{RemoveXML}, this \hyperref[sec:xpath]{XPath} expression must always select a single element or attribute within the relevant model. +The \concept{Change} class has the mandatory attribute \hyperref[sec:changeTarget]{target} which defines the target of the change. The \hyperref[sec:changeTarget]{\element{target}} attribute holds an unambiguous description of the address of the element or attribute that is to undergo the defined changes, such as a valid \hyperref[sec:xpath]{XPath} expression pointing to the XML element or XML attribute. For \hyperref[class:newXml]{NewXML}, \hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, and \hyperref[class:removeXml]{RemoveXML}, \hyperref[sec:changeTarget]{target} must be an \hyperref[sec:xpath]{XPath} expression. Except for the cases of \hyperref[class:changeXml]{ChangeXML} and \hyperref[class:removeXml]{RemoveXML}, this \hyperref[sec:xpath]{XPath} expression must always select a single element or attribute within the relevant model. \sedfig[width=1.0\textwidth]{images/uml/change}{The SED-ML Change class}{fig:sedChange} @@ -116,7 +116,7 @@ \subsection{\element{Change}} % ~~~ target ~~~ \paragraph*{\element{target}} \label{sec:changeTarget} -The \concept{\element{target}} attribute holds a valid \hyperref[sec:xpath]{XPath} expression of data type \hyperref[type:xpath]{\element{xpath}} pointing to the XML element or XML attribute that is to undergo the defined changes. +The \concept{\element{target}} attribute holds an unambiguous description of the address of an element or attribute of a model that is to undergo the defined changes. For XML model languages such as SBML, \hyperref[sec:changeTarget]{\element{target}} should be a valid \hyperref[sec:xpath]{XPath} expression of data type \hyperref[type:xpath]{\element{xpath}} pointing to the XML element or XML attribute that is to undergo the defined changes. % ~~~ NewXML ~~~ @@ -196,7 +196,7 @@ \subsubsection{\element{RemoveXML}} % ~~~ ChangeAttribute ~~~ \subsubsection{\element{ChangeAttribute}} \label{class:changeAttribute} -The \concept{ChangeAttribute} class allows to define updates on the XML attribute values of the corresponding model (\fig{sedChange}). \concept{ChangeAttribute} requires to specify the \hyperref[sec:changeTarget]{\element{target}} of the change, i.e., the location of the addressed XML attribute, and also the \hyperref[sec:newValue]{\element{newValue}} of that attribute. Note that the XPath expression in the \hyperref[sec:changeTarget]{\element{target}} attribute must select a single attribute within the corresponding model. +The \concept{ChangeAttribute} class allows to define updates on the attribute values of the corresponding model (\fig{sedChange}). \concept{ChangeAttribute} requires to specify the \hyperref[sec:changeTarget]{\element{target}} of the change, i.e., the location of the addressed attribute, and also the \hyperref[sec:newValue]{\element{newValue}} of that attribute. Note that the \hyperref[sec:changeTarget]{\element{target}} attribute must select a single attribute within the corresponding model. The \hyperref[class:changeXml]{ChangeXML} class covers the possibilities provided by the \concept{ChangeAttribute} class, i.e, everything that can be expressed by a \concept{ChangeAttribute} construct can also be expressed by \hyperref[class:changeXml]{ChangeXML}. However, for the common case of changing an attribute value \concept{ChangeAttribute} is easier to use, and so it is recommended to use the \concept{ChangeAttribute} for any changes of an XML attribute's value, and to use the more general \hyperref[class:changeXml]{ChangeXML} for other cases. @@ -221,7 +221,7 @@ \subsubsection{\element{ChangeAttribute}} % ~~~ ComputeChange ~~~ \subsubsection{\element{ComputeChange}} \label{class:computeChange} -The \concept{ComputeChange} class permits to change, prior to the experiment, the numerical value of any element or attribute of a \Model addressable by an \hyperref[sec:xpath]{XPath} expression, based on a calculation (\fig{sedChange}). \changed{It inherits the \element{target} attribute from the \Change abstract base class, as well as the standard \SedBase attributes and children, and its ability to perform a calculation is described in the \Calculation class. (For implementations, if multiple inheritance is not possible, the children of \Calculation should just be added directly to the \ComputeChange class itself.)} +The \concept{ComputeChange} class permits to change, prior to the experiment, the numerical value of any element or attribute of a \Model addressable by a \hyperref[sec:changeTarget]{\element{target}}, based on a calculation (\fig{sedChange}). \changed{It inherits the \element{target} attribute from the \Change abstract base class, as well as the standard \SedBase attributes and children, and its ability to perform a calculation is described in the \Calculation class. (For implementations, if multiple inheritance is not possible, the children of \Calculation should just be added directly to the \ComputeChange class itself.)} \changed{The change is calculated from the \Math of the \Calculation, and applied to the \element{target} of the \Change.} diff --git a/specification/level-1-version-4/sources/styles/latex-macros.tex b/specification/level-1-version-4/sources/styles/latex-macros.tex index 0406c8f6..f32cd749 100644 --- a/specification/level-1-version-4/sources/styles/latex-macros.tex +++ b/specification/level-1-version-4/sources/styles/latex-macros.tex @@ -110,6 +110,7 @@ \newcommand{\MappingType} {\hyperref[type:mappingType]{MappingType}\xspace} \newcommand{\ScaleType} {\hyperref[type:scaleType]{ScaleType}\xspace} \newcommand{\XPath} {\hyperref[sec:xpath]{XPath}\xspace} +\newcommand{\Target} {Target\xspace} \newcommand{\AbstractCurve} {\hyperref[class:abstractCurve]{\emph{AbstractCurve}}\xspace} diff --git a/specification/level-1-version-4/sources/task.tex b/specification/level-1-version-4/sources/task.tex index ebc58dbc..40812a35 100644 --- a/specification/level-1-version-4/sources/task.tex +++ b/specification/level-1-version-4/sources/task.tex @@ -350,7 +350,7 @@ \subsubsection{\element{AdjustableParameter}} \label{class:adjustableParameter} \label{class:listOfExperimentRefs} -The \AdjustableParameter inherits from \SedBase, and adds a required attribute \element{target} of type \XPath, a required child \Bounds, and an optional child \ListOfExperimentRefs with zero or more \ExperimentRef elements, and an optional attribute \element{initalValue} of type \code{double}. +The \AdjustableParameter inherits from \SedBase, and adds a required attribute \element{target} of type \Target, a required child \Bounds, and an optional child \ListOfExperimentRefs with zero or more \ExperimentRef elements, and an optional attribute \element{initalValue} of type \code{double}. The \element{target} of an \AdjustableParameter must point to an adjustable element of the \Model referenced by the parent \ParameterEstimationTask. This element is one of the elements whose value can be changed by the task in order to optimize the fit experiments. From b3acccddbe212081875fca5f50faa20e59f41acd Mon Sep 17 00:00:00 2001 From: Jonathan Karr Date: Wed, 6 May 2020 13:21:04 -0400 Subject: [PATCH 02/10] adding URN for BNGL --- specification/level-1-version-4/sources/concepts.tex | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/level-1-version-4/sources/concepts.tex b/specification/level-1-version-4/sources/concepts.tex index 7fafd379..d7133fd4 100644 --- a/specification/level-1-version-4/sources/concepts.tex +++ b/specification/level-1-version-4/sources/concepts.tex @@ -220,6 +220,7 @@ \subsection{Language references} \toprule \textbf{Language} & \textbf{URN}\\ \midrule +BNGL (generic) & \code{urn:sedml:language:bgnl} \\ CellML (generic) & \code{urn:sedml:language:cellml} \\ CellML 1.0 & \code{urn:sedml:language:cellml.1\_0} \\ CellML 1.1 & \code{urn:sedml:language:cellml.1\_1} \\ From d36933945b29a616b3b4b3e04652201cfb6ce8da Mon Sep 17 00:00:00 2001 From: Jonathan Karr Date: Wed, 6 May 2020 13:32:19 -0400 Subject: [PATCH 03/10] generalizing application of SED-ML beyond XML-based model languages --- specification/level-1-version-4/sed-ml-L1V4.tex | 2 +- .../level-1-version-4/sources/concepts.tex | 2 +- specification/level-1-version-4/sources/model.tex | 14 +++++++------- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/specification/level-1-version-4/sed-ml-L1V4.tex b/specification/level-1-version-4/sed-ml-L1V4.tex index 3e546de8..03e7e536 100644 --- a/specification/level-1-version-4/sed-ml-L1V4.tex +++ b/specification/level-1-version-4/sed-ml-L1V4.tex @@ -89,7 +89,7 @@ \chapter{Examples} \label{app:examples} This appendix presents selected SED-ML examples. These examples are only illustrative and do not intend to demonstrate the full capabilities of SED-ML. For a more comprehensive view of the SED-ML features refer to the specification (Chapter~\ref{chp:specification}). -The presented examples use models encoded in SBML and CellML. SED-ML is not restricted to those formats, but can be used with models encoded in formats serialized in XML (see Section~\ref{sec:languageURI} for more information). +The presented examples use models encoded in SBML and CellML. SED-ML is not restricted to those formats. See Section~\ref{sec:languageURI} for more information. All specification examples listed below are available as \hyperref[sec:archive]{Combine Archives} from \url{http://sed-ml.org/} under the \code{*.omex} file name for the respective example. diff --git a/specification/level-1-version-4/sources/concepts.tex b/specification/level-1-version-4/sources/concepts.tex index d7133fd4..3c5b82a0 100644 --- a/specification/level-1-version-4/sources/concepts.tex +++ b/specification/level-1-version-4/sources/concepts.tex @@ -210,7 +210,7 @@ \subsection{Language references} To help software decide whether or not it supports a SED-ML description file, the information on the \hyperref[class:model]{model} encoding for each referenced \hyperref[class:model]{model} can be provided through the \hyperref[sec:language]{\element{language}} attribute, as the description of a language name and version through an unrestricted \code{String} is error-prone. A prerequisite for a language to be fully supported by SED-ML is that a formalised language definition, e.g., an XML Schema, is provided online. SED-ML also defines a set of standard URIs to refer to particular language definitions. -To specify the language a model is encoded in, a set of pre-defined SED-ML URNs can be used (\tab{languageURI}). The structure of SED-ML language URNs is \element{urn:sedml:language:}\emph{\element{name.version}}. SED-ML allows to specify a model representation format very generally as being \code{XML}, if no standardised representation format has been used to encode the model. On the other hand, one can be as specific as defining a model being in a particular version of a language, e.g., SBML Level 3 Version 1 as \code{urn:sedml:language:sbml.level-3.version-1}. +To specify the language a model is encoded in, a set of pre-defined SED-ML URNs can be used (\tab{languageURI}). The structure of SED-ML language URNs is \element{urn:sedml:language:}\emph{\element{name.version}}. One can be as specific as defining a model being in a particular version of a language, e.g., SBML Level 3 Version 1 as \code{urn:sedml:language:sbml.level-3.version-1}. For additional information see the \hyperref[sec:language]{\element{language}} attribute on \Model. diff --git a/specification/level-1-version-4/sources/model.tex b/specification/level-1-version-4/sources/model.tex index 810cba56..18c199f9 100644 --- a/specification/level-1-version-4/sources/model.tex +++ b/specification/level-1-version-4/sources/model.tex @@ -13,8 +13,8 @@ \subsection{\element{Model}} The \concept{Model} class refers to the particular model of interest through the \hyperref[sec:model_source]{\element{source}} attribute. The restrictions on the model reference are \begin{itemize} - \item{The model must be encoded in an XML format.} - \item{To refer to the model encoding language, a reference to a valid definition of that XML format must be given (\hyperref[sec:language]{\element{language}} attribute).} + \item{The model must be encoded in a well-defined format.} + \item{To refer to the model encoding language, a reference to a valid definition of that format must be given (\hyperref[sec:language]{\element{language}} attribute).} \item{To refer to a particular model in an external resource, an unambiguous reference must be given (\hyperref[sec:model_source]{\element{source}} attribute).} \end{itemize} @@ -50,7 +50,7 @@ \subsection{\element{Model}} \label{sec:language} The optional \concept{\element{language}} attribute of data type \hyperref[type:anyURI]{\code{anyURI}} is used to specify the format of the \hyperref[class:model]{model}. Example formats are SBML (\code{urn:sedml:language:sbml}) or CellML (\code{urn:sedml:language:cellml}). The supported languages are defined in the \hyperref[sec:languageURI]{language references}. -If it is not explicitly defined the default value for \concept{\element{language}} is \code{urn:sedml:language:xml}, referring to any XML based model representation. However, the use of the \concept{\element{language}} attribute is strongly encouraged for two reasons. Firstly, it helps to decide whether or not one is able to run the simulation, that is to parse the model referenced in the SED-ML file. Secondly, the language attribute is also needed to decide how to handle the \hyperref[sec:implicitVariable]{Symbols} in the \Variable class, as the interpretation of \hyperref[sec:implicitVariable]{Symbols} depends on the language of the representation format. +If it is not explicitly defined, the default value for \concept{\element{language}} is \code{urn:sedml:language:xml}, referring to any XML-based model representation. However, the use of the \concept{\element{language}} attribute is strongly encouraged for two reasons. Firstly, it helps to decide whether or not one is able to run the simulation, that is to parse the model referenced in the SED-ML file. Secondly, the language attribute is also needed to decide how to handle the \hyperref[sec:implicitVariable]{Symbols} in the \Variable class, as the interpretation of \hyperref[sec:implicitVariable]{Symbols} depends on the language of the representation format. % ~~~ MODEL:SOURCE ~~~ @@ -101,9 +101,9 @@ \subsection{\element{Change}} \label{class:change} The \concept{Change} class allows to describe changes applied to a \hyperref[class:model]{model} before simulation (\fig{sedChange}). \concept{Changes} can be of the following types: \begin{itemize} - \item{Changes on attributes of the model's XML representation (\hyperref[class:changeAttribute]{ChangeAttribute})} - \item{Changes on any XML snippet of the model's XML representation (\hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML})} + \item{Changes on attributes of the model (\hyperref[class:changeAttribute]{ChangeAttribute})} \item{Changes based on mathematical calculations (\ComputeChange)} + \item{For XML-encoded models, changes on any XML snippet of the model's XML representation (\hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML})} \end{itemize} The \concept{Change} class is abstract and serves as the base class for different types of changes, the \hyperref[class:changeAttribute]{ChangeAttribute}, \hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML}, and \ComputeChange. @@ -198,12 +198,12 @@ \subsubsection{\element{ChangeAttribute}} \label{class:changeAttribute} The \concept{ChangeAttribute} class allows to define updates on the attribute values of the corresponding model (\fig{sedChange}). \concept{ChangeAttribute} requires to specify the \hyperref[sec:changeTarget]{\element{target}} of the change, i.e., the location of the addressed attribute, and also the \hyperref[sec:newValue]{\element{newValue}} of that attribute. Note that the \hyperref[sec:changeTarget]{\element{target}} attribute must select a single attribute within the corresponding model. -The \hyperref[class:changeXml]{ChangeXML} class covers the possibilities provided by the \concept{ChangeAttribute} class, i.e, everything that can be expressed by a \concept{ChangeAttribute} construct can also be expressed by \hyperref[class:changeXml]{ChangeXML}. However, for the common case of changing an attribute value \concept{ChangeAttribute} is easier to use, and so it is recommended to use the \concept{ChangeAttribute} for any changes of an XML attribute's value, and to use the more general \hyperref[class:changeXml]{ChangeXML} for other cases. +The \hyperref[class:changeXml]{ChangeXML} class covers the possibilities provided by the \concept{ChangeAttribute} class, i.e, everything that can be expressed by a \concept{ChangeAttribute} construct can also be expressed by \hyperref[class:changeXml]{ChangeXML}. However, for the common case of changing an attribute value \concept{ChangeAttribute} is easier to use, and so it is recommended to use the \concept{ChangeAttribute} for any changes of an attribute's value, and to use the more general \hyperref[class:changeXml]{ChangeXML} for other cases. \paragraph*{\element{newValue}} \label{sec:newValue} -The mandatory \concept{\element{newValue}} attribute of data type \code{string} assignes a new value to the targeted XML attribute. +The mandatory \concept{\element{newValue}} attribute of data type \code{string} assignes a new value to the targeted attribute. The example in Listing~\ref{lst:changeAttribute} shows the update of the value of two parameters inside an SBML model. From 4d3a5d43fdce2da7d309ff2a14c3274a6849f963 Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 16:37:10 -0700 Subject: [PATCH 04/10] Update sed-ml-L1V4.tex --- specification/level-1-version-4/sed-ml-L1V4.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/level-1-version-4/sed-ml-L1V4.tex b/specification/level-1-version-4/sed-ml-L1V4.tex index 03e7e536..51a85ffe 100644 --- a/specification/level-1-version-4/sed-ml-L1V4.tex +++ b/specification/level-1-version-4/sed-ml-L1V4.tex @@ -89,7 +89,7 @@ \chapter{Examples} \label{app:examples} This appendix presents selected SED-ML examples. These examples are only illustrative and do not intend to demonstrate the full capabilities of SED-ML. For a more comprehensive view of the SED-ML features refer to the specification (Chapter~\ref{chp:specification}). -The presented examples use models encoded in SBML and CellML. SED-ML is not restricted to those formats. See Section~\ref{sec:languageURI} for more information. +The presented examples use models encoded in SBML and CellML\changed{, though SED-ML is not restricted to those formats. See} Section~\ref{sec:languageURI} for more information. All specification examples listed below are available as \hyperref[sec:archive]{Combine Archives} from \url{http://sed-ml.org/} under the \code{*.omex} file name for the respective example. From 471c1da996b299f2d3957e2455a75601b6774e1a Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 16:41:32 -0700 Subject: [PATCH 05/10] Update concepts.tex --- specification/level-1-version-4/sources/concepts.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/level-1-version-4/sources/concepts.tex b/specification/level-1-version-4/sources/concepts.tex index 3c5b82a0..62f62523 100644 --- a/specification/level-1-version-4/sources/concepts.tex +++ b/specification/level-1-version-4/sources/concepts.tex @@ -210,7 +210,7 @@ \subsection{Language references} To help software decide whether or not it supports a SED-ML description file, the information on the \hyperref[class:model]{model} encoding for each referenced \hyperref[class:model]{model} can be provided through the \hyperref[sec:language]{\element{language}} attribute, as the description of a language name and version through an unrestricted \code{String} is error-prone. A prerequisite for a language to be fully supported by SED-ML is that a formalised language definition, e.g., an XML Schema, is provided online. SED-ML also defines a set of standard URIs to refer to particular language definitions. -To specify the language a model is encoded in, a set of pre-defined SED-ML URNs can be used (\tab{languageURI}). The structure of SED-ML language URNs is \element{urn:sedml:language:}\emph{\element{name.version}}. One can be as specific as defining a model being in a particular version of a language, e.g., SBML Level 3 Version 1 as \code{urn:sedml:language:sbml.level-3.version-1}. +To specify the language a model is encoded in, a set of pre-defined SED-ML URNs can be used (\tab{languageURI}). The structure of SED-ML language URNs is \element{urn:sedml:language:}\emph{\element{name.version}}. \changed{One} can be as specific as defining a model being in a particular version of a language, e.g., SBML Level 3 Version 1 as \code{urn:sedml:language:sbml.level-3.version-1}. For additional information see the \hyperref[sec:language]{\element{language}} attribute on \Model. @@ -220,7 +220,7 @@ \subsection{Language references} \toprule \textbf{Language} & \textbf{URN}\\ \midrule -BNGL (generic) & \code{urn:sedml:language:bgnl} \\ +\changed{BNGL (generic) & \code{urn:sedml:language:bgnl}} \\ CellML (generic) & \code{urn:sedml:language:cellml} \\ CellML 1.0 & \code{urn:sedml:language:cellml.1\_0} \\ CellML 1.1 & \code{urn:sedml:language:cellml.1\_1} \\ @@ -380,7 +380,7 @@ \subsection{Annotation Scheme} % ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \section{XPath} \label{sec:xpath} -\concept{XPath} is a language for finding and referencing information in an XML document \citep{xpath:1999}. Within SED-ML \currentLV, XPath version 1 expressions can be used to identify nodes and attributes within an XML representation of an XML-encoded model in the following ways: +\concept{XPath} is a language for finding and referencing information in an XML document \citep{xpath:1999}. Within SED-ML \currentLV, XPath version 1 expressions \changed{can be used to identify nodes and attributes within an XML representation of an XML-encoded model} in the following ways: \begin{itemize} \item {Within a \Variable definition, where \concept{XPath} identifies the model variable required for manipulation in SED-ML.} @@ -398,7 +398,8 @@ \section{XPath} which will only be interpretable by standard XML software tools if the SBML file declares no namespaces (and hence is invalid SBML). -Following the convention of other \concept{XPath} host languages such as XPointer and XSLT, the prefixes used within \concept{XPath} expressions must be declared using namespace declarations within the SED-ML document, and be in-scope for the relevant expression. Thus for the correct example above, there must also be an ancestor element of the node containing the XPath expression that has an attribute like: +Following the convention of other \concept{XPath} host languages such as XPointer and XSLT, the prefixes used within \concept{XPath} expressions must be declared using namespace declarations within the SED-ML document, and be in-scope for the relevant expression. Thus for the correct example above, there must also be an ancestor element of the node containing the +ssion that has an attribute like: \begin{alltt} xmlns:sbml=`http://www.sbml.org/sbml/level3/version1/core' \end{alltt} From 6b6743f5654ca7eb14f83f7e6fb967c6d054e57b Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 16:42:30 -0700 Subject: [PATCH 06/10] Update data.tex --- specification/level-1-version-4/sources/data.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/level-1-version-4/sources/data.tex b/specification/level-1-version-4/sources/data.tex index c11fffc4..a5946245 100644 --- a/specification/level-1-version-4/sources/data.tex +++ b/specification/level-1-version-4/sources/data.tex @@ -106,7 +106,7 @@ \subsubsection{\element{DataSource}} This represents a change from \LoneVone and \LoneVtwo, in which a \token{taskReference} was always present for a \token{variable} in a \DataGenerator. -To indicate that the \hyperref[sec:target]{\element{target}} of the \Variable is an entity defined within the current SED-ML description (and not an entity in an external document, such as referenced by a \hyperref[sec:xpath]{Xpath} expression) the hashtag (\#) with the reference to an \hyperref[type:id]{\element{id}} is used. +To indicate that the \hyperref[sec:target]{\element{target}} of the \Variable is an entity defined within the current SED-ML description (and not an \changed{entity in an external document, such as referenced by a} \hyperref[sec:xpath]{Xpath} expression) the hashtag (\#) with the reference to an \hyperref[type:id]{\element{id}} is used. In addition, this example uses the \hyperref[sec:modelReference]{\element{modelReference}}, in order to facilitate a mapping of the data with a given model. From 9a53a2ea4e4022211d9da4bd76bf19d44bc8eb16 Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 17:04:36 -0700 Subject: [PATCH 07/10] Update generalElements.tex --- specification/level-1-version-4/sources/generalElements.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/level-1-version-4/sources/generalElements.tex b/specification/level-1-version-4/sources/generalElements.tex index 40d22e2c..d998079b 100644 --- a/specification/level-1-version-4/sources/generalElements.tex +++ b/specification/level-1-version-4/sources/generalElements.tex @@ -338,7 +338,7 @@ \subsection{\element{Variable}} - + [FURTHER VARIABLE DEFINITIONS] [..] @@ -364,11 +364,11 @@ \subsection{\element{Variable}} % ~~~ TARGET ~~~ \paragraph*{\element{target}} \label{sec:target} -An instance of \Variable can refer to a model constituent inside a particular \hyperref[class:model]{model} through the address stored in the \concept{\element{target}} attribute, such as an \code{\hyperref[type:xpath]{XPath}} expression. +An instance of \Variable can refer to a model constituent inside a particular \hyperref[class:model]{model} through \changed{the address stored in the \concept{\element{target}} attribute, such as an \code{\hyperref[type:xpath]{XPath}} expression}. The \concept{\element{target}} attribute may also be used to reference an entity within the SED-ML file itself, by containing a fragment identifier consisting of a hash character (\code{\#}) followed by the \SId of the targeted element. As of SED-ML \currentLV this is used to refer to a \hyperref[class:dataSource]{DataSource} in a \Variable or to refer to \hyperref[class:listOfRanges]{ranges} within a \hyperref[class:repeatedTask]{repeatedTask} (see Listing~\ref{lst:repeatedTask}). -Note that while it is possible to write addresses that select multiple nodes within a referenced model, when used within a \concept{\element{target}} attribute a single element or attribute \emph{must} be selected by the expression. +Note that while it is possible to write \changed{addresses} that select multiple nodes within a referenced model, when used within a \concept{\element{target}} attribute a single element or attribute \emph{must} be selected by the expression. \lsttexta{target}{target} In the example the \concept{\element{target}} is used to reference a species with \element{id='PY'} in an SBML model. From ffbbfeebd37dfcadfc86ad7f6a0d29c746a42906 Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 17:06:09 -0700 Subject: [PATCH 08/10] Update introduction.tex --- specification/level-1-version-4/sources/introduction.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/level-1-version-4/sources/introduction.tex b/specification/level-1-version-4/sources/introduction.tex index aa396d23..cd0a054f 100644 --- a/specification/level-1-version-4/sources/introduction.tex +++ b/specification/level-1-version-4/sources/introduction.tex @@ -36,7 +36,7 @@ \section{SED-ML overview} \paragraph*{\Model} The \Model class allows to reference the models used in a simulation experiment. -The \hyperref[class:change]{Change} class allows to modify models (pre-processing), i.e., changing the value of an observable, computing the change of a value using mathematics, or general changes on any element of the model representation that is addressable by an unambiguous target, such as an \hyperref[sec:xpath]{XPath} expression for an entity in an XML-encoded model, e.g., substituting a piece of XML by an updated one. +The \hyperref[class:change]{Change} class allows to modify models (pre-processing), i.e., changing the value of an observable, computing the change of a value using mathematics, or general changes on \changed{any element of the model representation that is addressable by an unambiguous target, such as an \hyperref[sec:xpath]{XPath} expression for an entity in an XML-encoded model}, e.g., substituting a piece of XML by an updated one. \paragraph*{\Simulation} The \Simulation class defines the simulation settings and the steps taken during simulation. These include the particular type of simulation, the algorithm, and the algorithm parameters used for the execution of the simulation. From 49d21f4cf44e5becc4bbe4e24592e901c2496e1b Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 17:11:34 -0700 Subject: [PATCH 09/10] Update model.tex --- .../level-1-version-4/sources/model.tex | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/level-1-version-4/sources/model.tex b/specification/level-1-version-4/sources/model.tex index 18c199f9..b164696a 100644 --- a/specification/level-1-version-4/sources/model.tex +++ b/specification/level-1-version-4/sources/model.tex @@ -13,7 +13,7 @@ \subsection{\element{Model}} The \concept{Model} class refers to the particular model of interest through the \hyperref[sec:model_source]{\element{source}} attribute. The restrictions on the model reference are \begin{itemize} - \item{The model must be encoded in a well-defined format.} + \item{The model must be encoded in \changed{a well-defined format}.} \item{To refer to the model encoding language, a reference to a valid definition of that format must be given (\hyperref[sec:language]{\element{language}} attribute).} \item{To refer to a particular model in an external resource, an unambiguous reference must be given (\hyperref[sec:model_source]{\element{source}} attribute).} \end{itemize} @@ -101,14 +101,14 @@ \subsection{\element{Change}} \label{class:change} The \concept{Change} class allows to describe changes applied to a \hyperref[class:model]{model} before simulation (\fig{sedChange}). \concept{Changes} can be of the following types: \begin{itemize} - \item{Changes on attributes of the model (\hyperref[class:changeAttribute]{ChangeAttribute})} + \item{Changes on \changed{attributes of the model} (\hyperref[class:changeAttribute]{ChangeAttribute})} \item{Changes based on mathematical calculations (\ComputeChange)} - \item{For XML-encoded models, changes on any XML snippet of the model's XML representation (\hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML})} + \item{\changed{For XML-encoded models, changes on any XML snippet of the model's XML representation} (\hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML})} \end{itemize} The \concept{Change} class is abstract and serves as the base class for different types of changes, the \hyperref[class:changeAttribute]{ChangeAttribute}, \hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, \hyperref[class:removeXml]{RemoveXML}, and \ComputeChange. -The \concept{Change} class has the mandatory attribute \hyperref[sec:changeTarget]{target} which defines the target of the change. The \hyperref[sec:changeTarget]{\element{target}} attribute holds an unambiguous description of the address of the element or attribute that is to undergo the defined changes, such as a valid \hyperref[sec:xpath]{XPath} expression pointing to the XML element or XML attribute. For \hyperref[class:newXml]{NewXML}, \hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, and \hyperref[class:removeXml]{RemoveXML}, \hyperref[sec:changeTarget]{target} must be an \hyperref[sec:xpath]{XPath} expression. Except for the cases of \hyperref[class:changeXml]{ChangeXML} and \hyperref[class:removeXml]{RemoveXML}, this \hyperref[sec:xpath]{XPath} expression must always select a single element or attribute within the relevant model. +The \concept{Change} class has the mandatory attribute \hyperref[sec:changeTarget]{target} which defines the target of the change. The \hyperref[sec:changeTarget]{\element{target}} attribute holds \changed{an unambiguous description of the address of the element or attribute that is to undergo the defined changes, such as a valid \hyperref[sec:xpath]{XPath} expression pointing to the XML element or XML attribute. For \hyperref[class:newXml]{NewXML}, \hyperref[class:addXml]{AddXML}, \hyperref[class:changeXml]{ChangeXML}, and \hyperref[class:removeXml]{RemoveXML}, \hyperref[sec:changeTarget]{target} must be an \hyperref[sec:xpath]{XPath} expression.} Except for the cases of \hyperref[class:changeXml]{ChangeXML} and \hyperref[class:removeXml]{RemoveXML}, this \hyperref[sec:xpath]{XPath} expression must always select a single element or attribute within the relevant model. \sedfig[width=1.0\textwidth]{images/uml/change}{The SED-ML Change class}{fig:sedChange} @@ -116,7 +116,7 @@ \subsection{\element{Change}} % ~~~ target ~~~ \paragraph*{\element{target}} \label{sec:changeTarget} -The \concept{\element{target}} attribute holds an unambiguous description of the address of an element or attribute of a model that is to undergo the defined changes. For XML model languages such as SBML, \hyperref[sec:changeTarget]{\element{target}} should be a valid \hyperref[sec:xpath]{XPath} expression of data type \hyperref[type:xpath]{\element{xpath}} pointing to the XML element or XML attribute that is to undergo the defined changes. +The \concept{\element{target}} attribute holds \changed{an unambiguous description of the address of an element or attribute of a model that is to undergo the defined changes. For XML model languages such as SBML, \hyperref[sec:changeTarget]{\element{target}} should be} a valid \hyperref[sec:xpath]{XPath} expression of data type \hyperref[type:xpath]{\element{xpath}} pointing to the XML element or XML attribute that is to undergo the defined changes. % ~~~ NewXML ~~~ @@ -196,14 +196,14 @@ \subsubsection{\element{RemoveXML}} % ~~~ ChangeAttribute ~~~ \subsubsection{\element{ChangeAttribute}} \label{class:changeAttribute} -The \concept{ChangeAttribute} class allows to define updates on the attribute values of the corresponding model (\fig{sedChange}). \concept{ChangeAttribute} requires to specify the \hyperref[sec:changeTarget]{\element{target}} of the change, i.e., the location of the addressed attribute, and also the \hyperref[sec:newValue]{\element{newValue}} of that attribute. Note that the \hyperref[sec:changeTarget]{\element{target}} attribute must select a single attribute within the corresponding model. +The \concept{ChangeAttribute} class allows to define updates on the attribute values of the corresponding model (\fig{sedChange}). \concept{ChangeAttribute} requires to specify the \hyperref[sec:changeTarget]{\element{target}} of the change, i.e., the location of the addressed attribute, and also the \hyperref[sec:newValue]{\element{newValue}} of that attribute. Note that \changed{the \hyperref[sec:changeTarget]{\element{target}} attribute} must select a single attribute within the corresponding model. The \hyperref[class:changeXml]{ChangeXML} class covers the possibilities provided by the \concept{ChangeAttribute} class, i.e, everything that can be expressed by a \concept{ChangeAttribute} construct can also be expressed by \hyperref[class:changeXml]{ChangeXML}. However, for the common case of changing an attribute value \concept{ChangeAttribute} is easier to use, and so it is recommended to use the \concept{ChangeAttribute} for any changes of an attribute's value, and to use the more general \hyperref[class:changeXml]{ChangeXML} for other cases. \paragraph*{\element{newValue}} \label{sec:newValue} -The mandatory \concept{\element{newValue}} attribute of data type \code{string} assignes a new value to the targeted attribute. +The mandatory \concept{\element{newValue}} attribute of data type \code{string} assignes a new value to the \changed{targeted attribute}. The example in Listing~\ref{lst:changeAttribute} shows the update of the value of two parameters inside an SBML model. @@ -221,7 +221,7 @@ \subsubsection{\element{ChangeAttribute}} % ~~~ ComputeChange ~~~ \subsubsection{\element{ComputeChange}} \label{class:computeChange} -The \concept{ComputeChange} class permits to change, prior to the experiment, the numerical value of any element or attribute of a \Model addressable by a \hyperref[sec:changeTarget]{\element{target}}, based on a calculation (\fig{sedChange}). \changed{It inherits the \element{target} attribute from the \Change abstract base class, as well as the standard \SedBase attributes and children, and its ability to perform a calculation is described in the \Calculation class. (For implementations, if multiple inheritance is not possible, the children of \Calculation should just be added directly to the \ComputeChange class itself.)} +The \concept{ComputeChange} class permits to change, prior to the experiment, the numerical value of any element or attribute of a \Model addressable by \changed{a \hyperref[sec:changeTarget]{\element{target}}}, based on a calculation (\fig{sedChange}). \changed{It inherits the \element{target} attribute from the \Change abstract base class, as well as the standard \SedBase attributes and children, and its ability to perform a calculation is described in the \Calculation class. (For implementations, if multiple inheritance is not possible, the children of \Calculation should just be added directly to the \ComputeChange class itself.)} \changed{The change is calculated from the \Math of the \Calculation, and applied to the \element{target} of the \Change.} From 55c355b1d5b0c16e979f2fc7d3037b8ff20def05 Mon Sep 17 00:00:00 2001 From: Lucian Smith Date: Tue, 13 Oct 2020 17:13:31 -0700 Subject: [PATCH 10/10] Update task.tex --- specification/level-1-version-4/sources/task.tex | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/level-1-version-4/sources/task.tex b/specification/level-1-version-4/sources/task.tex index 40812a35..a3dd17ed 100644 --- a/specification/level-1-version-4/sources/task.tex +++ b/specification/level-1-version-4/sources/task.tex @@ -45,7 +45,8 @@ \subsubsection{\element{SimpleRepeated Task}} The \concept{SimpleRepeatedTask} inherits from \Task, and provides a simplified looping construct that performs the \Task multiple times, resetting the model or not, according to its \element{resetModel} attribute. The task itself is defined by the \element{modelReference} and \element{simulationReference} attributes it inherits from \Task. \paragraph*{\element{resetModel}} -The \element{resetModel} attribute, of type \element{boolean} defines whether, for each execution of the simulation, the model is to be reset (\val{true}) or not (\val{false}). +The \element{resetModel} attribute, +\element{boolean} defines whether, for each execution of the simulation, the model is to be reset (\val{true}) or not (\val{false}). \paragraph*{\element{numRepeats}} The \element{numRepeats}, of type \element{positive integer}, defines the number of times the simulation is to be performed. @@ -350,7 +351,7 @@ \subsubsection{\element{AdjustableParameter}} \label{class:adjustableParameter} \label{class:listOfExperimentRefs} -The \AdjustableParameter inherits from \SedBase, and adds a required attribute \element{target} of type \Target, a required child \Bounds, and an optional child \ListOfExperimentRefs with zero or more \ExperimentRef elements, and an optional attribute \element{initalValue} of type \code{double}. +The \AdjustableParameter inherits from \SedBase, and adds a required attribute \element{target} \changed{of type \Target}, a required child \Bounds, and an optional child \ListOfExperimentRefs with zero or more \ExperimentRef elements, and an optional attribute \element{initalValue} of type \code{double}. The \element{target} of an \AdjustableParameter must point to an adjustable element of the \Model referenced by the parent \ParameterEstimationTask. This element is one of the elements whose value can be changed by the task in order to optimize the fit experiments.