-
Notifications
You must be signed in to change notification settings - Fork 9
/
combinatorialDerivation.tex
139 lines (105 loc) · 11.8 KB
/
combinatorialDerivation.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
\subsection{CombinatorialDerivation}
\label{sec:CombinatorialDerivation}
The purpose of the \sbol{CombinatorialDerivation} class is to specify combinatorial biological designs without having to specify every possible design variant. For example, a \sbol{CombinatorialDerivation} can be used to specify a library of reporter gene variants that include different promoters and RBSs without having to specify a \sbol{Component} for every possible combination of promoter, RBS, and CDS in the library. \sbol{Component} objects that realize a \sbol{CombinatorialDerivation} can be derived in accordance with the class properties \sbol{template}, \\
\sbol{hasVariableFeature}, and \sbol{strategy} (see \ref{uml:combinatorial_derivation}).
\begin{figure}[ht]
\begin{center}
\includegraphics[scale=0.6]{uml/combinatorial_derivation}
\caption[]{Diagram of the \sbol{CombinatorialDerivation} class and its associated properties.}
\label{uml:combinatorial_derivation}
\end{center}
\end{figure}
\subparagraph{The \sbolheading{template} property}\label{sec:template}
The \sbol{template} property is REQUIRED and MUST contain a IRI that refers to a \sbol{Component}.
This \sbol{Component} is expected to serve as a template for the derivation of new \sbol{Component} objects.
Consequently, its \sbol{hasFeature} properties SHOULD contain one or more \sbol{Feature} objects that will serve as the variables whose values are set during derivation (referred to hereafter as template \sbol{Feature} objects).
Its other property values describe aspects of the template that will not change based on the values that may be varied.
\subparagraph{The \sbolheading{hasVariableFeature} property}
\label{sec:hasVariableFeature}
Each \sbol{VariableFeature} child of a \sbol{CombinatorialDerivation} defines the set of possible values for one of the variables in the \sbol{template}.
A \sbol{CombinatorialDerivation} object can have zero or more \sbol{hasVariableFeature} properties, each of type \sbol{IRI}, specifying a \sbol{VariableFeature}.
The set of \sbol{hasVariableFeature} properties MUST NOT contain two or more \sbol{VariableFeature} objects that refer to the same template \\sbol{Feature} via their \sbol{variable} properties (i.e., do not define the same variable twice).
The \sbol{variable} properties of \sbol{VariableFeature} objects determined which \sbol{Feature} objects in the \sbol{template} are modified in a derived \sbol{Component}, and which ones will not be changed.
In particular, we will refer to a \sbol{Feature} in the template \sbol{Component} that is referred to by some \sbol{variable} property as a variable \sbol{Feature}, and one that is not referred to by any as a static \sbol{Feature}.
\subparagraph{The \sbolheading{strategy} property}\label{sec:strategy}
The \sbol{strategy} property is OPTIONAL and has a data type of IRI. \ref{tbl:strategy} provides a list of REQUIRED \sbol{strategy} URLs. If the \sbol{strategy} property is not empty, then it MUST contain a URL from \ref{tbl:strategy}. This property recommends how many \sbol{Component} objects SHOULD be derived from the template \sbol{Component}.
\begin{table}[ht]
\begin{edtable}{tabular}{lp{4in}}
\toprule
\textbf{Strategy URL} & \textbf{Description} \\
\midrule
\url{http://sbols.org/v3#enumerate} & Derivation SHOULD produce all possible \sbol{Component} objects specified by the \sbol{CombinatorialDerivation}. \\
\url{http://sbols.org/v3#sample} & Derivation SHOULD produce a subset of possible \sbol{Component} objects specified by \sbol{CombinatorialDerivation}. The manner in which this subset is chosen is left unspecified. \\
\bottomrule
\end{edtable}
\caption{REQUIRED \sbol{URL}s for the \sbol{strategy} property.}
\label{tbl:strategy}
\end{table}
\subparagraph{Executing a derivation}
When a \sbol{CombinatorialDerivation} is evaluated to produce a set of derived \sbol{Component} objects, the relationship between the two SHOULD be recorded by means of \prov{wasDerivedFrom} properties.
In particular:
\begin{itemize}
\item Any derived \sbol{Component} SHOULD have a \prov{wasDerivedFrom} property that refers to the \sbol{CombinatorialDerivation}.
\item Any \sbol{Feature} in a derived \sbol{Component} SHOULD have a \prov{wasDerivedFrom} property that refers to its corresponding \sbol{Feature} in the template \sbol{Component}.
\item Any \sbol{Collection} produced by the derivation process and containing only derived \sbol{Component} objects SHOULD also have a \prov{wasDerivedFrom} property that refers to the \sbol{CombinatorialDerivation}.
\end{itemize}
All derived objects MUST be consistent with the specification provided in the \sbol{CombinatorialDerivation}.
In particular:
\begin{itemize}
\item Every value of the \sbolmult{type:C}{type} and \sbolmult{role:C}{role} properties of the template \sbol{Component} SHOULD be contained in the values of the corresponding properties in each derived \sbol{Component}.
\item Any static \sbol{Feature} in the template \sbol{Component} SHOULD correspond to a \sbol{Feature} with identical properties in each derived \sbol{Component}.
\item Any variable \sbol{Feature} in the template \sbol{Component} SHOULD be replaced in each derived \sbol{Component} by a number of \sbol{Feature} objects constrained by the number specified by the \sbol{cardinality} property of the \sbol{VariableFeature} (see \ref{tbl:cardinality}).
\item Each property of a \sbol{Feature} object in the derived \sbol{Component} that replaces a variable \sbol{Feature} in the template \sbol{Component} MUST be derived from the values of the associated \sbol{VariableFeature}.
\item All derived \sbol{Feature} object MUST follow the \sbol{restriction} properties of any \sbol{Constraint} objects that refer to their corresponding template \sbol{Feature}. This will typically be used to rule out illegal combinations of variable values.
\item The \sbolmult{role:F}{role} property of a derived \sbol{Feature} SHOULD contain the same values as the \sbolmult{role:F}{role} property did in the template \sbol{Feature}.
\item The \sbolmult{type:C}{type} property of a derived \sbol{Feature} or its type-determining referent
(\sbol{instanceOf} for \sbol{SubComponent}, or that determined for the \sbol{Feature} referred to by a \sbol{ComponentReference})
SHOULD contain the same values as the \sbolmult{type:C}{type} property did in the template \sbol{Feature} or its type-determining referent.
\end{itemize}
\subsubsection{VariableFeature}
\label{sec:VariableFeature}
As described \sbolmult{hasVariableFeature}{above}, the \sbol{VariableFeature} class specifies a variable and set of values that will replace one of the \sbol{Feature} objects in the \sbol{template} of a \sbol{CombinatorialDerivation}.
The variable is specified by the \sbol{variable} property,
and the set of values is defined by the union of \sbol{Component} objects referred to by the \sbol{variant}, \sbol{variantCollection}, and \sbol{variantDerivation} properties.
Note that this union is intended to be a set and not a multi-set.
For example, if the \sbol{variant} property contains a \sbol{Component} $A$ and the \sbol{variantCollection} property has a \sbol{Collection} containing both \sbol{Component} $A$ and \sbol{Component} $B$, then $A$ SHOULD NOT be selected twice during enumeration, and it SHOULD NOT be selected twice as much as $B$ during sampling.
Given a set of values linked from a \sbol{VariableFeature}, it SHOULD be the case that all value are of type \sbol{om:Measure} or else all values are of type \sbol{Feature}. At present, it is explicitly left undefined how derivation of new components ought to handle mixtures of \sbol{om:Measure} and \sbol{Feature} values.
\begin{figure}[ht]
\begin{center}
\includegraphics[scale=0.6]{uml/variable_component}
\caption[]{Diagram of the \sbol{VariableFeature} class and its associated properties.}
\label{uml:variable_component}
\end{center}
\end{figure}
\subparagraph{The \sbolheading{variable} property}\label{sec:variable}
The \sbol{variable} property is REQUIRED and MUST contain a IRI that refers to a template \sbol{Feature} in the \sbol{template} \sbol{Component} referred to by this \sbol{VariableFeature}'s parent \sbol{CombinatorialDerivation}
\subparagraph{The \sbolheading{variantMeasure} property}\label{sec:variantMeasure}
A \sbol{VariableFeature} object can have zero or more \sbol{variantMeasure} properties, each of type \sbol{IRI}, specifying a \sbol{om:Measure} object. This property specifies numerical values that are options to be applied to the \sbol{variable} \sbol{Feature} from the \sbol{template} when deriving a new \sbol{Component}.
Note that because a \sbol{om:Measure} is not a \sbol{TopLevel}, the vlaues of \sbol{variantMeasure} must be child objects of the \sbol{VariableFeature}.
\subparagraph{The \sbolheading{variant} property}\label{sec:variant}
A \sbol{VariableFeature} object can have zero or more \sbol{variant} properties, each of type \sbol{IRI}, specifying a \sbol{Component} object. This property specifies individual \sbol{Component} objects to serve as options when deriving a new \sbol{Feature} for the \sbol{variable} \sbol{Feature} from the \sbol{template}.
\subparagraph{The \sbolheading{variantCollection} property}\label{sec:variantCollection}
A \sbol{VariableFeature} object can have zero or more \sbol{variantCollection} properties, each of type \sbol{IRI}, specifying a \sbol{Collection} object.
Such a \sbol{Collection} MUST NOT contain any objects besides \sbol{Component} objects or \sbol{Collection} objects that themselves contain only \sbol{Component} or \sbol{Collection} objects.
This property enables the specification of existing groups of \sbol{Component} objects to serve as options.
\subparagraph{The \sbolheading{variantDerivation} property}\label{sec:variantDerivation}
A \sbol{VariableFeature} object can have zero or more \sbol{variantDerivation} properties, each of type \sbol{IRI}, specifying a \sbol{CombinatorialDerivation} object.
This property enables the specification of \sbol{Component} objects derived in accordance with another \sbol{CombinatorialDerivation} to serve as options when deriving a new \sbol{Feature} for the \sbol{variable} \sbol{Feature} from the \sbol{template}.
The \sbol{variantDerivation} properties of a \sbol{VariableFeature} MUST NOT refer to the \sbol{CombinatorialDerivation} that contains this \sbol{VariableFeature}.
Furthermore, such \sbol{VariableFeature} objects MUST NOT form a cyclical chain of references via their \sbol{variantDerivation} properties and the \sbol{CombinatorialDerivation} objects that contain them.
\subparagraph{The \sbolheading{cardinality} property}\label{sec:cardinality}
The \sbol{cardinality} property is REQUIRED and has type of IRI. This property specifies how many \sbol{Feature} objects SHOULD be derived from the template \sbol{Feature} during the derivation of a new \sbol{Component}. The value of this property MUST come from the URLs provided in~\ref{tbl:cardinality}.
\begin{table}[ht]
\begin{edtable}{tabular}{lp{4in}}
\toprule
\textbf{Cardinality URL} & \textbf{Description} \\
\midrule
\url{http://sbols.org/v3#zeroOrOne} & No more than one \sbol{Feature} in the derived \sbol{Component} SHOULD have a \prov{wasDerivedFrom} property that refers to the template \sbol{Feature}. \\
\url{http://sbols.org/v3#one} & Exactly one \sbol{Feature} in the derived \sbol{Component} SHOULD have a \prov{wasDerivedFrom} property that refers to the template \sbol{Feature}. \\
\url{http://sbols.org/v3#zeroOrMore} & Any number of \sbol{Feature} objects in the derived \sbol{Component} MAY have \prov{wasDerivedFrom} properties that refer to the template \sbol{Feature}. \\
\url{http://sbols.org/v3#oneOrMore} & At least one \sbol{Feature} in the derived \sbol{Component} SHOULD have a \prov{wasDerivedFrom} property that refers to the template \sbol{Feature}. \\
\bottomrule
\end{edtable}
\caption{REQUIRED \sbol{URL}s for the \sbol{cardinality} property.}
\label{tbl:cardinality}
\end{table}