Merge branch 'SBOL3' of github.com:SynBioDex/SBOL-specification into …

…sep-015-025

.gitignore

@@ -1,10 +1,10 @@
 .DS_Store
-sbol2.aux
-sbol2.bbl
-sbol2.blg
-sbol2.cb
-sbol2.cb2
-sbol2.log
-sbol2.out
-sbol2.pdf
-sbol2.toc
+sbol3.aux
+sbol3.bbl
+sbol3.blg
+sbol3.cb
+sbol3.cb2
+sbol3.log
+sbol3.out
+sbol3.pdf
+sbol3.toc

compliance.tex

@@ -1,6 +1,6 @@
 \section{SBOL Compliance}
 
-\twozeroone{
+
 There are different types of software compliance with respect to the SBOL specification.  First, a software tool can either support all classes of the SBOL 2.x data model or only its structural subset.  The structural subset includes the following classes:
 \begin{itemize}
 \item \sbol{Sequence}
@@ -25,5 +25,5 @@ \section{SBOL Compliance}
 This validator can also be used to check lossless import/export support, since it can compare the data content of files imported and exported by a software tool.
 
 Finally, developers of SBOL-compliant tools are encouraged to notify the SBOL editors\\([email protected]) when they have determined that their tool is SBOL compliant, so their tool can be publicly categorized as such on the SBOL website.
-}
+
 

examples_model.tex

@@ -11,7 +11,7 @@ \section{Data Model Examples}
 With repressors LacI and TetR, this results in a bi-stable system that will tend to settle into a state where precisely one of the two repressors is strongly expressed, repressing the other.
 Each of these repressors can have its activity disrupted by a small molecule (IPTG for LacI, aTc for TetR), which enables the system to be ``toggled'' from one state to the other by dosing it with the appropriate small molecule.
 
-\twotwozero{
+
 \begin{figure}[ht]
 \begin{center}
 \includegraphics[width=0.33\textwidth]{images/toggle-highlevel2.pdf}
@@ -31,7 +31,7 @@ \section{Data Model Examples}
 \label{images:toggleswitch_modular}
 \end{center}
 \end{figure}
-}
+
 
 The LacI/TetR toggle switch is modeled in SBOL as two parallel hierarchies of structure and function. The structural hierarchy of the toggle switch is represented using \sbol{Component}s:
 \begin{itemize}
@@ -47,15 +47,15 @@ \section{Data Model Examples}
 \end{center}
 \end{figure}
 
-\twozeroone{
+
 \begin{figure}[ht]
 \begin{center}
 \includegraphics[width=\textwidth]{example_uml/toggle_2}
 \caption[]{Composite \sbol{Component} objects for the LacI inverter. In the case of the \sbol{Component} that represents the TetR gene, its sub-\sbol{SubComponent} objects are located as \sbol{Range}s along its \sbol{Sequence} using \sbol{SequenceAnnotation} objects. The \sbol{Component} that represents the IPTG-LacI complex, however, has no \sbol{Sequence} and its sub-\sbol{SubComponent} objects are composed without any data about their relative positions.}
 \label{uml:ex_comp_def_compo}
 \end{center}
 \end{figure}
-}
+
 
 The functional hierarchy of the toggle switch is represented using
 \sbol{Component}s:
@@ -64,7 +64,7 @@ \section{Data Model Examples}
 \item Base elements are composed to form the toggle switch at the top of the hierarchy.  As an example, \ref{uml:ex_mod_def_compo} is a UML diagram of the \sbol{Component} that represents the toggle switch.
 \end{itemize}
 
-\twozeroone{
+
 \begin{figure}[ht]
 \begin{center}
 \includegraphics[width=\textwidth]{example_uml/toggle_3}
@@ -81,7 +81,7 @@ \section{Data Model Examples}
 \label{uml:ex_mod_def_compo}
 \end{center}
 \end{figure}
-}
+
 
 % Each \sbol{Component} also contains the \sbol{SubComponent}s that participate in \sbol{Interaction}s and are defined by the same \sbol{Component}s as the parallel \sbol{SubComponent}s in the structural hierarchy of the toggle switch. Finally, \sbol{MapsTo} entities are used to refine which \sbol{SubComponent}s of the functional hierarchy are identical or map them to \sbol{SubComponent}s in the structural hierarchy.
 

practices.tex

@@ -2,9 +2,9 @@
 \section{Recommended Best Practices}
 \label{sec:bestpractices}
 % -----------------------------------------------------------------------------
-\twozeroone{\subsection{SBOL Namespaces}
+\subsection{SBOL Namespaces}
 
-Namespaces for different versions of SBOL SHOULD NOT be semantically mixed in the same document. For example, an SBOL 3.x \sbol{SubComponent} SHOULD NOT refer to an SBOL 1.x DNAComponent. However, namespaces for different versions MAY be present in the same document so long as they are semantically independent (that is, so long as objects belonging to these namespaces do not refer to each other). When multiple SBOL namespaces are present in a document, libraries SHOULD default to interpreting as SBOL only those objects belonging to the namespace for the most recent version of SBOL in the document. Any remaining objects belonging to any other SBOL namespace SHOULD be interpreted as \sbol{GenericTopLevel}s and custom \sbol{Annotation}s.}
+Namespaces for different versions of SBOL SHOULD NOT be semantically mixed in the same document. For example, an SBOL 3.x \sbol{ComponentInstance} SHOULD NOT refer to an SBOL 1.x DNAComponent. However, namespaces for different versions MAY be present in the same document so long as they are semantically independent (that is, so long as objects belonging to these namespaces do not refer to each other). When multiple SBOL namespaces are present in a document, libraries SHOULD default to interpreting as SBOL only those objects belonging to the namespace for the most recent version of SBOL in the document. Any remaining objects belonging to any other SBOL namespace SHOULD be interpreted as \sbol{GenericTopLevel}s and custom \sbol{Annotation}s.
 
 \subsection{Use of the Version Property}
 
@@ -98,10 +98,10 @@ \subsection{Recommended Ontologies for External Terms}
   \label{tbl:preferred_external_resources}
 \end{table}
 
-\twoonezero{The URIs for ontological terms SHOULD come from identifiers.org.  However, it is acceptable to use terms from purl.org as an alternative, for example when RDF tooling requires URIs to be represented as compliant QNames.  SBOL software may convert between these forms as required.}
+The URIs for ontological terms SHOULD come from identifiers.org.  However, it is acceptable to use terms from purl.org as an alternative, for example when RDF tooling requires URIs to be represented as compliant QNames.  SBOL software may convert between these forms as required.
 
-\twozeroone{\subsection{Annotating Entities with Date \& Time}\label{sec:DateTime}
-Entities in an SBOL document can be annotated with creation and modification date. It is RECOMMENDED that predicates, or properties, from DCMI Metadata Terms SHOULD be used to include date and time information. The \texttt{created} and \texttt{modified} terms SHOULD respectively be used to annotate SBOL entities with creation and modification dates. Date and time values SHOULD be expressed using the XML Schema \texttt{DateTime} datatype~\citep{Biron2004}. For example, "\texttt{2016-03-16T20:12:00Z}" specifies that the day is 16 March 2016 and the time is 20:12pm in UTC (Coordinated Universal Time). An example serialization is shown below:}
+\subsection{Annotating Entities with Date \& Time}\label{sec:DateTime}
+Entities in an SBOL document can be annotated with creation and modification date. It is RECOMMENDED that predicates, or properties, from DCMI Metadata Terms SHOULD be used to include date and time information. The \texttt{created} and \texttt{modified} terms SHOULD respectively be used to annotate SBOL entities with creation and modification dates. Date and time values SHOULD be expressed using the XML Schema \texttt{DateTime} datatype~\citep{Biron2004}. For example, "\texttt{2016-03-16T20:12:00Z}" specifies that the day is 16 March 2016 and the time is 20:12pm in UTC (Coordinated Universal Time). An example serialization is shown below:
 
 \lstsetsbol
 \begin{lstlisting}
@@ -116,9 +116,9 @@ \subsection{Recommended Ontologies for External Terms}
 </rdf:RDF>
 \end{lstlisting}
 
-\twotwoone{\subsection{Annotating Entities with Authorship information}\label{sec:Authorship}
+\subsection{Annotating Entities with Authorship information}\label{sec:Authorship}
 Authorship information should ideally be added to \sbol{TopLevel} entities, where possible. It is RECOMMENDED that the \texttt{creator} DCMI Metadata term SHOULD be used to annotate SBOL entities with authorship information. This property can be repeated for each author. The example below shows the use of this property for two authors and the values shown are free text \texttt{String} literals.
-}
+
 \lstsetsbol
 \begin{lstlisting}
 <?xml version="1.0" ?>
@@ -132,3 +132,65 @@ \subsection{Recommended Ontologies for External Terms}
 </rdf:RDF>
 \end{lstlisting}
 
+\subsection{Host Context / Ontologies for Experiments}
+
+\subsubsection{Mixtures via Components}
+
+Any \sbol{Component} can be interpreted as specifying a mixture of the \sbol{SubComponent}s that it includes.
+
+The amount of each such instance included in the mixture SHOULD be specified by attaching a \sbol{Measure} with a \sbolmult{types:Measure}{type} set to the appropriate SBO term. The SBO terms that are RECOMMENDED as appropriate are members of the Systems Description Parameter (SBO:0000545) branch of SBO. Examples include:
+\begin{itemize}
+\item SBO:0000540: fraction of an entity pool (e.g., 1/3 CHO cells, 2/3 HEK cells)
+\item SBO:0000472: molar concentration of an entity (e.g., 1 mM Arabinose)
+\item SBO:0000361: amount of an entity pool (e.g., 200 uL M9 media)
+\end{itemize}
+
+\subsubsection{Media, Inducers, and Other Reagents}
+
+An ``atomic'' reagent, which is not expected to be divided further in designs, SHOULD be represented as a \linebreak \sbol{Component}. Examples: Arabinose, Kanamycin, Rainbow bead control
+
+A ``composite'' reagent, which might be defined as a mixture of other reagents, SHOULD be represented as a \sbol{Component} that defines it as a mixture of other reagents. This might be recursive, with mixtures of mixtures of mixtures, etc. Examples: M9 media, LB broth
+
+The roles of reagents may vary in context: for example, Arabinose may serve as an inducer or as a media carbon source. As such, role SHOULD be indicated by an NCI Thesaurus (NCIT) term in a \sbolmult{roles:MD}{role} property of the \sbol{SubComponent}. Examples include:
+\begin{itemize}
+\item NCIT:C64356: Positive Control
+\item NCIT:C48694: Cell
+\item NCIT:C85504: Media
+\item NCIT:C14419: Strain
+\item NCIT:C120268: Inducer
+\end{itemize}
+
+Note that this also implies that the \sbolmult{roles:C}{role} property should be promoted from \sbol{SubComponent} to \sbol{ComponentInstance} (so it can be used for \sbol{FunctionalComponent} as well) and also added to \sbol{Module}.
+
+\subsubsection{Strains, Genomes, and Plasmids}
+
+A cell strain SHOULD be represented as a \sbol{Component} containing at least:
+\begin{itemize}
+\item A \sbol{SubComponent} for the cell, which is RECOMMENDED to have \sbolmult{types:CD}{type} cell (GO:0005623) and \sbolmult{roles:MD}{role} physical compartment (SBO:0000290).
+\item A representation of its genetic material (genome, plasmids, etc.) as a collection of \sbol{SubComponent} instances.
+\item An \sbol{Interaction} of type \texttt{FunctionalCompartment} (SBO:0000289) with the cell participating as physical compartment (SBO: 0000290) and the genetic material participating as contained entity (SBO:0000664).
+\end{itemize}
+
+\subsubsection{Samples}
+
+A complete specification of a sample SHOULD be a \sbol{Component} that includes at least:
+\begin{itemize}
+\item A \sbol{Module} instantiating each strain in the sample
+\item A \sbol{SubComponent} for the media or buffer
+\item A \sbol{SubComponent} for each additional reagent added to the media (e.g., inducers, antibiotics)
+\item \sbol{Measure}s on each of these specifying the amount in the sample
+\item \sbol{Measure}s on the \sbol{Component} for each environmental parameter (e.g., temperature, pH, culturing time)
+\end{itemize}
+
+\subsubsection{Other Experimental Parameters}
+
+In order to deal with parameters associated with the context in general but not specific instances, e.g., temperature, pH, total sample volume, we need to add a \texttt{measures} property to \sbol{Component} (in addition to the ones already on \sbol{SubComponent}) and to \sbol{ComponentDefinition}.
+
+The distinction is that the \texttt{measures} of a \texttt{Component} provide context-free information (e.g., the pH of M9 media, the GC-content of a GFP coding sequence), while the \texttt{measures} on an \texttt{SubComponent} provide a measurement in context (e.g., the dosage of Arabinose in a sample).
+
+Values of these parameters SHOULD be specified by attaching a \sbol{Measure} with a \sbolmult{types:Measure}{type} set to the appropriate SBO term. The SBO terms that are RECOMMENDED as appropriate are members of the Systems Description Parameter (SBO:0000545) branch of SBO. Examples include:
+\begin{itemize}
+\item SBO:0000147: thermodynamic temperature (e.g., culturing at 27 C)
+\item SBO:0000332: half-life of an exponential decay (e.g., decay rate of a gRNA)
+\item SBO:0000304: pH (e.g., pH of M9 media)
+\end{itemize}

purpose.tex

@@ -25,14 +25,14 @@ \section{Purpose}
 %Goksel: Removed this sentence: The ultimate utility of URIs in the SBOL standard is the ability to support flexible annotation with appropriate metadata while associating an authority with that annotation. 
 The definition of the data model and associated format, the rules on the addition of data within the format and the representation of this in electronic data files are intended to make the SBOL standard a useful means of promoting global data exchange between laboratories and between software programs.
 
-\twothreezero{
+
 This document details version 2.3 of SBOL that builds upon the previous version 2.2. In particular, SBOL 2.3 includes means of succinctly representing sequence modifications (such as insertion, deletion, and replacement), an extension to support organization and attachment of experimental data derived from designs,
 and an extension for describing numerical parameters of design elements. The new version also includes typing of activities, unambiguous locations for sequences with multiple encodings, refinement of a number of validation rules, improved figures and examples, and clarification on a number of issues related to ontology terms. 
-}
 
-\twotwozero{Version 2.2 of SBOL in turn builds upon SBOL version 2.1. SBOL 2.2 included improved description and validation rules for genetic design provenance, an extension to support combinatorial genetic designs, a new class to add non-SBOL data as attachments, a new class for genetic design implementations, and a description of a methodology to describe the entire design-build-test-learn cycle within the SBOL data model.}
 
-\twoonezero{Version 2.1 included improved rules for what constitutes a valid SBOL document, new role fields to simplify the expression of sequence features and how components are used in context, and new best practices descriptions to improve the exchange of basic sequence topology information and the description of genetic design provenance.}
+Version 2.2 of SBOL in turn builds upon SBOL version 2.1. SBOL 2.2 included improved description and validation rules for genetic design provenance, an extension to support combinatorial genetic designs, a new class to add non-SBOL data as attachments, a new class for genetic design implementations, and a description of a methodology to describe the entire design-build-test-learn cycle within the SBOL data model.
+
+Version 2.1 included improved rules for what constitutes a valid SBOL document, new role fields to simplify the expression of sequence features and how components are used in context, and new best practices descriptions to improve the exchange of basic sequence topology information and the description of genetic design provenance.
 
 SBOL 2.x builds upon SBOL 1.1, which focused on representing the structural aspects of genetic designs. Users of the standard were able to exchange information on DNA designs, but they could not represent molecules other than DNA or the functional aspects of designs beyond DNA sequence features. The SBOL 2 data model defined in this specification extends the version 1.1 data model to provide for the most pressing data exchange needs identified by the SBOL community. In particular, the extended data model can:
 \begin{itemize}
@@ -48,14 +48,13 @@ \section{Purpose}
 \end{itemize}
 Taken together, these extensions enable SBOL to support the description and exchange of hierarchical, modular representations of both the intended structure and function of designed biological systems.
 
-\twotwozero{
 \begin{figure}[htbp]
 \centering
 \includegraphics[width=\textwidth]{images/standard-evolution.pdf}
 \caption{SBOL 2 extends prior sequence description formats to represent both the structure and function of a genetic design in a modular, hierarchical manner.}
 \label{f:sequence}
 \end{figure}
-}
+
 
 While the ultimate goal of SBOL is to describe synthetic biological designs such that they can be reproduced in the lab with a high degree of fidelity, SBOL 2 does not yet provide a complete catalog of the different classes of data that are necessary to achieve this goal. 
 For example, SBOL 2 does not yet include data on environmental and host context, or details on how the performance of a design is measured. 

sbmlpkgspec.cls

@@ -953,7 +953,7 @@ Package Specification Style]
 
 \newcommand{\notice}{\marginpar{\hspace*{34pt}\raisebox{-0.5ex}{\color{black}\Large\ding{43}}}}
 \newcommand{\version}[1]{\marginpar{\hspace*{34pt}\raisebox{-3.0ex}{\color{blue}\small #1}}}
-\newcommand{\warning}{\marginpar{\hspace*{34pt}{\color{red}\large\danger}}}
+%\newcommand{\warning}{\marginpar{\hspace*{34pt}{\color{red}\large\danger}}}
 
 % Margin notes.
 %