krlhBlupine/iBioSim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated tutorial for synthetic biology focus using Genetic Toggle Switch example.

Browse source
This commit is contained in:
cjmyers 2014-09-11 03:44:00 +00:00
parent 289d8c2142
commit e2ef7c770a
12 changed files with 2162 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/Makefile
View file

@ -6,7 +6,7 @@ DVI2PDF = dvipdf
DVIFLAGS = -t letter
PDFLATEX = pdflatex
all: iBioSim.html iBioSim_Tutorial.html iBioSim_Grid_Tutorial.html iBioSim_Install.html LEMA.html ATACS.html
all: iBioSim.html iBioSim_SynBio_Tutorial.html iBioSim_SysBio_Tutorial.html iBioSim_Grid_Tutorial.html iBioSim_Install.html LEMA.html ATACS.html
iBioSim.pdf: iBioSim.tex
$(PDFLATEX) iBioSim
@ -29,12 +29,19 @@ ATACS.pdf: ATACS.tex
ATACS.html: ATACS.pdf
tth -u -e2 -LATACS < ATACS.tex > ATACS.html
iBioSim_Tutorial.pdf: iBioSim_Tutorial.tex
$(PDFLATEX) iBioSim_Tutorial
$(PDFLATEX) iBioSim_Tutorial
iBioSim_SysBio_Tutorial.pdf: iBioSim_SysBio_Tutorial.tex
$(PDFLATEX) iBioSim_SysBio_Tutorial
$(PDFLATEX) iBioSim_SysBio_Tutorial
iBioSim_Tutorial.html: iBioSim_Tutorial.pdf
tth -u -e2 -LiBioSim_Tutorial < iBioSim_Tutorial.tex > iBioSim_Tutorial.html
iBioSim_SysBio_Tutorial.html: iBioSim_SysBio_Tutorial.pdf
tth -u -e2 -LiBioSim_SysBio_Tutorial < iBioSim_SysBio_Tutorial.tex > iBioSim_SysBio_Tutorial.html
iBioSim_SynBio_Tutorial.pdf: iBioSim_SynBio_Tutorial.tex
$(PDFLATEX) iBioSim_SynBio_Tutorial
$(PDFLATEX) iBioSim_SynBio_Tutorial
iBioSim_SynBio_Tutorial.html: iBioSim_SynBio_Tutorial.pdf
tth -u -e2 -LiBioSim_SynBio_Tutorial < iBioSim_SynBio_Tutorial.tex > iBioSim_SynBio_Tutorial.html
iBioSim_Grid_Tutorial.pdf: iBioSim_Grid_Tutorial.tex
$(PDFLATEX) iBioSim_Grid_Tutorial

63
docs/iBioSim.html
View file

@ -14,13 +14,13 @@
<title> iBioSim Version 2.5 \ User's Manual</title>
<title> iBioSim Version 3.0 \ User's Manual</title>
<h1 align="center">iBioSim Version 2.5 <br />User's Manual </h1>
<h1 align="center">iBioSim Version 3.0 <br />User's Manual </h1>
<div class="p"><!----></div>
<h3 align="center">Chris J. Myers, Nathan Barker, Kevin Jones, Hiroyuki Kuwahara, Curtis
<h3 align="center">Chris J. Myers, Nathan Barker, Scott Glass, Kevin Jones, Hiroyuki Kuwahara, Curtis
Madsen, <br />Nam Nguyen, Tyler Patterson, Nicholas Roehner, Jason Stevens, Leandro Watanabe </h3>
<div class="p"><!----></div>
@ -86,7 +86,7 @@
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc5.1"
>5.1&nbsp; Simulation Options</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc5.2"
>5.2&nbsp; Abstraction Options</a><br />
>5.2&nbsp; Advanced Options</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc5.3"
>5.3&nbsp; Schematic</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc5.4"
@ -116,11 +116,11 @@
1</a>&nbsp;&nbsp;Introduction</h2>
<div class="p"><!----></div>
<tt>iBioSim</tt> has been developed for the modeling, analysis, and design of genetic circuits. While <tt>iBioSim</tt> primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed. Recently, modeling and visualization support has been added for multi-cellular and spatial models as well.
<tt>iBioSim</tt> has been developed for the modeling, analysis, and design of genetic circuits. While <tt>iBioSim</tt> primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed. <tt>iBioSim</tt> also includes modeling and visualization support for multi-cellular and spatial models as well.
It is capable of importing and exporting models specified using the <A HREF="http://www.sbml.org/">
<em>Systems Biology Markup Language</em>
</A>
&nbsp;(SBML). It can import all levels and versions of SBML and is able to export Level 3 Version 1. It supports all core SBML modeling constructs except some types of <em>fast</em> reactions, and also has support for the hierarchical modeling package and layout package. It was the first tool to produce correct results for all examples in the SBML benchmark suite. It has also been tested successfully on the stochastic benchmark suite and the curated models in the
&nbsp;(SBML). It can import all levels and versions of SBML and is able to export Level 3 Version 1. It supports all core SBML modeling constructs except some types of <em>fast</em> reactions, and also has support for the hierarchical model composition, layout, flux balance constraints, and arrays packages. It was the first tool to produce correct results for all examples in the SBML benchmark suite. It has also been tested successfully on the stochastic benchmark suite and the curated models in the
<A HREF="http://www.ebi.ac.uk/biomodels-main/">
<em>BioModels database</em>.
</A>
@ -140,7 +140,7 @@ Finally, it is one of the first tools to also support the
<div class="p"><!----></div>
</li>
<li> Analysis Tool - an abstraction-based ODE, Monte Carlo, and Markov analysis tool.
<li> Analysis Tool - an abstraction-based ODE, Monte Carlo, Markov, and flux balance analysis tool.
<div class="p"><!----></div>
</li>
@ -152,7 +152,7 @@ Finally, it is one of the first tools to also support the
<div class="p"><!----></div>
</li>
<li> Histogram Graph Editor - a tool to visualize probability data.
<li> Histogram Graph Editor - a tool to visualize probability data and flux balance results.
<div class="p"><!----></div>
</li>
</ul>
@ -162,31 +162,15 @@ Finally, it is one of the first tools to also support the
<h3>Credits</h3>
<div class="p"><!----></div>
The iBioSim tool is being developed at the University of Utah
by
The iBioSim tool is being developed by
<A HREF="http://www.async.ece.utah.edu/~myers">
Chris Myers,
Chris Myers
</A>
<A HREF="http://www.cs.utah.edu/~barkern">
Nathan Barker,
</A>
<A HREF="http://www.async.ece.utah.edu/~kjones">
Kevin Jones,
</A>
<A HREF="http://www.cs.utah.edu/~kuwahara">
Hiroyuki Kuwahara,
</A>
<A HREF="http://www.async.ece.utah.edu/~cmadsen">
Curtis Madsen,
</A>
<A HREF="http://www.cs.utah.edu/~namphuon">
Nam Nguyen,
</A>
<A HREF="http://www.cs.utah.edu/~patterson">
Tyler Patterson,
</A>
Nicholas Roehner,
and Jason Stevens. Nathan Barker is now with Southern Utah University, Kevin Jones is now with Raytheon, Hiroyuki Kuwahara is now with King Abdullah University of Science and Technology, Nam Nguyen is now with the University of Texas in Austin, and Jason Stevens is now with the University of Washington.
research group at the University of Utah.
This project has involved many students including Nathan Barker, Scott Glass, Kevin Jones,
Hiroyuki Kuwahara, Curtis Madsen, Nam Nguyen, Tyler Patterson, Nicholas Roehner, and
Jason Stevens.
Nathan Barker is now with Southern Utah University, Kevin Jones is now with Raytheon, Hiroyuki Kuwahara is now with King Abdullah University of Science and Technology, Curtis Madsen is now with Newcastle University, Nam Nguyen is now with the University of Texas in Austin, and Jason Stevens is now with the University of Washington.
<div class="p"><!----></div>
<h2><a name="tth_sEc2">
@ -261,7 +245,7 @@ To create a new histogram, select New &#8594; Histogram from the File menu. You
<div class="p"><!----></div>
<center><img src="screenshots/Histogram.png" alt="screenshots/Histogram.png" />
<center><img src="screenshots/TopHistogram.png" alt="screenshots/TopHistogram.png" />
</center>
<div class="p"><!----></div>
@ -1561,9 +1545,11 @@ The next field specifies the simulation method you want to use based on the simu
<tr><td align="center">ODE </td><td align="center">rk4imp </td><td>Implicit 4th order Runge-Kutta at Gaussian points </td></tr>
<tr><td align="center">ODE </td><td align="center">rk8pd </td><td>Embedded Runge-Kutta Prince-Dormand (8,9) method </td></tr>
<tr><td align="center">ODE </td><td align="center">rkf45 </td><td>Embedded Runge-Kutta-Fehlberg (4, 5) method </td></tr>
<tr><td align="center">ODE </td><td align="center">rkf45 (java) </td><td>Native Java Runge-Kutta-Fehlberg method </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">gillespie </td><td>Gillespie's SSA-direct method </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">SSA-CR </td><td>SSA composition and rejection method </td></tr>
<tr><td align="center">ODE </td><td align="center">Runge-Kutta-Fehlberg </td><td>Runge-Kutta-Fehlberg method (java)</td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">gillespie </td><td>SSA-direct method </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">SSA-Hierarchical </td><td>SSA-direct method on hierarchical models (java) </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">SSA-Direct </td><td>SSA-direct method (java) </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">SSA-CR </td><td>SSA composition and rejection method (java) </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">iSSA </td><td>incremental SSA </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">interactive </td><td>Interactive SSA-direct method </td></tr>
<tr><td align="center">Monte Carlo </td><td align="center">emc-sim </td><td>Uses jump count as next reaction time </td></tr>
@ -1604,7 +1590,7 @@ The table below specifies these:
<div class="p"><!----></div>
<h3><a name="tth_sEc5.2">
5.2</a>&nbsp;&nbsp;<a name="absOptions">
</a>Abstraction Options</h3>
</a>Advanced Options</h3>
<div class="p"><!----></div>
Abstraction is performed in three steps. There is a preprocess step, which is a sequence of abstractions performed once on the initial model. The main loop iterates through a group of abstractions until there is no change in the model. Finally, there is a postprocess step, which is a sequence of abstractions performed once at the end. Clicking on the Add button brings up a list of all the possible abstraction methods. The selected abstraction method is added after the highlighted abstraction method in the list. If no method is highlighted, it makes it the first abstraction in the list.
@ -1978,6 +1964,7 @@ After selecting a data set, one can select individual variables (typically speci
<div class="p"><!----></div>
</li>
</ul>
If multiple data files are selected in the data selection menu on the left when the use check box is selected for a variable, then that variable will be checked for all highlighted data files.
Note that a checkmark appears on a data set to indicate that some species have been selected in that data set. Also, all species can be deselected by pressing the Deselect All button.
<div class="p"><!----></div>
@ -2192,7 +2179,7 @@ Math formulas appear in many model constructs. These formulas are expressed as
<div class="p"><!----></div>
</li>
<li> Mathematical operators including add (+), subtract (-), multiply (*), divide (/), and power (pow(x,y)).
<li> Mathematical operators including add (+), subtract (-), multiply (*), divide (/), power (^ or pow(x,y)), and root.
<div class="p"><!----></div>
</li>
@ -2351,5 +2338,5 @@ mail will be filtered by our spam filters.
T<sub><font size="-1">E</font></sub>X
by <a href="http://hutchinson.belmont.ma.us/tth/">
T<sub><font size="-1">T</font></sub>H</a>,
version 3.81.<br />On 16 Aug 2013, 16:06.</small>
version 3.81.<br />On 1 Jun 2014, 11:11.</small>
</html>

BIN
docs/iBioSim.pdf
View file

Binary file not shown.

44
docs/iBioSim.tex
View file

@ -7,9 +7,9 @@
\usepackage{indentfirst,graphics,alltt,epsfig,color}
\title{iBioSim Version 2.5 \\ User's Manual}
\title{iBioSim Version 3.0 \\ User's Manual}
\author{Chris J. Myers, Nathan Barker, Kevin Jones, Hiroyuki Kuwahara, Curtis
\author{Chris J. Myers, Nathan Barker, Scott Glass, Kevin Jones, Hiroyuki Kuwahara, Curtis
Madsen, \\ Nam Nguyen, Tyler Patterson, Nicholas Roehner, Jason Stevens, Leandro Watanabe}
\begin{document}
@ -26,11 +26,11 @@
\section{Introduction}
\noindent
{\tt iBioSim} has been developed for the modeling, analysis, and design of genetic circuits. While {\tt iBioSim} primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed. Recently, modeling and visualization support has been added for multi-cellular and spatial models as well.
{\tt iBioSim} has been developed for the modeling, analysis, and design of genetic circuits. While {\tt iBioSim} primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed. {\tt iBioSim} also includes modeling and visualization support for multi-cellular and spatial models as well.
It is capable of importing and exporting models specified using the %%tth:\begin{html}<A HREF="http://www.sbml.org/">\end{html}
\emph{Systems Biology Markup Language}
%%tth:\begin{html}</A>\end{html}
~(SBML). It can import all levels and versions of SBML and is able to export Level 3 Version 1. It supports all core SBML modeling constructs except some types of \emph{fast} reactions, and also has support for the hierarchical modeling package and layout package. It was the first tool to produce correct results for all examples in the SBML benchmark suite. It has also been tested successfully on the stochastic benchmark suite and the curated models in the
~(SBML). It can import all levels and versions of SBML and is able to export Level 3 Version 1. It supports all core SBML modeling constructs except some types of \emph{fast} reactions, and also has support for the hierarchical model composition, layout, flux balance constraints, and arrays packages. It was the first tool to produce correct results for all examples in the SBML benchmark suite. It has also been tested successfully on the stochastic benchmark suite and the curated models in the
%%tth:\begin{html}<A HREF="http://www.ebi.ac.uk/biomodels-main/">\end{html}
\emph{BioModels database}.
%%tth:\begin{html}</A>\end{html}
@ -43,40 +43,24 @@ Finally, it is one of the first tools to also support the
\begin{itemize}
\item Model Editor - a tool to create a model of a genetic circuit or other biological system.
\item SBOL Browser - a tool to view SBOL files and associate DNA components to model elements.
\item Analysis Tool - an abstraction-based ODE, Monte Carlo, and Markov analysis tool.
\item Analysis Tool - an abstraction-based ODE, Monte Carlo, Markov, and flux balance analysis tool.
\item Learn Tool - a tool to learn a model from \emph{time series data} (TSD).
\item TSD Graph Editor- a tool to visualize TSD files.
\item Histogram Graph Editor - a tool to visualize probability data.
\item Histogram Graph Editor - a tool to visualize probability data and flux balance results.
\end{itemize}
\subsection*{Credits}
\noindent
The iBioSim tool is being developed at the University of Utah
by
The iBioSim tool is being developed by
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/~myers">\end{html}
Chris Myers,
Chris Myers
%%tth:\begin{html}</A>\end{html}
%%tth:\begin{html}<A HREF="http://www.cs.utah.edu/~barkern">\end{html}
Nathan Barker,
%%tth:\begin{html}</A>\end{html}
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/~kjones">\end{html}
Kevin Jones,
%%tth:\begin{html}</A>\end{html}
%%tth:\begin{html}<A HREF="http://www.cs.utah.edu/~kuwahara">\end{html}
Hiroyuki Kuwahara,
%%tth:\begin{html}</A>\end{html}
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/~cmadsen">\end{html}
Curtis Madsen,
%%tth:\begin{html}</A>\end{html}
%%tth:\begin{html}<A HREF="http://www.cs.utah.edu/~namphuon">\end{html}
Nam Nguyen,
%%tth:\begin{html}</A>\end{html}
%%tth:\begin{html}<A HREF="http://www.cs.utah.edu/~patterson">\end{html}
Tyler Patterson,
%%tth:\begin{html}</A>\end{html}
Nicholas Roehner,
and Jason Stevens. Nathan Barker is now with Southern Utah University, Kevin Jones is now with Raytheon, Hiroyuki Kuwahara is now with King Abdullah University of Science and Technology, Nam Nguyen is now with the University of Texas in Austin, and Jason Stevens is now with the University of Washington.
research group at the University of Utah.
This project has involved many students including Nathan Barker, Scott Glass, Kevin Jones,
Hiroyuki Kuwahara, Curtis Madsen, Nam Nguyen, Tyler Patterson, Nicholas Roehner, and
Jason Stevens.
Nathan Barker is now with Southern Utah University, Kevin Jones is now with Raytheon, Hiroyuki Kuwahara is now with King Abdullah University of Science and Technology, Curtis Madsen is now with Newcastle University, Nam Nguyen is now with the University of Texas in Austin, and Jason Stevens is now with the University of Washington.
\clearpage
@ -1322,7 +1306,7 @@ Math formulas appear in many model constructs. These formulas are expressed as
\item Real numbers followed optionally by its units
\item Built-in constants: exponential, pi, Infinity, NaN, true, and false.
\item Special variable time or t, which returns the current simulation time.
\item Mathematical operators including add (+), subtract (-), multiply (*), divide (/), and power (pow(x,y)).
\item Mathematical operators including add (+), subtract (-), multiply (*), divide (/), power (\^{} or pow(x,y)), and root.
\item A function defined in the list of function definitions.
\item Logical functions: and (\&\&), or ($||$), xor, not (!).
\item Relational functions: eq (==), neq (!=), geq (>=), gt (>), leq (<=), and lt (<).

526
docs/iBioSim_SynBio_Tutorial.html Normal file
View file

@ -0,0 +1,526 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<meta name="GENERATOR" content="TtH 3.81">
<style type="text/css"> div.p { margin-top: 7pt;}</style>
<style type="text/css"><!--
td div.comp { margin-top: -0.6ex; margin-bottom: -1ex;}
td div.comb { margin-top: -0.6ex; margin-bottom: -.6ex;}
td div.hrcomp { line-height: 0.9; margin-top: -0.8ex; margin-bottom: -1ex;}
td div.norm {line-height:normal;}
span.roman {font-family: serif; font-style: normal; font-weight: normal;}
span.overacc2 {position: relative; left: .8em; top: -1.2ex;}
span.overacc1 {position: relative; left: .6em; top: -1.2ex;} --></style>
<title> iBioSim Version 2.7 \ Tutorial</title>
<h1 align="center">iBioSim Version 2.7 <br />Tutorial </h1>
<div class="p"><!----></div>
<h3 align="center">Chris J. Myers </h3>
<div class="p"><!----></div>
<div class="p"><!----></div>
<h1>Contents </h1><a href="#tth_sEc1"
>1&nbsp; Introduction</a><br />
<a href="#tth_sEc2"
>2&nbsp; Project Management</a><br />
<a href="#tth_sEc3"
>3&nbsp; Importing Models</a><br />
<a href="#tth_sEc4"
>4&nbsp; Model Editor</a><br />
<a href="#tth_sEc5"
>5&nbsp; SBOL Browser</a><br />
<a href="#tth_sEc6"
>6&nbsp; Analysis Tool</a><br />
<a href="#tth_sEc7"
>7&nbsp; Grid Models</a><br />
<div class="p"><!----></div>
<h2><a name="tth_sEc1">
1</a>&nbsp;&nbsp;Introduction</h2>
<div class="p"><!----></div>
<tt>iBioSim</tt> has been developed for the modeling, analysis, and design of genetic circuits. While <tt>iBioSim</tt> primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed.
<tt>iBioSim</tt> makes extensive use of standard data representations. Models are specified in <tt>iBioSim</tt> in the <A HREF="http://www.sbml.org/">
<em>Systems Biology Markup Language</em>
</A>
&nbsp;(SBML). It can import all levels and versions of SBML and is able to export Level 3 Version 1. It supports all core SBML modeling constructs except some types of <em>fast</em> reactions, and also has support for the hierarchical model composition, layout, flux balance constraints, and arrays packages. It was the first tool to produce correct results for all examples in the SBML benchmark suite. It has also been tested successfully on the stochastic benchmark suite and the curated models in the
<A HREF="http://www.ebi.ac.uk/biomodels-main/">
<em>BioModels database</em>.
</A>
<tt>iBioSim</tt> can also import
<A HREF="http://sed-ml.org/">
<em>SED-ML</em> files
</A>
that describe simulation experiments. Finally, it is one of the first tools to also support the
<A HREF="http://www.sbolstandard.org/">
<em>Synthetic Biology Open Language</em>
</A>
&nbsp;(SBOL), an emerging standard for information exchange in synthetic biology.
<div class="p"><!----></div>
<tt>iBioSim</tt> includes the following components:
<div class="p"><!----></div>
<ul>
<li> Model Editor - a tool to create a model of a genetic circuit or other biological system.
<div class="p"><!----></div>
</li>
<li> SBOL Browser - a tool to view SBOL files and associate DNA components to model elements.
<div class="p"><!----></div>
</li>
<li> Analysis Tool - an abstraction-based ODE, Monte Carlo, and Markov analysis tool.
<div class="p"><!----></div>
</li>
<li> Learn Tool - a tool to learn a model from <em>time series data</em> (TSD).
<div class="p"><!----></div>
</li>
<li> TSD Graph Editor- a tool to visualize TSD files.
<div class="p"><!----></div>
</li>
<li> Histogram Graph Editor - a tool to visualize probability data.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
This tutorial illustrates the first three of these features of <tt>iBioSim</tt> using a model of the Genetic Toggle Switch (Gardner et al., 2000).
<div class="p"><!----></div>
<h2><a name="tth_sEc2">
2</a>&nbsp;&nbsp;Project Management</h2>
<div class="p"><!----></div>
Within <tt>iBioSim</tt>, all files are collected within projects. A project is a collection of models, analysis views, learn views, and graphs. As shown below, <tt>iBioSim</tt> displays all project files on the left, the open models, views, and graphs on the right, and a log of all external commands on the bottom. The menu bar is located on the top of the window in the Windows and Linux versions. It is located on the top of the screen in the MacOS version.
<div class="p"><!----></div>
<center><img src="screenshots/iBioSim.png" alt="screenshots/iBioSim.png" />
</center>
<div class="p"><!----></div>
To create a new project, select New &#8594; Project from the File menu as shown below. You will then be prompted to browse to a desired location and to give a name to the project directory. Enter the name <tt>SynBioTutorial</tt>. After you do this, click the new button and a new project directory will be created.
<div class="p"><!----></div>
<center><img src="screenshots/project.png" alt="screenshots/project.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc3">
3</a>&nbsp;&nbsp;Importing Models</h2>
<div class="p"><!----></div>
In order to do analysis within <tt>iBioSim</tt>, you must first have models to analyze. The simplest way to obtain a model to analyze is to import it from an external source. As shown below, using the menu option File &#8594; Import, <tt>iBioSim</tt> can import models in a variety of ways. First, one can simply import an SBML model from somewhere on the local file system.
<div class="p"><!----></div>
<center><img src="screenshots/import.png" alt="screenshots/import.png" />
</center>
<div class="p"><!----></div>
One can also import an SBML model from the EMBL-EBI's BioModels Repository by selecting the menu option File &#8594; Import &#8594; BioModel. This brings up the window shown below without the model names. Pressing the Get Names button will fetch the names, but this takes awhile the first time, so let's skip that for now. Instead, scroll down to BIOMD0000000507 and Press the Get Description button which brings up the BioModels entry for this model in a browser, which you can see is the original model of the genetic toggle switch. The Get Reference button brings up a browser entry for the original publication. With BIOMD0000000507 highlighted, press OK to fetch this SBML model. Since this model does not include any layout information, you will need to either lay it out by hand or use one of the default layout routines selectable using the Apply Layout icon <img src="../gui/icons/modelview/choose_layout_selected.png" alt="../gui/icons/modelview/choose_layout_selected.png" />. Horizontal Hierarchical layout works well for this model. Click on the "X" to close the window.
<div class="p"><!----></div>
<center><img src="screenshots/BioModels.png" alt="screenshots/BioModels.png" />
</center>
<div class="p"><!----></div>
Another source for import of SBML models is from Newcastle University's Virtual Parts Repository. In this case, you can either import a model of the part or of the part's interactions.
<div class="p"><!----></div>
<center><img src="screenshots/VirtualParts.png" alt="screenshots/VirtualParts.png" />
</center>
<div class="p"><!----></div>
Next, you can import a <em>labeled Petri net</em> (LPN) model. Petri net models are a type of discrete modeling formalism similar to a state machine though with more support for the modeling of concurrent systems. LPNs extend Petri nets with labels that indicate when state transitions are enabled, the time they take, and how they update the system state. <tt>iBioSim</tt> uses the LPN format for Markov chain analysis of biological systems.
<div class="p"><!----></div>
We can also import an SBOL file that provides annotated DNA sequences for DNA components. More on this later.
<div class="p"><!----></div>
Finally, we can import a SED-ML file that describes a simulation experiment.
Importing a SED-ML file will also import the SBML models required for the simulation followed by performing the simulation. To see how this works, select File &#8594; Import &#8594; SED-ML File, and browse to the install directory for <tt>iBioSim</tt>. Continue browsing from here to the directory:<br />
<tt>&lt;INSTALL DIRECTORY&#62;/docs/SynBioTutorial/SBMLTestSuite</tt> <br />
which contains the SBML testsuite files. Go to test 00001, and select the file:<br />
<tt>00001-sbml-l3v1-sedml.xml</tt>. This will import an SBML model called <tt>case00001.xml</tt> and simulate it. Click on the tab labelled TSD Graph to see the result of an ODE simulation of this model. Repeat these steps to import a SED-ML file for test case 01195. This SBML model is a <em>flux balance</em> model, so the analysis performed is flux balance analysis. To see the results, click on the Histogram tab. Now, click on the "X" to close each window.
<div class="p"><!----></div>
<center><img src="screenshots/TestSuiteResults.png" alt="screenshots/TestSuiteResults.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/FBAresults.png" alt="screenshots/FBAresults.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc4">
4</a>&nbsp;&nbsp;Model Editor</h2>
<div class="p"><!----></div>
Let us know see how to create a new model using the Model Editor. First, select New &#8594; Model from the File menu as shown below. You will then be prompted to enter a model ID. Enter <tt>LacI_Inverter</tt>. At this point, a Model editor will open in a new tab.
<div class="p"><!----></div>
<center><img src="screenshots/newModel.png" alt="screenshots/newModel.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/ModelIdGT.png" alt="screenshots/ModelIdGT.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/schematicGT.png" alt="screenshots/schematicGT.png" />
</center>
<div class="p"><!----></div>
To add a chemical species, select the Add Species icon <img src="../gui/icons/modelview/add_species_selected.png" alt="../gui/icons/modelview/add_species_selected.png" /> and click on the schematic canvas. This will drop a new species with default ID and other values. You may change these defaults by clicking on the selection icon
<img src="../gui/icons/modelview/select_mode_selected.png" alt="../gui/icons/modelview/select_mode_selected.png" />, and
double-clicking on the species to open the Species Editor. In this case, let us change the ID to LacI and change the Port type to <em>input</em>. We will leave all the other values at their default values. The port type of input indicates that this species will be used as an input for the LacI inverter.
Note that while in the select mode, you can also select an object in the schematic and move it by moving the mouse while holding the left mouse button. Pressing the right mouse button while an object is selected brings up a menu that allows you to delete an object from the schematic. Repeat the steps above to add TetR and GFP species. Give these species port type of <em>output</em>.
<div class="p"><!----></div>
<center><img src="screenshots/speciesGT.png" alt="screenshots/speciesGT.png" />
</center>
<div class="p"><!----></div>
<div class="p"><!----></div>
<div class="p"><!----></div>
<div class="p"><!----></div>
<div class="p"><!----></div>
Next, let's add the pLac promoter, which initiates transcription of the gene that produces the proteins TetR and GFP. To do this, select the promoter icon <img src="../gui/icons/modelview/promoter_mode_selected.png" alt="../gui/icons/modelview/promoter_mode_selected.png" /> and click on the schematic canvas to drop the promoter with a default ID and parameter values. Double-click on the promoter to bring up the promoter editor. Change the ID to pLac.
<div class="p"><!----></div>
<center><img src="screenshots/promoterGT.png" alt="screenshots/promoterGT.png" />
</center>
<div class="p"><!----></div>
The pLac promoter is repressed by the LacI species. To create this relationship, select the repression arc icon
<img src="../gui/icons/modelview/inhibition_selected.png" alt="../gui/icons/modelview/inhibition_selected.png" />, highlight the LacI species, and, while holding the mouse button, stretch the repression arc to the pLac promoter.
<div class="p"><!----></div>
<center><img src="screenshots/repressionGT.png" alt="screenshots/repressionGT.png" />
</center>
<div class="p"><!----></div>
As mentioned earlier, the pLac promoter initiates the production of the TetR and GFP species. Highlight the pLac promoter and, while holding the mouse button, stretch the production arc to the TetR species. Repeat these steps to create a production arc between the pLac promoter and GFP species. Note that the icons selected for this are not important because all arcs from promoters to species are always production arcs.
<div class="p"><!----></div>
<center><img src="screenshots/productionGT.png" alt="screenshots/productionGT.png" />
</center>
<div class="p"><!----></div>
Let us now annotate the LacI inverter with its DNA sequence. To do this, we will need to first import some annotated sequence data stored using the <em>synthetic biology open language</em> (SBOL). Select the File &#8594; Import &#8594; SBOL File menu option as shown below. This will bring up a file browser. You will need to find the location where <tt>iBioSim</tt> is installed, and the file you want to import should be located in <tt>iBioSim/docs/SynBioTutorial/SBOL/GeneticToggle.sbol</tt>.
<div class="p"><!----></div>
<center><img src="screenshots/importSBOL.png" alt="screenshots/importSBOL.png" />
</center>
<div class="p"><!----></div>
Next, click on the Model button in the schematic editor which brings up the Model editor shown below.
<div class="p"><!----></div>
<center><img src="screenshots/ModelEditorGT.png" alt="screenshots/ModelEditorGT.png" />
</center>
<div class="p"><!----></div>
Next, click on the Associate SBOL button, highlight the placeholder for the DNA component, and click the Remove button. Then, press the Add button which will open the SBOL browser shown below. In the list of DNA components, scroll down to the component named pIKERightCassette_1, select it, and press OK.
<div class="p"><!----></div>
<center><img src="screenshots/SBOLBrowserGT.png" alt="screenshots/SBOLBrowserGT.png" />
</center>
<div class="p"><!----></div>
The SBOL association editor should now show this DNA component as being associated with this model. We could now add more components, if we wish, but only one is needed for this, so press Ok. We are now done with the LacI inverter model, so let's make sure the model is saved by either clicking on the Save icon <img src="../gui/icons/save.png" alt="../gui/icons/save.png" /> or selecting the Save option from the File menu.
<div class="p"><!----></div>
<center><img src="screenshots/SBOLAssociationGT.png" alt="screenshots/SBOLAssociationGT.png" />
</center>
<div class="p"><!----></div>
Next, repeat the steps above to create a TetR_Inverter model. The TetR inverter has input TetR and output LacI. In the TetR inverter, TetR represses the production of LacI. To indicate this, select the repression icon <img src="../gui/icons/modelview/inhibition_selected.png" alt="../gui/icons/modelview/inhibition_selected.png" />, highlight the TetR species and stretch the arc to the LacI species. This action creates an implicit promoter P0 that is repressed by TetR and initiates production of LacI. When you associate SBOL with this model, select the pIKELeftCassette_1 component, and select for it to be put on the Minus Strand by checking the box on the SBOL association window. Do not forget to save this model either by clicking on the Save icon <img src="../gui/icons/save.png" alt="../gui/icons/save.png" /> or selecting the Save option from the File menu.
<div class="p"><!----></div>
<center><img src="screenshots/implicitPromoterGT.png" alt="screenshots/implicitPromoterGT.png" />
</center>
<div class="p"><!----></div>
Now, let us put these genetic inverters into a new model called GeneticToggle.
This model will be the top-level model, and all elements of this model will be enclosed in this model's <em>compartment</em>. Compartments are the membrane-enclosed regions where species can be found and reactions take place. <tt>iBioSim</tt> creates a default compartment initially with the ID of Cell. If you click on the schematic within the Cell compartment, it brings up the compartment editor. Uncheck the "Is Mapped to a Port". This indicates that this compartment should be enclosing this model and not replaced when instantiated in a larger model. Once you press OK, you will notice that the compartment now has rounded corners to indicate that this is membrane enclosed by the compartment Cell.
<div class="p"><!----></div>
<center><img src="screenshots/compartmentGT.png" alt="screenshots/compartmentGT.png" />
</center>
<div class="p"><!----></div>
Now, lets add the LacI_Inverter component to this model. Select the Add Component icon <img src="../gui/icons/modelview/add_component_selected.png" alt="../gui/icons/modelview/add_component_selected.png" /> and click on the Schematic canvas opening the Add Component(s) window. In this window, browse the combo box, if necessary, to find your LacI_Inverter model. Pressing OK will then add it to your schematic. Repeat these steps to add the TetR_Inverter.
<div class="p"><!----></div>
<center><img src="screenshots/subModelGT.png" alt="screenshots/subModelGT.png" />
</center>
<div class="p"><!----></div>
The next step is to connect the components through their species. To do this, add species to the model for LacI, TetR, and GFP. Mark that each of these species degrades, and set the initial amount of LacI to 60. The degrades checkbox means that when this model is analyzed a default degradation reaction will be created which has a rate of 0.0075. Next, highlight the LacI species and stretch a connection to the LacI_Inverter connecting it to its LacI input port. Next, highlight the LacI_Inverter and stretch to the TetR species. In this case, since there are two output ports, you must select the TetR output port is the one desired. Next, highlight the TetR species and stretch to the TetR_Inverter to connect to the TetR input port. Next, highlight the TetR_Inverter and stretch to the LacI species to connect it to its LacI output port. Finally, highlight the Lac_Inverter and stretch to the GFP species being sure to select to connect to its GFP output port.
<div class="p"><!----></div>
<center><img src="screenshots/addConnectionGT.png" alt="screenshots/addConnectionGT.png" />
</center>
<div class="p"><!----></div>
By instantiating these models together, the SBOL associated with each component will now be composed as well. To add some description for this composite DNA component, click on the Model button, followed by the Associate SBOL button on the Model Editor, and finally the Edit Composite button on the SBOL Association window. You can now add an ID, Name, and Description for this composite DNA component as shown below.
<div class="p"><!----></div>
<center><img src="screenshots/compSBOLDesc.png" alt="screenshots/compSBOLDesc.png" />
</center>
<div class="p"><!----></div>
Next let us add the complex formation reactions that sequester LacI and TetR preventing them from acting as repressors. First, add the small molecule species IPTG and aTc. Select <em>boundary condition</em> to indicate they are replenished inputs to the system. Next, add the complex species IPTG_LacI and aTc_TetR and mark that they degrade. Now, select the complex formation icon <img src="../gui/icons/modelview/bio_activation_selected.png" alt="../gui/icons/modelview/bio_activation_selected.png" />, highlight the IPTG species, and, while holding the mouse button, stretch the complex formation arc to the IPTG_LacI species. Repeat this step to connect complex formation arcs between LacI and this complex, as well as from aTc and TetR to the aTc_TetR complex. Finally, click on the selection icon
<img src="../gui/icons/modelview/select_mode_selected.png" alt="../gui/icons/modelview/select_mode_selected.png" />, and
double-click on each complex formation to open the Influence Editor. In this editor, change the Stoichiometry of binding (nc) from 2 to 1 by first changing "default" to "custom" then editing the value.
<div class="p"><!----></div>
<center><img src="screenshots/complexGT.png" alt="screenshots/complexGT.png" />
</center>
<div class="p"><!----></div>
The final step in the model creation is to add some discrete events to change the amounts of IPTG and aTc, so we may see the genetic toggle switch change state during simulation. First, select the event icon <img src="../gui/icons/modelview/event_mode_selected.png" alt="../gui/icons/modelview/event_mode_selected.png" />, and click on the schematic to add an event. This action opens the event editor. In this editor, create an event with ID "IPTG_High", a trigger of "true", and a delay of 2000. Next, click on Add Assignment to bring up the Event Assignment Editor. In this editor, select the variable IPTG and provide the assignment of 60. Press the Add button to add the assignment and the Add button to add the event. This event will cause the amount of IPTG to change to 60 molecules after 2000 seconds of simulation time. Repeat these steps to create an "IPTG_Low" event with a delay of 4000 which assigns 0 to IPTG, an "aTc_High" event with a delay of 6000 which assigns 60 to aTc, and finally an "aTc_Low" event with a delay of 8000 which assigns 0 to aTc.
<div class="p"><!----></div>
<center><img src="screenshots/eventGT.png" alt="screenshots/eventGT.png" />
</center>
<div class="p"><!----></div>
You should now have a complete model of the genetic toggle switch that looks like the one below (though locations of elements may be different). Make sure the model is saved by either clicking on the Save icon <img src="../gui/icons/save.png" alt="../gui/icons/save.png" /> or selecting the Save option from the File menu.
<div class="p"><!----></div>
<center><img src="screenshots/saveGT.png" alt="screenshots/saveGT.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc5">
5</a>&nbsp;&nbsp;SBOL Browser</h2>
<div class="p"><!----></div>
As mentioned above, a composite DNA component has been constructed for the entire genetic toggle switch. To see this component, click on the GeneticToggle.sbol file in the list of project files to open the SBOL browser. On the right side, scroll down and select the DNA component that you named MyGeneticToggle. You will now see the complete annotated DNA sequence for this component. Note how the pIKELeftCassette_1 has been put on the minus strand while the pIKERightCassette_1 follows it on the positive strand.
<div class="p"><!----></div>
<center><img src="screenshots/SBOLBrowserGT2.png" alt="screenshots/SBOLBrowserGT2.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc6">
6</a>&nbsp;&nbsp;Analysis Tool</h2>
<div class="p"><!----></div>
This section describes how to analyze the model just created. The first step is to create an analysis view. To do this, right-click on the model file and select Create Analysis View. Enter the analysis ID <tt>GeneticToggle</tt> or just press enter. At this point, a new analysis view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
<div class="p"><!----></div>
<center><img src="screenshots/createAnalysisViewGT.png" alt="screenshots/createAnalysisViewGT.png" /><br />
<img src="screenshots/analysisViewGT.png" alt="screenshots/analysisViewGT.png" />
</center>
<div class="p"><!----></div>
In order to perform analysis, the analysis tool first converts the model into a detailed reaction-based model. There are three different ways to see the reaction-based model that is produced. If GraphViz is installed on your computer, you can select Network for your Simulation Type. Then, either press the Save and Run icon <img src="../gui/icons/run-icon.jpg" alt="../gui/icons/run-icon.jpg" /> or select the Save and Run option from the File menu. The result will be a GraphViz window that will open to show the reaction-based model such as the one shown below for our example. If it does not open in GraphViz, make sure that you have files with the <tt>.dot</tt> file extension associated with GraphViz on your computer. You can also view the model in a web browser by selecting Browser for your simulation type. In this case, you should ensure that you have files with the <tt>.xhtml</tt> extension associated with your favorite browser. Finally, you can save the reaction-based model by selecting Model as your simulation type. In this case, you must provide a new model ID. This new model will appear in your project and it can be opened in the Model Editor. Since this model does not include any layout information, you will need to either lay it out by hand or using one of the default layout routines selectable using the Apply Layout icon <img src="../gui/icons/modelview/choose_layout_selected.png" alt="../gui/icons/modelview/choose_layout_selected.png" />.
<div class="p"><!----></div>
<center><img src="screenshots/viewNetworkGT.png" alt="screenshots/viewNetworkGT.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/viewBrowserGT.png" alt="screenshots/viewBrowserGT.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/reactionModelGT.png" alt="screenshots/reactionModelGT.png" />
</center>
<div class="p"><!----></div>
As you can see, this model is quite complex. A simple model can be generated by selecting Abstraction to reduce the model using reaction-based abstractions based on the quasi-steady state assumption. The abstracted model shown below is reduced from 15 species and 13 reactions to just 5 species and 5 reactions.
<div class="p"><!----></div>
<center><img src="screenshots/reactionModelAbsGT.png" alt="screenshots/reactionModelAbsGT.png" />
</center>
<div class="p"><!----></div>
Now, go back to the simulation options tab. Here, make sure that Abstraction is still selected, change the simulation type back to ODE, the simulator to Runge-Kutta-Fehlberg, the time limit to 10000.0, the print interval to 100.0, and enter a Simulation ID of <tt>ode</tt>. Then, either press the Save and Run icon <img src="../gui/icons/run-icon.jpg" alt="../gui/icons/run-icon.jpg" /> or select the Save and Run option from the File menu.
After the simulation completes, click on the TSD Graph tab. Double-click on the graph to bring up the graph editor.
Open the <tt>ode</tt> simulation, highlight Average, select aTc, IPTG, and GFP, change the Title to "ODE Simulation Results", change the X-Axis Label to "Time (seconds)", and change the Y-Axis Label to "Number of Molecules".
Press the OK button.
<div class="p"><!----></div>
<center><img src="screenshots/odeSimGT.png" alt="screenshots/odeSimGT.png" /><br />
<img src="screenshots/odeResultsGT.png" alt="screenshots/odeResultsGT.png" /><br />
<img src="screenshots/odeSimResultsGT.png" alt="screenshots/odeSimResultsGT.png" />
</center>
<div class="p"><!----></div>
Graphs can be exported in a variety of formats including:
<ul>
<li> Time series data format (tsd).
<div class="p"><!----></div>
</li>
<li> Comma separated value (csv).
<div class="p"><!----></div>
</li>
<li> Column separated data (dat).
<div class="p"><!----></div>
</li>
<li> Encapsulated postscript (eps).
<div class="p"><!----></div>
</li>
<li> Joint Photographic Experts Group (jpg).
<div class="p"><!----></div>
</li>
<li> Portable document format (pdf).
<div class="p"><!----></div>
</li>
<li> Portable network graphics (png).
<div class="p"><!----></div>
</li>
<li> Scalable vector graphics (svg).
<div class="p"><!----></div>
</li>
</ul>
In order to export a graph, you can either click on the Export icon <img src="../gui/icons/export.jpg" alt="../gui/icons/export.jpg" /> or select one of the graph export options from the File menu. When using the Export icon, the type of file exported will depend on the extension provided to the file name. Click on the Export icon, browse to a location on your file system, and enter the file name of <tt>ode.pdf</tt> to create a PDF file for your graph.
<div class="p"><!----></div>
<center><img src="screenshots/exportTSD.png" alt="screenshots/exportTSD.png" />
</center>
<div class="p"><!----></div>
Now, select the Simulation Options tab again, select <tt>Monte Carlo</tt>, change the simulator SSA-Direct, the number of runs to 100, set the simulation ID to <tt>ssa</tt>, and click on the Save and Run icon. Click on the TSD Graph tab. Double-click on the graph to bring up the graph editor. Click on Deselect All to remove the plotted points. Open the <tt>ssa</tt> simulation directory, and highlight <tt>run-1</tt>. Select aTc, IPTG, and GFP, and change the title to "SSA Simulation Results". Press the OK button. Click on the Export icon and enter the file name <tt>ssa-1.pdf</tt>. Repeat these steps to generate graphs for the average (<tt>average.pdf</tt>).
<div class="p"><!----></div>
<center><img src="screenshots/ssaSimGT.png" alt="screenshots/ssaSimGT.png" /><br />
<img src="screenshots/ssaResultsGT.png" alt="screenshots/ssaResultsGT.png" /><br />
<img src="screenshots/ssaSimResultsGT.png" alt="screenshots/ssaSimResultsGT.png" />
</center>
<div class="p"><!----></div>
Another way to view simulation results is on the schematic. To do this, click on the schematic tab. At the bottom of the window, select the Choose Simulation button, which brings up a window with all the simulations in this analysis view. Open the <tt>ssa</tt> directory, select <tt>run-1.tsd</tt>, and press OK.
<div class="p"><!----></div>
<center><img src="screenshots/chooseSimGT.png" alt="screenshots/chooseSimGT.png" />
</center>
<div class="p"><!----></div>
Now, click on the GFP species, which brings up the Edit Species window. Select the Appearance tab. Here you can select how you want the species to appear as you playback the simulation. You can have it change color, size, and/or opacity on a gradient. You can also select the range of molecule counts to specify the ends of the gradient(s). Finally, you can indicate that these selections are either for this species or all species in the model. For our example, let's make GFP follow a green color gradient, IPTG follow a blue color gradient, LacI follow a cyan color gradient, aTc follow a red color gradient, and TetR follow a magenta gradient.
<center>
<img src="screenshots/editSpeciesAppearanceGT.png" alt="screenshots/editSpeciesAppearanceGT.png" />
</center>
<div class="p"><!----></div>
Once you have made your selections, you can now play back the simulation. You can either single-step the simulation by pressing the <img src="../gui/icons/modelview/movie/single_step.png" alt="../gui/icons/modelview/movie/single_step.png" /> icon or play continuously by pressing the <img src="../gui/icons/modelview/movie/play.png" alt="../gui/icons/modelview/movie/play.png" /> icon. The playback can also be paused by pressing the <img src="../gui/icons/modelview/movie/pause.png" alt="../gui/icons/modelview/movie/pause.png" /> icon and restarted by pressing the <img src="../gui/icons/modelview/movie/rewind.png" alt="../gui/icons/modelview/movie/rewind.png" /> icon.
<div class="p"><!----></div>
<center><img src="screenshots/movieViewGT.png" alt="screenshots/movieViewGT.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc7">
7</a>&nbsp;&nbsp;Grid Models</h2>
<div class="p"><!----></div>
In the last example, we will build a model with a grid.
Create a grid model using the File &#8594; New &#8594; Grid Model menu, and name the new model <tt>Population</tt>. In the create grid window shown below, select your copy of your GeneticToggle model and change the number of rows and columns to 5.
<div class="p"><!----></div>
<center><img src="screenshots/createGridGT.png" alt="screenshots/createGridGT.png" />
</center>
<div class="p"><!----></div>
The schematic in a grid model is a bit different. It includes a grid in which each location can be empty or contain exactly one component. Only components can be added to grids.
<div class="p"><!----></div>
<center><img src="screenshots/gridModelGT.png" alt="screenshots/gridModelGT.png" />
</center>
<div class="p"><!----></div>
Next, right-click on the Population model and create an analysis view. Select Abstraction, Monte Carlo, and the SSA-Direct simulator. Set the time limit to 10000 with a print interval of 100, and perform the simulation. Now, go to the schematic tab and press the Choose Simulation button to select run-1.tsd. Click on one of the genetic toggle switch models to bring up the Edit Species editor. Select the GFP species and a green color gradient, and apply to all components with this model. Now, play back the simulation to see the toggle switches turn on and off.
<div class="p"><!----></div>
<center><img src="screenshots/gridSimGT.png" alt="screenshots/gridSimGT.png" />
</center>
<div class="p"><!----></div>
<div class="p"><!----></div>
<center><img src="screenshots/compAppearancesGT.png" alt="screenshots/compAppearancesGT.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/gridSimResultsGT.png" alt="screenshots/gridSimResultsGT.png" />
</center>
<div class="p"><!----></div>
<br /><br /><hr /><small>File translated from
T<sub><font size="-1">E</font></sub>X
by <a href="http://hutchinson.belmont.ma.us/tth/">
T<sub><font size="-1">T</font></sub>H</a>,
version 3.81.<br />On 10 Sep 2014, 21:33.</small>
</html>

BIN
docs/iBioSim_SynBio_Tutorial.pdf Normal file
View file

Binary file not shown.

522
docs/iBioSim_SynBio_Tutorial.tex Normal file
View file

@ -0,0 +1,522 @@
\documentclass[titlepage,11pt]{article}
\textwidth 6.5in
\textheight 9in
\oddsidemargin -0.2in
\topmargin -0.5in
\usepackage{indentfirst,graphics,alltt,epsfig,color}
\title{iBioSim Version 2.7 \\ Tutorial}
\author{Chris J. Myers}
\begin{document}
\maketitle
%show only subsection granularity in the toc
%\setcounter{tocdepth}{2}
\tableofcontents
\clearpage
\section{Introduction}
\noindent
{\tt iBioSim} has been developed for the modeling, analysis, and design of genetic circuits. While {\tt iBioSim} primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed.
{\tt iBioSim} makes extensive use of standard data representations. Models are specified in {\tt iBioSim} in the %%tth:\begin{html}<A HREF="http://www.sbml.org/">\end{html}
\emph{Systems Biology Markup Language}
%%tth:\begin{html}</A>\end{html}
~(SBML). It can import all levels and versions of SBML and is able to export Level 3 Version 1. It supports all core SBML modeling constructs except some types of \emph{fast} reactions, and also has support for the hierarchical model composition, layout, flux balance constraints, and arrays packages. It was the first tool to produce correct results for all examples in the SBML benchmark suite. It has also been tested successfully on the stochastic benchmark suite and the curated models in the
%%tth:\begin{html}<A HREF="http://www.ebi.ac.uk/biomodels-main/">\end{html}
\emph{BioModels database}.
%%tth:\begin{html}</A>\end{html}
{\tt iBioSim} can also import
%%tth:\begin{html}<A HREF="http://sed-ml.org/">\end{html}
\emph{SED-ML} files
%%tth:\begin{html}</A>\end{html}
that describe simulation experiments. Finally, it is one of the first tools to also support the
%%tth:\begin{html}<A HREF="http://www.sbolstandard.org/">\end{html}
\emph{Synthetic Biology Open Language}
%%tth:\begin{html}</A>\end{html}
~(SBOL), an emerging standard for information exchange in synthetic biology.
{\tt iBioSim} includes the following components:
\begin{itemize}
\item Model Editor - a tool to create a model of a genetic circuit or other biological system.
\item SBOL Browser - a tool to view SBOL files and associate DNA components to model elements.
\item Analysis Tool - an abstraction-based ODE, Monte Carlo, and Markov analysis tool.
\item Learn Tool - a tool to learn a model from \emph{time series data} (TSD).
\item TSD Graph Editor- a tool to visualize TSD files.
\item Histogram Graph Editor - a tool to visualize probability data.
\end{itemize}
This tutorial illustrates the first three of these features of {\tt iBioSim} using a model of the Genetic Toggle Switch (Gardner et al., 2000).
\section{Project Management}
\noindent
Within {\tt iBioSim}, all files are collected within projects. A project is a collection of models, analysis views, learn views, and graphs. As shown below, {\tt iBioSim} displays all project files on the left, the open models, views, and graphs on the right, and a log of all external commands on the bottom. The menu bar is located on the top of the window in the Windows and Linux versions. It is located on the top of the screen in the MacOS version.
\begin{center}
\includegraphics[width=160mm]{screenshots/iBioSim}
\end{center}
\noindent
To create a new project, select New $\rightarrow$ Project from the File menu as shown below. You will then be prompted to browse to a desired location and to give a name to the project directory. Enter the name {\tt SynBioTutorial}. After you do this, click the new button and a new project directory will be created.
\begin{center}
\includegraphics[width=60mm]{screenshots/project}
\end{center}
\section{Importing Models}
\noindent
In order to do analysis within {\tt iBioSim}, you must first have models to analyze. The simplest way to obtain a model to analyze is to import it from an external source. As shown below, using the menu option File $\rightarrow$ Import, {\tt iBioSim} can import models in a variety of ways. First, one can simply import an SBML model from somewhere on the local file system.
\begin{center}
\includegraphics[width=60mm]{screenshots/import}
\end{center}
One can also import an SBML model from the EMBL-EBI's BioModels Repository by selecting the menu option File $\rightarrow$ Import $\rightarrow$ BioModel. This brings up the window shown below without the model names. Pressing the Get Names button will fetch the names, but this takes awhile the first time, so let's skip that for now. Instead, scroll down to BIOMD0000000507 and Press the Get Description button which brings up the BioModels entry for this model in a browser, which you can see is the original model of the genetic toggle switch. The Get Reference button brings up a browser entry for the original publication. With BIOMD0000000507 highlighted, press OK to fetch this SBML model. Since this model does not include any layout information, you will need to either lay it out by hand or use one of the default layout routines selectable using the Apply Layout icon \includegraphics{../gui/icons/modelview/choose_layout_selected}. Horizontal Hierarchical layout works well for this model. Click on the ``X'' to close the window.
\begin{center}
\includegraphics[width=120mm]{screenshots/BioModels}
\end{center}
Another source for import of SBML models is from Newcastle University's Virtual Parts Repository. In this case, you can either import a model of the part or of the part's interactions.
\begin{center}
\includegraphics[width=120mm]{screenshots/VirtualParts}
\end{center}
Next, you can import a \emph{labeled Petri net} (LPN) model. Petri net models are a type of discrete modeling formalism similar to a state machine though with more support for the modeling of concurrent systems. LPNs extend Petri nets with labels that indicate when state transitions are enabled, the time they take, and how they update the system state. {\tt iBioSim} uses the LPN format for Markov chain analysis of biological systems.
We can also import an SBOL file that provides annotated DNA sequences for DNA components. More on this later.
Finally, we can import a SED-ML file that describes a simulation experiment.
Importing a SED-ML file will also import the SBML models required for the simulation followed by performing the simulation. To see how this works, select File $\rightarrow$ Import $\rightarrow$ SED-ML File, and browse to the install directory for {\tt iBioSim}. Continue browsing from here to the directory:\\
{\tt <INSTALL DIRECTORY>/docs/SynBioTutorial/SBMLTestSuite} \\
which contains the SBML testsuite files. Go to test 00001, and select the file:\\
{\tt 00001-sbml-l3v1-sedml.xml}. This will import an SBML model called {\tt case00001.xml} and simulate it. Click on the tab labelled TSD Graph to see the result of an ODE simulation of this model. Repeat these steps to import a SED-ML file for test case 01195. This SBML model is a \emph{flux balance} model, so the analysis performed is flux balance analysis. To see the results, click on the Histogram tab. Now, click on the ``X'' to close each window.
\begin{center}
\includegraphics[width=160mm]{screenshots/TestSuiteResults}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/FBAresults}
\end{center}
\section{Model Editor}
\noindent
Let us know see how to create a new model using the Model Editor. First, select New $\rightarrow$ Model from the File menu as shown below. You will then be prompted to enter a model ID. Enter {\tt LacI\_Inverter}. At this point, a Model editor will open in a new tab.
\begin{center}
\includegraphics[width=80mm]{screenshots/newModel}
\end{center}
\begin{center}
\includegraphics[height=25mm]{screenshots/ModelIdGT}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/schematicGT}
\end{center}
To add a chemical species, select the Add Species icon \includegraphics{../gui/icons/modelview/add_species_selected} and click on the schematic canvas. This will drop a new species with default ID and other values. You may change these defaults by clicking on the selection icon
\includegraphics{../gui/icons/modelview/select_mode_selected}, and
double-clicking on the species to open the Species Editor. In this case, let us change the ID to LacI and change the Port type to \emph{input}. We will leave all the other values at their default values. The port type of input indicates that this species will be used as an input for the LacI inverter.
Note that while in the select mode, you can also select an object in the schematic and move it by moving the mouse while holding the left mouse button. Pressing the right mouse button while an object is selected brings up a menu that allows you to delete an object from the schematic. Repeat the steps above to add TetR and GFP species. Give these species port type of \emph{output}.
\begin{center}
\includegraphics[width=160mm]{screenshots/speciesGT}
\end{center}
% Add another species for the CI dimer molecule. The next step is to add a complex-formation reaction to convert CI monomers into CI dimers. Select the complex formation icon \includegraphics{../gui/icons/modelview/bio_activation_selected}, highlight the CI species, and, while holding the mouse button, stretch the complex formation arc to the S1 species. Next, edit this species to set its ID to CI2 and select that it degrades. This species is created using a complex-formation reaction with an equilibrium constant of 0.1. Change default to custom for the complex formation equilibrium and set it to this value as shown below.
% \begin{center}
% \includegraphics[width=160mm]{screenshots/species2}
% \end{center}
% If you double-click on the complex formation arc, an influence editor will open which indicates that this is a complex formation arc and the stoichiometry of binding (i.e., the number of molecules of the source species used to construct the sink species) is 2. The default in this case is correct as it does take two molecules of CI to make CI2.
% \begin{center}
% \includegraphics[width=160mm]{screenshots/complex}
% \end{center}
Next, let's add the pLac promoter, which initiates transcription of the gene that produces the proteins TetR and GFP. To do this, select the promoter icon \includegraphics{../gui/icons/modelview/promoter_mode_selected} and click on the schematic canvas to drop the promoter with a default ID and parameter values. Double-click on the promoter to bring up the promoter editor. Change the ID to pLac.
\begin{center}
\includegraphics[width=160mm]{screenshots/promoterGT}
\end{center}
The pLac promoter is repressed by the LacI species. To create this relationship, select the repression arc icon
\includegraphics{../gui/icons/modelview/inhibition_selected}, highlight the LacI species, and, while holding the mouse button, stretch the repression arc to the pLac promoter.
%% Next, double-click on the repression arc to bring up the influence editor.
\begin{center}
\includegraphics[width=160mm]{screenshots/repressionGT}
\end{center}
As mentioned earlier, the pLac promoter initiates the production of the TetR and GFP species. Highlight the pLac promoter and, while holding the mouse button, stretch the production arc to the TetR species. Repeat these steps to create a production arc between the pLac promoter and GFP species. Note that the icons selected for this are not important because all arcs from promoters to species are always production arcs.
\begin{center}
\includegraphics[width=160mm]{screenshots/productionGT}
\end{center}
Let us now annotate the LacI inverter with its DNA sequence. To do this, we will need to first import some annotated sequence data stored using the \emph{synthetic biology open language} (SBOL). Select the File $\rightarrow$ Import $\rightarrow$ SBOL File menu option as shown below. This will bring up a file browser. You will need to find the location where {\tt iBioSim} is installed, and the file you want to import should be located in {\tt iBioSim/docs/SynBioTutorial/SBOL/GeneticToggle.sbol}.
\begin{center}
\includegraphics[width=60mm]{screenshots/importSBOL}
\end{center}
Next, click on the Model button in the schematic editor which brings up the Model editor shown below.
\begin{center}
\includegraphics[width=160mm]{screenshots/ModelEditorGT}
\end{center}
Next, click on the Associate SBOL button, highlight the placeholder for the DNA component, and click the Remove button. Then, press the Add button which will open the SBOL browser shown below. In the list of DNA components, scroll down to the component named pIKERightCassette\_1, select it, and press OK.
\begin{center}
\includegraphics[width=160mm]{screenshots/SBOLBrowserGT}
\end{center}
The SBOL association editor should now show this DNA component as being associated with this model. We could now add more components, if we wish, but only one is needed for this, so press Ok. We are now done with the LacI inverter model, so let's make sure the model is saved by either clicking on the Save icon \includegraphics{../gui/icons/save} or selecting the Save option from the File menu.
\begin{center}
\includegraphics[width=160mm]{screenshots/SBOLAssociationGT}
\end{center}
Next, repeat the steps above to create a TetR\_Inverter model. The TetR inverter has input TetR and output LacI. In the TetR inverter, TetR represses the production of LacI. To indicate this, select the repression icon \includegraphics{../gui/icons/modelview/inhibition_selected}, highlight the TetR species and stretch the arc to the LacI species. This action creates an implicit promoter P0 that is repressed by TetR and initiates production of LacI. When you associate SBOL with this model, select the pIKELeftCassette\_1 component, and select for it to be put on the Minus Strand by checking the box on the SBOL association window. Do not forget to save this model either by clicking on the Save icon \includegraphics{../gui/icons/save} or selecting the Save option from the File menu.
\begin{center}
\includegraphics[width=160mm]{screenshots/implicitPromoterGT}
\end{center}
Now, let us put these genetic inverters into a new model called GeneticToggle.
This model will be the top-level model, and all elements of this model will be enclosed in this model's \emph{compartment}. Compartments are the membrane-enclosed regions where species can be found and reactions take place. {\tt iBioSim} creates a default compartment initially with the ID of Cell. If you click on the schematic within the Cell compartment, it brings up the compartment editor. Uncheck the ``Is Mapped to a Port''. This indicates that this compartment should be enclosing this model and not replaced when instantiated in a larger model. Once you press OK, you will notice that the compartment now has rounded corners to indicate that this is membrane enclosed by the compartment Cell.
\begin{center}
\includegraphics[width=160mm]{screenshots/compartmentGT}
\end{center}
Now, lets add the LacI\_Inverter component to this model. Select the Add Component icon \includegraphics{../gui/icons/modelview/add_component_selected} and click on the Schematic canvas opening the Add Component(s) window. In this window, browse the combo box, if necessary, to find your LacI\_Inverter model. Pressing OK will then add it to your schematic. Repeat these steps to add the TetR\_Inverter.
\begin{center}
\includegraphics[width=160mm]{screenshots/subModelGT}
\end{center}
The next step is to connect the components through their species. To do this, add species to the model for LacI, TetR, and GFP. Mark that each of these species degrades, and set the initial amount of LacI to 60. The degrades checkbox means that when this model is analyzed a default degradation reaction will be created which has a rate of 0.0075. Next, highlight the LacI species and stretch a connection to the LacI\_Inverter connecting it to its LacI input port. Next, highlight the LacI\_Inverter and stretch to the TetR species. In this case, since there are two output ports, you must select the TetR output port is the one desired. Next, highlight the TetR species and stretch to the TetR\_Inverter to connect to the TetR input port. Next, highlight the TetR\_Inverter and stretch to the LacI species to connect it to its LacI output port. Finally, highlight the Lac\_Inverter and stretch to the GFP species being sure to select to connect to its GFP output port.
\begin{center}
\includegraphics[width=160mm]{screenshots/addConnectionGT}
\end{center}
By instantiating these models together, the SBOL associated with each component will now be composed as well. To add some description for this composite DNA component, click on the Model button, followed by the Associate SBOL button on the Model Editor, and finally the Edit Composite button on the SBOL Association window. You can now add an ID, Name, and Description for this composite DNA component as shown below.
\begin{center}
\includegraphics[width=160mm]{screenshots/compSBOLDesc}
\end{center}
Next let us add the complex formation reactions that sequester LacI and TetR preventing them from acting as repressors. First, add the small molecule species IPTG and aTc. Select \emph{boundary condition} to indicate they are replenished inputs to the system. Next, add the complex species IPTG\_LacI and aTc\_TetR and mark that they degrade. Now, select the complex formation icon \includegraphics{../gui/icons/modelview/bio_activation_selected}, highlight the IPTG species, and, while holding the mouse button, stretch the complex formation arc to the IPTG\_LacI species. Repeat this step to connect complex formation arcs between LacI and this complex, as well as from aTc and TetR to the aTc\_TetR complex. Finally, click on the selection icon
\includegraphics{../gui/icons/modelview/select_mode_selected}, and
double-click on each complex formation to open the Influence Editor. In this editor, change the Stoichiometry of binding (nc) from 2 to 1 by first changing ``default'' to ``custom'' then editing the value.
\begin{center}
\includegraphics[width=160mm]{screenshots/complexGT}
\end{center}
The final step in the model creation is to add some discrete events to change the amounts of IPTG and aTc, so we may see the genetic toggle switch change state during simulation. First, select the event icon \includegraphics{../gui/icons/modelview/event_mode_selected}, and click on the schematic to add an event. This action opens the event editor. In this editor, create an event with ID ``IPTG\_High'', a trigger of ``true'', and a delay of 2000. Next, click on Add Assignment to bring up the Event Assignment Editor. In this editor, select the variable IPTG and provide the assignment of 60. Press the Add button to add the assignment and the Add button to add the event. This event will cause the amount of IPTG to change to 60 molecules after 2000 seconds of simulation time. Repeat these steps to create an ``IPTG\_Low'' event with a delay of 4000 which assigns 0 to IPTG, an ``aTc\_High'' event with a delay of 6000 which assigns 60 to aTc, and finally an ``aTc\_Low'' event with a delay of 8000 which assigns 0 to aTc.
\begin{center}
\includegraphics[width=160mm]{screenshots/eventGT}
\end{center}
You should now have a complete model of the genetic toggle switch that looks like the one below (though locations of elements may be different). Make sure the model is saved by either clicking on the Save icon \includegraphics{../gui/icons/save} or selecting the Save option from the File menu.
\begin{center}
\includegraphics[width=160mm]{screenshots/saveGT}
\end{center}
\section{SBOL Browser}
As mentioned above, a composite DNA component has been constructed for the entire genetic toggle switch. To see this component, click on the GeneticToggle.sbol file in the list of project files to open the SBOL browser. On the right side, scroll down and select the DNA component that you named MyGeneticToggle. You will now see the complete annotated DNA sequence for this component. Note how the pIKELeftCassette\_1 has been put on the minus strand while the pIKERightCassette\_1 follows it on the positive strand.
\begin{center}
\includegraphics[width=160mm]{screenshots/SBOLBrowserGT2}
\end{center}
\section{Analysis Tool}
This section describes how to analyze the model just created. The first step is to create an analysis view. To do this, right-click on the model file and select Create Analysis View. Enter the analysis ID {\tt GeneticToggle} or just press enter. At this point, a new analysis view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
\begin{center}
\includegraphics[height=60mm]{screenshots/createAnalysisViewGT}\\
\includegraphics[width=160mm]{screenshots/analysisViewGT}
\end{center}
In order to perform analysis, the analysis tool first converts the model into a detailed reaction-based model. There are three different ways to see the reaction-based model that is produced. If GraphViz is installed on your computer, you can select Network for your Simulation Type. Then, either press the Save and Run icon \includegraphics{../gui/icons/run-icon} or select the Save and Run option from the File menu. The result will be a GraphViz window that will open to show the reaction-based model such as the one shown below for our example. If it does not open in GraphViz, make sure that you have files with the {\tt .dot} file extension associated with GraphViz on your computer. You can also view the model in a web browser by selecting Browser for your simulation type. In this case, you should ensure that you have files with the {\tt .xhtml} extension associated with your favorite browser. Finally, you can save the reaction-based model by selecting Model as your simulation type. In this case, you must provide a new model ID. This new model will appear in your project and it can be opened in the Model Editor. Since this model does not include any layout information, you will need to either lay it out by hand or using one of the default layout routines selectable using the Apply Layout icon \includegraphics{../gui/icons/modelview/choose_layout_selected}.
\begin{center}
\includegraphics[width=160mm]{screenshots/viewNetworkGT}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/viewBrowserGT}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/reactionModelGT}
\end{center}
As you can see, this model is quite complex. A simple model can be generated by selecting Abstraction to reduce the model using reaction-based abstractions based on the quasi-steady state assumption. The abstracted model shown below is reduced from 15 species and 13 reactions to just 5 species and 5 reactions.
\begin{center}
\includegraphics[width=160mm]{screenshots/reactionModelAbsGT}
\end{center}
Now, go back to the simulation options tab. Here, make sure that Abstraction is still selected, change the simulation type back to ODE, the simulator to Runge-Kutta-Fehlberg, the time limit to 10000.0, the print interval to 100.0, and enter a Simulation ID of {\tt ode}. Then, either press the Save and Run icon \includegraphics{../gui/icons/run-icon} or select the Save and Run option from the File menu.
After the simulation completes, click on the TSD Graph tab. Double-click on the graph to bring up the graph editor.
Open the {\tt ode} simulation, highlight Average, select aTc, IPTG, and GFP, change the Title to ``ODE Simulation Results'', change the X-Axis Label to ``Time (seconds)'', and change the Y-Axis Label to ``Number of Molecules''.
Press the OK button.
\begin{center}
\includegraphics[width=160mm]{screenshots/odeSimGT}\\
\includegraphics[width=160mm]{screenshots/odeResultsGT}\\
\includegraphics[width=160mm]{screenshots/odeSimResultsGT}
\end{center}
Graphs can be exported in a variety of formats including:
\begin{itemize}
\item Time series data format (tsd).
\item Comma separated value (csv).
\item Column separated data (dat).
\item Encapsulated postscript (eps).
\item Joint Photographic Experts Group (jpg).
\item Portable document format (pdf).
\item Portable network graphics (png).
\item Scalable vector graphics (svg).
\end{itemize}
In order to export a graph, you can either click on the Export icon \includegraphics{../gui/icons/export} or select one of the graph export options from the File menu. When using the Export icon, the type of file exported will depend on the extension provided to the file name. Click on the Export icon, browse to a location on your file system, and enter the file name of {\tt ode.pdf} to create a PDF file for your graph.
\begin{center}
\includegraphics[height=60mm]{screenshots/exportTSD}
\end{center}
Now, select the Simulation Options tab again, select {\tt Monte Carlo}, change the simulator SSA-Direct, the number of runs to 100, set the simulation ID to {\tt ssa}, and click on the Save and Run icon. Click on the TSD Graph tab. Double-click on the graph to bring up the graph editor. Click on Deselect All to remove the plotted points. Open the {\tt ssa} simulation directory, and highlight {\tt run-1}. Select aTc, IPTG, and GFP, and change the title to ``SSA Simulation Results''. Press the OK button. Click on the Export icon and enter the file name {\tt ssa-1.pdf}. Repeat these steps to generate graphs for the average ({\tt average.pdf}).
\begin{center}
\includegraphics[width=160mm]{screenshots/ssaSimGT}\\
\includegraphics[width=160mm]{screenshots/ssaResultsGT}\\
\includegraphics[width=160mm]{screenshots/ssaSimResultsGT}
\end{center}
Another way to view simulation results is on the schematic. To do this, click on the schematic tab. At the bottom of the window, select the Choose Simulation button, which brings up a window with all the simulations in this analysis view. Open the {\tt ssa} directory, select {\tt run-1.tsd}, and press OK.
\begin{center}
\includegraphics[width=160mm]{screenshots/chooseSimGT}
\end{center}
Now, click on the GFP species, which brings up the Edit Species window. Select the Appearance tab. Here you can select how you want the species to appear as you playback the simulation. You can have it change color, size, and/or opacity on a gradient. You can also select the range of molecule counts to specify the ends of the gradient(s). Finally, you can indicate that these selections are either for this species or all species in the model. For our example, let's make GFP follow a green color gradient, IPTG follow a blue color gradient, LacI follow a cyan color gradient, aTc follow a red color gradient, and TetR follow a magenta gradient.
\begin{center}
\includegraphics[width=160mm]{screenshots/editSpeciesAppearanceGT}
\end{center}
Once you have made your selections, you can now play back the simulation. You can either single-step the simulation by pressing the \includegraphics{../gui/icons/modelview/movie/single_step} icon or play continuously by pressing the \includegraphics{../gui/icons/modelview/movie/play} icon. The playback can also be paused by pressing the \includegraphics{../gui/icons/modelview/movie/pause} icon and restarted by pressing the \includegraphics{../gui/icons/modelview/movie/rewind} icon.
\begin{center}
\includegraphics[width=160mm]{screenshots/movieViewGT}
\end{center}
\section{Grid Models}
In the last example, we will build a model with a grid.
%First, edit the CII species and make it diffusible, and save the model.
Create a grid model using the File $\rightarrow$ New $\rightarrow$ Grid Model menu, and name the new model {\tt Population}. In the create grid window shown below, select your copy of your GeneticToggle model and change the number of rows and columns to 5.
\begin{center}
\includegraphics[width=60mm]{screenshots/createGridGT}
\end{center}
The schematic in a grid model is a bit different. It includes a grid in which each location can be empty or contain exactly one component. Only components can be added to grids.
\begin{center}
\includegraphics[width=160mm]{screenshots/gridModelGT}
\end{center}
Next, right-click on the Population model and create an analysis view. Select Abstraction, Monte Carlo, and the SSA-Direct simulator. Set the time limit to 10000 with a print interval of 100, and perform the simulation. Now, go to the schematic tab and press the Choose Simulation button to select run-1.tsd. Click on one of the genetic toggle switch models to bring up the Edit Species editor. Select the GFP species and a green color gradient, and apply to all components with this model. Now, play back the simulation to see the toggle switches turn on and off.
\begin{center}
\includegraphics[width=160mm]{screenshots/gridSimGT}
\end{center}
% When you create a reaction-based model for a grid during analysis, reactions are created to move the diffusible species between the grid locations to provide a coarse form of spatial modeling. If the component within a grid location is enclosed in a compartment membrane (indicated by the rounded corners), the model generated also includes reactions to diffuse the species in and out of the compartment. In the analysis schematic, you can visualize your grid models by clicking on the component in the grid and selecting the species that you would like to see. For each such species, you can set its color, size, and/or opacity gradient. You can also copy these settings to all like models in your grid. Finally, you can click on the area outside of the component within the grid to allow you to also visualize the species that are in the medium.
\begin{center}
\includegraphics[width=160mm]{screenshots/compAppearancesGT}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/gridSimResultsGT}
\end{center}
\end{document}
Using the schematic tab, you can also adjust initial values and parameters allowing one to perform simulations to determine the effect of these changes. Clicking on any species, promoter, reaction, or influence brings up the corresponding editor. To change a value, switch the corresponding combo box to modified, which will then allow you to change the value. For example, as shown below, we have reduced the degradation rate for CI to 0.00075. Now, rerun the simulation and observe the change in the simulation data.
\begin{center}
\includegraphics[width=160mm]{screenshots/paramEdit}
\end{center}
In addition to making single changes, you can also sweep a value as shown below. When you click on the Sweep button, it brings up a window where you can select the start value, the stop value, and the step value. Using the values shown below for this example, simulations are generated using degradation rates of 0.001, 0.003, 0.005, and 0.007. The level indicates how the sweep should perform when multiple variables are swept at the same time. Variables at the same level are changed at the same time. Furthermore, all variables on level 2 are stepped through all their values before changing the values of those variables on level 1. After the values on level 1 are changed, the values on level 2 are stepped through all their values again. Rerun the simulation and create a graph that shows the value of CI for each of the different degradation rates.
\begin{center}
\includegraphics[width=160mm]{screenshots/sweep}
%\includegraphics[height=90mm]{screenshots/sweepPR}
\end{center}
The efficiency of simulation can be improved by employing various automatic abstraction techniques. Go back to the Schematic tab and change the degradation rate of CI back to the default value. Also, go to the SBML elements tab and uncheck the rule for CI\_total. To activate abstraction, click on the Simulation Options tab, select Abstraction and change the simulation ID to {\tt abs}. Press the Save and Run icon and note that the simulation time is substantially faster. Plot both the SSA results for CI\_total and CII with the abstraction results for CI (note this is now equivalent to CI\_total after abstraction) and CII.
\begin{center}
\includegraphics[width=160mm]{screenshots/absResults}
\end{center}
One way to understand why abstraction is so much faster is by looking at the complexity of the reaction-based model before and after abstraction. The reaction-based model after abstraction is shown below which is clearly much simpler than the full model shown earlier.
\begin{center}
\includegraphics[width=100mm]{screenshots/viewNetworkAbs}
\end{center}
Next, let's try checking some properties. To do this, go to the SBML Elements tab and check the boxes next to the constraints. Recall that these constraints terminate simulation whenever CI goes above 20 molecules or CII goes above 50 molecules. Go back to the Simulation Options tab and change abstraction back to none, the Simulation Type to Monte Carlo, and Simulation ID to prob, then press the Save and Run icon. Now, let's plot the results on a histogram by clicking on the Histogram tab and then double-clicking on the graph to bring up the histogram graph editor shown below. Open the prob folder, select the sim-rep file, and check the Use check box to get all fields.
\begin{center}
\includegraphics[width=160mm]{screenshots/editProbGraph}
\end{center}
The histogram shown here indicates that CI goes above 20 molecules first about 21 percent of the time, CII goes above 50 molecules first about 74 percent of the time, and the simulation terminates before either happens about 5 percent of the time.
\begin{center}
\includegraphics[width=160mm]{screenshots/probResults}
\end{center}
These results can also be visualized using the TSD graph tool. Click on the TSD graph tab, click on the graph, Deselect All, open the prob folder, select the Percent Termination file, and add both constraints to the graph. The result, shown below is the probability of each constraint terminating the simulation as time evolves.
\begin{center}
\includegraphics[width=160mm]{screenshots/probResultsTSD}
\end{center}
\section{Learn Tool}
This section describes how a model can be learned from time series data using {\tt iBioSim}'s Learn Tool. To demonstrate the Learn Tool, first create a simple model, {\tt lambdaLearn}, which just includes the two species CI and CII as shown below. Next, create a learn view by right-clicking on this model file and selecting Create Learn View. Give this learn view the ID {\tt learnLambda}. At this point, a new learn view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
\begin{center}
\includegraphics[height=60mm]{screenshots/createLearn}
\end{center}
The next step is to add some experimental data from which you wish to learn a model. In this demo, we will just utilize our simulation data as synthetic experimental data. To do this, click Copy From View, and select {\tt lambda/abs}. Highlight {\tt lambda/abs/run-1.tsd} and you should see the simulation data for CI and CII appear on the right in the data editor.
\begin{center}
\includegraphics[width=160mm]{screenshots/dataManager}
\end{center}
Now, click on the Learn tab. Here you can edit the various learning options. For example, you can either use auto-generated levels or user-generated levels for your data encoding. Select Use User Generated Levels, which will make the levels below editable. At this point, you can ask the tool to suggest levels by clicking on the Suggest Levels button. Finally, click on the Save and Run icon which will bring up the model that has been learned from this experimental data using Graphviz's dotty program, and ask you for a model ID for the generated model.
\begin{center}
\includegraphics[width=160mm]{screenshots/learn}
\end{center}
\section{Advanced Modeling}
This section is less detailed than the others but it gives some intuition about modeling using reactions, components, and grids.
%% TODO: Need to add SBOL to tutorial
%It also introduces our preliminary support of the emerging \emph{Synthetic Biology Open Language standard} (SBOL). Let us take the last of these first. An SBOL file includes \emph{Collections} of \emph{DNA Components}. Each DNA component has a unique ID, name, description, type, and a DNA sequence. A DNA component can be a simple sequence feature like a promoter, ribosome binding site, open reading frame (i.e., gene), or terminator. It can also be an annotated DNA sequence that includes several of these individual features, perhaps organized hierarchically. For example, a DNA component may include a promoter followed by a ribosome binding site followed by a open reading frame followed by a terminator. When editing the model, you may have noticed the various SBOL fields. Namely, for a promoter, you can associate both a DNA component to the promoter as well as a terminator for the transcription initiated at this promoter. For a species, you can associate both a DNA component for the open reading frame for the gene that produces this species as well as the ribosome binding site where translation begins for this gene. This SBOL browser is opened by clicking on an Associate SBOL button within either the Species Editor or Promoter Editor. This browser only shows DNA components of the appropriate type. For example, when associating a species to its open reading frame, only DNA components of the open reading frame type are shown. After you have associated all genetically produced species (i.e., CI and CII in our model) and all promoters (i.e., PR and PRE in our model), you can then save the DNA component for your model into your SBOL file. You can also export it into a new or existing SBOL file outside your project.
%
% \begin{center}
% \includegraphics[width=160mm]{screenshots/AssociateSBOL}
% \end{center}
%
First, let's consider an alternative model of CII degradation which we are going to model using chemical reactions. To do this, create a new model named {\tt CII\_degradation}. In this model, create species CII, P1, and CII\_P1, making CII have the input type so that we can connect to it later. Set an initial amount of 35 molecules for P1.
\begin{center}
\includegraphics[width=160mm]{screenshots/P1}
\end{center}
Now, select the Add Reaction icon \includegraphics{../gui/icons/modelview/add_reaction_selected} and click on the schematic canvas to drop a reaction. This creates a reaction with a default ID and parameter values that we can change later, if we wish.
\begin{center}
\includegraphics[width=160mm]{screenshots/reaction}
\end{center}
Now, let's connect up the reactant species. To do this, select the Reaction icon \includegraphics{../gui/icons/modelview/reaction_selected}, select the reactant species CII, and, while holding the mouse button, drag the reaction edge to the reaction R1. Similarly, add P1 as a reactant as well. If you double-click on a reactant edge, it brings up a Reactant editor where you can change the stoichiometry, if desired.
\begin{center}
\includegraphics[width=160mm]{screenshots/reactant}
\end{center}
Connecting product species is accomplished in much the same way, except in this case you select reaction R1 and drag the reaction edge to the product CII\_P1. Again, there is a Product editor for changing the stoichiometry. Note that modifiers (i.e., species that are neither produced nor consumed by a reaction but simply catalyze a reaction) can be added in a similar way using the Modifier icon \includegraphics{../gui/icons/modelview/modifier_selected} instead.
\begin{center}
\includegraphics[width=160mm]{screenshots/product}
\end{center}
Now, let's adjust the parameters for this reaction by clicking on it to open the Reaction Editor. Press the Use Mass Action button to automatically create a kinetic law for this reaction. Then, make this reaction reversible and adjust its forward reaction rate to be 1.0.
\begin{center}
\includegraphics[width=160mm]{screenshots/localParam}
\end{center}
Follow the same steps to add another reaction that degrades CII in the CII\_P1 form and releases the protease molecule P1. This reaction is not reversible and it should have a forward rate of 0.002.
\begin{center}
\includegraphics[width=160mm]{screenshots/kineticLaw}
\end{center}
Let's now go and add this new degradation mechanism to our lambda model (you might actually want to copy your old model before you do this, which you can do by highlighting the file and selecting Edit $\rightarrow$ Copy or using the right mouse button menu). To simplify things, remove the rule, constraints, and event. Next, open the Species Editor on CII and deselect the degrades option. Finally, select the Add Component icon \includegraphics{../gui/icons/modelview/add_component_selected} and click on the Schematic canvas opening the Add Component(s) window. In this window, browse the combo box to find your CII\_degradation model. Pressing OK will then add it to your schematic.
\begin{center}
\includegraphics[width=160mm]{screenshots/addComponent}
\end{center}
Now, let's connect CII to this new component to relate the CII within the component to the outer CII species. To do this, select the CII species and, while holding the mouse button, drag a connection to the component connecting CII to the CII port on the component.
You may want to now go and try simulating this model, if you like.
\begin{center}
\includegraphics[width=160mm]{screenshots/addPort}
\end{center}
In the last example, we will build a model with a grid. First, edit the CII species and make it diffusible, and save the model. Now, create a grid model using the File $\rightarrow$ New $\rightarrow$ Grid Model menu, and name the new model {\tt Population}. In the create grid window shown below, select your copy of your lambda model and change the number of rows and columns to 5.
\begin{center}
\includegraphics[width=60mm]{screenshots/createGrid}
\end{center}
The schematic in a grid model is a bit different. It includes a grid in which each location can be empty or contain exactly one component. Only components can be added to grids.
\begin{center}
\includegraphics[width=160mm]{screenshots/gridModel}
\end{center}
When you create a reaction-based model for a grid during analysis, reactions are created to move the diffusible species between the grid locations to provide a coarse form of spatial modeling. If the component within a grid location is enclosed in a compartment membrane (indicated by the rounded corners), the model generated also includes reactions to diffuse the species in and out of the compartment. In the analysis schematic, you can visualize your grid models by clicking on the component in the grid and selecting the species that you would like to see. For each such species, you can set its color, size, and/or opacity gradient. You can also copy these settings to all like models in your grid. Finally, you can click on the area outside of the component within the grid to allow you to also visualize the species that are in the medium.
\begin{center}
\includegraphics[width=160mm]{screenshots/compAppearances}
\end{center}
%% TODO: Add Petri net modeling
\noindent
A more detailed
%%tth:\begin{html}<a href="iBioSim_Grid_Tutorial.html">\end{html}
grid tutorial
%%tth:\begin{html}</a>\end{html}
is available in the {\tt docs} directory that comes with the distribution.
\end{document}

615
docs/iBioSim_SysBio_Tutorial.html Normal file
View file

@ -0,0 +1,615 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<meta name="GENERATOR" content="TtH 3.81">
<style type="text/css"> div.p { margin-top: 7pt;}</style>
<style type="text/css"><!--
td div.comp { margin-top: -0.6ex; margin-bottom: -1ex;}
td div.comb { margin-top: -0.6ex; margin-bottom: -.6ex;}
td div.hrcomp { line-height: 0.9; margin-top: -0.8ex; margin-bottom: -1ex;}
td div.norm {line-height:normal;}
span.roman {font-family: serif; font-style: normal; font-weight: normal;}
span.overacc2 {position: relative; left: .8em; top: -1.2ex;}
span.overacc1 {position: relative; left: .6em; top: -1.2ex;} --></style>
<title> iBioSim Version 2.5 \ Tutorial</title>
<h1 align="center">iBioSim Version 2.5 <br />Tutorial </h1>
<div class="p"><!----></div>
<h3 align="center">Chris J. Myers </h3>
<div class="p"><!----></div>
<div class="p"><!----></div>
<h1>Contents </h1><a href="#tth_sEc1"
>1&nbsp; Introduction</a><br />
<a href="#tth_sEc2"
>2&nbsp; Project Management</a><br />
<a href="#tth_sEc3"
>3&nbsp; Model Editor</a><br />
<a href="#tth_sEc4"
>4&nbsp; Analysis Tool</a><br />
<a href="#tth_sEc5"
>5&nbsp; Learn Tool</a><br />
<a href="#tth_sEc6"
>6&nbsp; Advanced Modeling</a><br />
<div class="p"><!----></div>
<h2><a name="tth_sEc1">
1</a>&nbsp;&nbsp;Introduction</h2>
<div class="p"><!----></div>
<tt>iBioSim</tt> has been developed for the modeling, analysis, and design of genetic circuits. While <tt>iBioSim</tt> primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed. <tt>iBioSim</tt> includes the following components:
<div class="p"><!----></div>
<ul>
<li> Model Editor - a tool to create a model of a genetic circuit or other biological system.
<div class="p"><!----></div>
</li>
<li> Analysis Tool - an abstraction-based ODE, Monte Carlo, and Markov analysis tool.
<div class="p"><!----></div>
</li>
<li> Learn Tool - a tool to learn a model from <em>time series data</em> (TSD).
<div class="p"><!----></div>
</li>
<li> TSD Graph Editor- a tool to visualize TSD files.
<div class="p"><!----></div>
</li>
<li> Histogram Graph Editor - a tool to visualize probability data.
<div class="p"><!----></div>
</li>
</ul>
<div class="p"><!----></div>
This tutorial illustrates each of these features of <tt>iBioSim</tt> using a simple model for the <em>cI</em> and <em>cII</em> genes and the P<sub>R</sub> and P<sub>RE</sub> promoters from the phage &#955; decision circuit.
<div class="p"><!----></div>
<div class="p"><!----></div>
<h2><a name="tth_sEc2">
2</a>&nbsp;&nbsp;Project Management</h2>
<div class="p"><!----></div>
Within <tt>iBioSim</tt>, all files are collected within projects. A project is a collection of models, analysis views, learn views, and graphs. As shown below, <tt>iBioSim</tt> displays all project files on the left, the open models, views, and graphs on the right, and a log of all external commands on the bottom. The menu bar is located on the top of the window in the Windows and Linux versions. It is located on the top of the screen in the MacOS version.
<div class="p"><!----></div>
<center><img src="screenshots/iBioSim.png" alt="screenshots/iBioSim.png" />
</center>
<div class="p"><!----></div>
To create a new project, select New &#8594; Project from the File menu as shown below. You will then be prompted to browse to a desired location and to give a name to the project directory. Enter the name <tt>Tutorial</tt>. After you do this, click the new button and a new project directory will be created.
<div class="p"><!----></div>
<center><img src="screenshots/project.png" alt="screenshots/project.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc3">
3</a>&nbsp;&nbsp;Model Editor</h2>
<div class="p"><!----></div>
After you have created a project, you can create a new model to add to the project by selecting New &#8594; Model from the File menu as shown below. You will then be prompted to enter a model ID. Enter <tt>lambda</tt>. At this point, a Model editor will open in a new tab.
<div class="p"><!----></div>
<center><img src="screenshots/newModel.png" alt="screenshots/newModel.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/ModelId.png" alt="screenshots/ModelId.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/ModelEditor.png" alt="screenshots/ModelEditor.png" />
</center>
<div class="p"><!----></div>
Compartments are the membrane-enclosed regions where species can be found and reactions take place. <tt>iBioSim</tt> creates a default compartment initially with the ID of Cell. If you click on the schematic within the Cell compartment, it brings up the compartment editor. Uncheck the "Is Mapped to a Port". This indicates that this compartment should be enclosing this model and not replaced when instantiated in a larger model. Once you press OK, you will notice that the compartment now has rounded corners to indicate that this is membrane enclosed by the compartment Cell.
<div class="p"><!----></div>
<center><img src="screenshots/compartment.png" alt="screenshots/compartment.png" />
</center>
<div class="p"><!----></div>
To add a chemical species, select the Add Species icon <img src="../gui/icons/modelview/add_species_selected.png" alt="../gui/icons/modelview/add_species_selected.png" /> and click on the schematic canvas. This will drop a new species with default ID and other values. You may change these defaults by clicking on the selection icon
<img src="../gui/icons/modelview/select_mode_selected.png" alt="../gui/icons/modelview/select_mode_selected.png" />, and
double-clicking on the species to open the Species Editor. In this case, let us change the ID to CI, and click on degrades checkbox. We will leave all other values at their default values. One thing that is important to note is that when this model is analyzed a default degradation reaction will be created which has a rate of 0.0075.
<div class="p"><!----></div>
<center><img src="screenshots/species.png" alt="screenshots/species.png" />
</center>
<div class="p"><!----></div>
Add another species for the CI dimer molecule. The next step is to add a complex-formation reaction to convert CI monomers into CI dimers. Select the complex formation icon <img src="../gui/icons/modelview/bio_activation_selected.png" alt="../gui/icons/modelview/bio_activation_selected.png" />, highlight the CI species, and, while holding the mouse button, stretch the complex formation arc to the S1 species. Next, edit this species to set its ID to CI2 and select that it degrades. This species is created using a complex-formation reaction with an equilibrium constant of 0.1. Change default to custom for the complex formation equilibrium and set it to this value as shown below.
<div class="p"><!----></div>
<center><img src="screenshots/species2.png" alt="screenshots/species2.png" />
</center>
<div class="p"><!----></div>
If you double-click on the complex formation arc, an influence editor will open which indicates that this is a complex formation arc and the stoichiometry of binding (i.e., the number of molecules of the source species used to construct the sink species) is 2. The default in this case is correct as it does take two molecules of CI to make CI2.
<div class="p"><!----></div>
<center><img src="screenshots/complex.png" alt="screenshots/complex.png" />
</center>
<div class="p"><!----></div>
Next, let's add the PR promoter, which initiates transcription of the gene that produces the protein CII. To do this, select the promoter icon <img src="../gui/icons/modelview/promoter_mode_selected.png" alt="../gui/icons/modelview/promoter_mode_selected.png" /> and click on the schematic canvas to drop the promoter with a default ID and parameter values. Double-click on the promoter to bring up the promoter editor. Change the ID to PR, customize the RNAP binding equilibrium to be 0.69422, and set the open complex production rate to be 0.014.
<div class="p"><!----></div>
<center><img src="screenshots/promoter.png" alt="screenshots/promoter.png" />
</center>
<div class="p"><!----></div>
The PR promoter is repressed by the CI2 species. To create this relationship, select the repression arc icon
<img src="../gui/icons/modelview/inhibition_selected.png" alt="../gui/icons/modelview/inhibition_selected.png" />, highlight the CI2 species, and, while holding the mouse button, stretch the repression arc to the PR promoter. Next, double-click on the repression arc to bring up the influence editor. In this editor, customize the stoichiometry of binding to 1, indicating that just one CI dimer is necessary to repress this promoter, and change the repression binding equilibrium to 0.2165.
<div class="p"><!----></div>
<center><img src="screenshots/repression.png" alt="screenshots/repression.png" />
</center>
<div class="p"><!----></div>
As mentioned earlier, the PR promoter initiates the production of the CII species. Add the CII species following the steps given earlier for adding a species (be sure to mark that it degrades). Then, highlight the PR promoter and, while holding the mouse button, stretch the production arc to the CII species. Note that the icons selected for this are not important because all arcs from promoters to species are always production arcs.
<div class="p"><!----></div>
<center><img src="screenshots/production.png" alt="screenshots/production.png" />
</center>
<div class="p"><!----></div>
Finally, CII species activates the production of the CI species from the PRE promoter. Promoters do not need to always be drawn. They can also be implicit on an influence. To add an activation arc with an implicit promoter, select the activation arc icon <img src="../gui/icons/modelview/activation_selected.png" alt="../gui/icons/modelview/activation_selected.png" />, highlight the CII species, and, while holding the mouse button, stretch the activation arc to the CI species. This creates not only the influence but also a default promoter. Double-click on the activation arc to bring up the influence editor. In this editor, customize the stoichiometry of binding to 1, indicating that just one CII molecule is necessary to activate this promoter, and change the activation binding equilibrium to 0.00161. Finally, click on the Edit Promoter button and change the ID of this promoter to PRE. Also, customize the RNAP binding equilibrium to be 0.01, the basal production rate to be 0.00004, and the activated production rate to be 0.015.
<div class="p"><!----></div>
<center><img src="screenshots/activation.png" alt="screenshots/activation.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/activated_promoter.png" alt="screenshots/activated_promoter.png" />
</center>
<div class="p"><!----></div>
Next, let's go look at some of the other model tabs. Click on the Functions tab. Here one can add/remove/edit definitions for functions. Click on Add Function, and let's create a function to compute the total number of molecules where x is the number of monomers and y is the number of dimers. Let's give this function an ID of total with arguments x and y, and a definition of x + 2 * y.
<div class="p"><!----></div>
<center><img src="screenshots/function.png" alt="screenshots/function.png" />
</center>
<div class="p"><!----></div>
Click on the Units tab. Unit definitions allow the user to create custom units for use in models. As an example, click Add Unit and enter the ID nanoMole. A unit is defined using pre-defined base units. Click on Add to List and find mole in the Kind combo box, and change the scale to &#8722;9 to define a nanoMole in terms of moles. The exponent and multiplier are real numbers, and the scale is an integer that specifies the relationship between the derived unit and the base unit using the relation below:
<br clear="all" /><table border="0" width="100%"><tr><td>
<table border="0" cellspacing="0" cellpadding="0">
<tr><td width="50%"></td><td nowrap="nowrap" align="right" colspan="1"><table border="0" cellspacing="0" cellpadding="2"><tr><td nowrap="nowrap" align="left">
<span class="roman">unit</span> </td></tr></table></td><td nowrap="nowrap" align="left">
<table border="0" cellspacing="0" cellpadding="2"><tr><td nowrap="nowrap" align="left">
= </td></tr></table></td><td nowrap="nowrap" align="left">
<table><tr><td nowrap="nowrap" align="right" colspan="1">(<span class="roman">multiplier</span> * 10<sup><span class="roman">scale</span></sup> * <span class="roman">baseUnit</span>)<sup><span class="roman">exponent</span></sup></td></tr></table></td><td width="50%"></td></tr></table>
</td></tr></table>
Follow the same steps to create a unit for microLitre.
<div class="p"><!----></div>
<center><img src="screenshots/units.png" alt="screenshots/units.png" />
</center>
<div class="p"><!----></div>
Next, click on the Schematic tab. Then, click on the Model button to bring up a window of default units for this model. These are the units to be used for various things when no units are provided. For this model, let's make the Substance Units be in nanoMoles, Time Units be in seconds, and Volume Units be in microLitres. The Extent Units indicate the units of change for reactions. Let's make that also be nanoMoles.
<div class="p"><!----></div>
<center><img src="screenshots/ModelUnits.png" alt="screenshots/ModelUnits.png" />
</center>
<div class="p"><!----></div>
Next, click on the Constants tab. This tab includes the default model generation parameters as well as additional global variables. The model generation parameters are used for default values when creating a reaction-based model from our higher level model. These parameters can be edited by selecting them and entering a new initial value. They should not be removed. Note that new global constants can also be added by the user, if desired.
<div class="p"><!----></div>
<center><img src="screenshots/GCMparam.png" alt="screenshots/GCMparam.png" />
</center>
<div class="p"><!----></div>
While you can add a global variable here, the preferred way is to add it on the schematic. Click on the Schematic tab. Select the add variable icon <img src="../gui/icons/modelview/variable_mode_selected.png" alt="../gui/icons/modelview/variable_mode_selected.png" />, and click a location to add the variable to the schematic. Then, click on the selection icon
<img src="../gui/icons/modelview/select_mode_selected.png" alt="../gui/icons/modelview/select_mode_selected.png" />, and double click on the variable to open the Parameter Editor. Change the ID to CI_total, for the total amount of the species CI in both monomer and dimer form. Its units are in nanoMole and it is not constant.
<div class="p"><!----></div>
<center><img src="screenshots/parameter.png" alt="screenshots/parameter.png" />
</center>
<div class="p"><!----></div>
<div class="p"><!----></div>
<div class="p"><!----></div>
Now, let's create a rule to compute the value of CI_total. There are three types of rules: algebraic, assignment, and rate. Algebraic rules are used to specify relationships that must be maintained. Assignment rules are used to define one variable in terms of a mathematical expression. Finally, rate rules are used to indicate a differential equation to govern the evolution of a variable in terms of a mathematical expression on other variables. To add a rule, select the add rule icon
<img src="../gui/icons/modelview/rule_mode_selected.png" alt="../gui/icons/modelview/rule_mode_selected.png" />. In the Rule editor,
select Assignment, select the variable CI_total, and enter the expression total(CI,CI2). This uses our new function to compute that the amount of CI in total is the number of monomer molecules plus two times the number of dimer molecules.
<div class="p"><!----></div>
<center><img src="screenshots/rule.png" alt="screenshots/rule.png" />
</center>
<div class="p"><!----></div>
<div class="p"><!----></div>
<div class="p"><!----></div>
Next, let's add a constraint. A constraint is a condition that must be satisfied or simulation should terminate. To add a constraint, select the add constraint icon
<img src="../gui/icons/modelview/constraint_mode_selected.png" alt="../gui/icons/modelview/constraint_mode_selected.png" />. Add a constraint that states that CI remains less than or equal to 20 molecules as shown below. Add a second constraint that states that CII remains less than or equal to 50 molecules.
<div class="p"><!----></div>
<center><img src="screenshots/constraint.png" alt="screenshots/constraint.png" />
</center>
<div class="p"><!----></div>
Finally, let's add an event. Events are used to specify discrete state changes. For example, let's describe an event for cell division. Click on the Add Event button, enter the ID CellDivision, trigger true, and delay of 2100. The trigger specifies the condition that should be satisfied to enable this event. In this case, we want it to be enabled initially. The delay indicates the time after which it is enabled that it should execute. Finally, select the Dynamic Process of Symmetric Division. This combination results in a cell division event at 2100 seconds after simulation begins. The event assignments specify the state change(s) for this event. Click on the Add Assignment button and select the CI variable, and enter the assignment CI / uniform(1,2). In other words, the number of molecules is being divided between the two daughter cells with a random distribution. Similarly, add event assignments to divide up CI2 and CII.
<div class="p"><!----></div>
<center><img src="screenshots/event.png" alt="screenshots/event.png" />
</center>
<div class="p"><!----></div>
At this point, you should have a model that looks like the one below (though locations of elements may be different). Now, let's make sure the model is saved by either clicking on the Save icon <img src="../gui/icons/save.png" alt="../gui/icons/save.png" /> or selecting the Save option from the File menu.
<div class="p"><!----></div>
<center><img src="screenshots/save.png" alt="screenshots/save.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc4">
4</a>&nbsp;&nbsp;Analysis Tool</h2>
<div class="p"><!----></div>
This section describes how to analyze the model just created. The first step is to create an analysis view. To do this, right-click on the model file and select Create Analysis View. Enter the analysis ID <tt>lambda</tt> or just press enter. At this point, a new analysis view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
<div class="p"><!----></div>
<center><img src="screenshots/GCMAnalysis.png" alt="screenshots/GCMAnalysis.png" /><br />
<img src="screenshots/analysisView.png" alt="screenshots/analysisView.png" />
</center>
<div class="p"><!----></div>
In order to perform analysis, the analysis tool first converts the model into a reaction-based model in the <em>Systems Biology Markup Language</em> (SBML). There are three different ways to see the reaction-based model that is produced. If GraphViz is installed on your computer, you can select Network for your Simulation Type. Then, either press the Save and Run icon <img src="../gui/icons/run-icon.jpg" alt="../gui/icons/run-icon.jpg" /> or select the Save and Run option from the File menu. The result will be a GraphViz window that will open to show the reaction-based model such as the one shown below for our example. If it does not open in GraphViz, make sure that you have files with the <tt>.dot</tt> file extension associated with GraphViz on your computer. You can also view the model in a web browser by selecting Browser for your simulation type. In this case, you should ensure that you have files with the <tt>.xhtml</tt> extension associated with your favorite browser. Finally, you can save the reaction-based model by selecting Model as your simulation type. In this case, you must provide a new model ID. This new model will appear in your project and it can be opened in the Model Editor. Since this model does not include any layout information, you will need to either lay it out by hand or using one of the default layout routines selectable using the Apply Layout icon <img src="../gui/icons/modelview/choose_layout_selected.png" alt="../gui/icons/modelview/choose_layout_selected.png" />,
<div class="p"><!----></div>
<center><img src="screenshots/viewNetwork.png" alt="screenshots/viewNetwork.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/viewBrowser.png" alt="screenshots/viewBrowser.png" />
</center>
<div class="p"><!----></div>
<center><img src="screenshots/reactionModel.png" alt="screenshots/reactionModel.png" />
</center>
<div class="p"><!----></div>
Next, click on the SBML elements tab. This tab allows you to select which SBML model elements to include in your analysis. This includes initial assignments, rules, constraints, and events. Initially, let's only include the rule to compute CI_total. Uncheck all the other elements.
<div class="p"><!----></div>
<center><img src="screenshots/SBMLElements.png" alt="screenshots/SBMLElements.png" />
</center>
<div class="p"><!----></div>
Now, go back to the simulation options tab. Here, change the simulation type back to ODE, change the time limit to 2100.0, change the print interval to 10.0, and enter a Simulation ID of <tt>ode</tt>. Then, either press the Save and Run icon <img src="../gui/icons/run-icon.jpg" alt="../gui/icons/run-icon.jpg" /> or select the Save and Run option from the File menu.
After the simulation completes, click on the TSD Graph tab. Double-click on the graph to bring up the graph editor.
Open the <tt>ode</tt> simulation, highlight Average, select CI_total and CII, change the Title to "ODE Simulation Results", change the X-Axis Label to "Time (seconds)", and change the Y-Axis Label to "Number of Molecules".
Press the OK button.
<div class="p"><!----></div>
<center><img src="screenshots/odeSim.png" alt="screenshots/odeSim.png" /><br />
<img src="screenshots/odeResults.png" alt="screenshots/odeResults.png" /><br />
<img src="screenshots/odeSimResults.png" alt="screenshots/odeSimResults.png" />
</center>
<div class="p"><!----></div>
Graphs can be exported in a variety of formats including:
<ul>
<li> Time series data format (tsd).
<div class="p"><!----></div>
</li>
<li> Comma separated value (csv).
<div class="p"><!----></div>
</li>
<li> Column separated data (dat).
<div class="p"><!----></div>
</li>
<li> Encapsulated postscript (eps).
<div class="p"><!----></div>
</li>
<li> Joint Photographic Experts Group (jpg).
<div class="p"><!----></div>
</li>
<li> Portable document format (pdf).
<div class="p"><!----></div>
</li>
<li> Portable network graphics (png).
<div class="p"><!----></div>
</li>
<li> Scalable vector graphics (svg).
<div class="p"><!----></div>
</li>
</ul>
In order to export a graph, you can either click on the Export icon <img src="../gui/icons/export.jpg" alt="../gui/icons/export.jpg" /> or select one of the graph export options from the File menu. When using the Export icon, the type of file exported will depend on the extension provided to the file name. Click on the Export icon, browse to a location on your file system, and enter the file name of <tt>ode.pdf</tt> to create a PDF file for your graph.
<div class="p"><!----></div>
<center><img src="screenshots/exportTSD.png" alt="screenshots/exportTSD.png" />
</center>
<div class="p"><!----></div>
Now, select the Simulation Options tab again, select <tt>Monte Carlo</tt>, change the number of runs to 100, set the simulation ID to <tt>ssa</tt>, and click on the Save and Run icon. Click on the TSD Graph tab. Double-click on the graph to bring up the graph editor. Open the <tt>ssa</tt> simulation directory, and highlight <tt>run-1</tt>. Select CI_Total and CII, change the title to "SSA Simulation Results", change the X-Axis Label to "Time (seconds)", and change the Y-Axis Label to "Number of Molecules". Press the OK button. Click on the Export icon and enter the file name <tt>ssa-1.pdf</tt>. Repeat these steps to generate graphs for the average (<tt>average.pdf</tt>) and standard deviation (<tt>stddev.pdf</tt>). Note that you can use the "Deselect All" button to remove all items from the graph.
<div class="p"><!----></div>
<center><img src="screenshots/ssaSim.png" alt="screenshots/ssaSim.png" /><br />
<img src="screenshots/ssaResults.png" alt="screenshots/ssaResults.png" /><br />
<img src="screenshots/ssaSimResults.png" alt="screenshots/ssaSimResults.png" />
</center>
<div class="p"><!----></div>
Another way to view simulation results is on the schematic. To do this, click on the schematic tab. At the bottom of the window, select the Choose Simulation button, which brings up a window with all the simulations in this analysis view. Open the <tt>ssa</tt> directory, select <tt>run-1.tsd</tt>, and press OK.
<div class="p"><!----></div>
<center><img src="screenshots/chooseSim.png" alt="screenshots/chooseSim.png" />
</center>
<div class="p"><!----></div>
Now, click on the CI species, which brings up the Edit Species window. Select the Appearance tab. Here you can select how you want the species to appear as you playback the simulation. You can have it change color, size, and/or opacity on a gradient. You can also select the range of molecule counts to specify the ends of the gradient(s). Finally, you can indicate that these selections are either for this species or all species in the model. For our example, let's make CI follow a green color gradient, CI2 follow a red color gradient, and CII follow a blue color gradient.
<center>
<img src="screenshots/editSpeciesAppearance.png" alt="screenshots/editSpeciesAppearance.png" />
</center>
<div class="p"><!----></div>
Once you have made your selections, you can now play back the simulation. You can either single-step the simulation by pressing the <img src="../gui/icons/modelview/movie/single_step.png" alt="../gui/icons/modelview/movie/single_step.png" /> icon or play continuously by pressing the <img src="../gui/icons/modelview/movie/play.png" alt="../gui/icons/modelview/movie/play.png" /> icon. The playback can also be paused by pressing the <img src="../gui/icons/modelview/movie/pause.png" alt="../gui/icons/modelview/movie/pause.png" /> icon and restarted by pressing the <img src="../gui/icons/modelview/movie/rewind.png" alt="../gui/icons/modelview/movie/rewind.png" /> icon.
<div class="p"><!----></div>
<center><img src="screenshots/movieView.png" alt="screenshots/movieView.png" />
</center>
<div class="p"><!----></div>
Using the schematic tab, you can also adjust initial values and parameters allowing one to perform simulations to determine the effect of these changes. Clicking on any species, promoter, reaction, or influence brings up the corresponding editor. To change a value, switch the corresponding combo box to modified, which will then allow you to change the value. For example, as shown below, we have reduced the degradation rate for CI to 0.00075. Now, rerun the simulation and observe the change in the simulation data.
<div class="p"><!----></div>
<center><img src="screenshots/paramEdit.png" alt="screenshots/paramEdit.png" />
</center>
<div class="p"><!----></div>
In addition to making single changes, you can also sweep a value as shown below. When you click on the Sweep button, it brings up a window where you can select the start value, the stop value, and the step value. Using the values shown below for this example, simulations are generated using degradation rates of 0.001, 0.003, 0.005, and 0.007. The level indicates how the sweep should perform when multiple variables are swept at the same time. Variables at the same level are changed at the same time. Furthermore, all variables on level 2 are stepped through all their values before changing the values of those variables on level 1. After the values on level 1 are changed, the values on level 2 are stepped through all their values again. Rerun the simulation and create a graph that shows the value of CI for each of the different degradation rates.
<div class="p"><!----></div>
<center><img src="screenshots/sweep.png" alt="screenshots/sweep.png" />
</center>
<div class="p"><!----></div>
The efficiency of simulation can be improved by employing various automatic abstraction techniques. Go back to the Schematic tab and change the degradation rate of CI back to the default value. Also, go to the SBML elements tab and uncheck the rule for CI_total. To activate abstraction, click on the Simulation Options tab, select Abstraction and change the simulation ID to <tt>abs</tt>. Press the Save and Run icon and note that the simulation time is substantially faster. Plot both the SSA results for CI_total and CII with the abstraction results for CI (note this is now equivalent to CI_total after abstraction) and CII.
<div class="p"><!----></div>
<center><img src="screenshots/absResults.png" alt="screenshots/absResults.png" />
</center>
<div class="p"><!----></div>
One way to understand why abstraction is so much faster is by looking at the complexity of the reaction-based model before and after abstraction. The reaction-based model after abstraction is shown below which is clearly much simpler than the full model shown earlier.
<div class="p"><!----></div>
<center><img src="screenshots/viewNetworkAbs.png" alt="screenshots/viewNetworkAbs.png" />
</center>
<div class="p"><!----></div>
Next, let's try checking some properties. To do this, go to the SBML Elements tab and check the boxes next to the constraints. Recall that these constraints terminate simulation whenever CI goes above 20 molecules or CII goes above 50 molecules. Go back to the Simulation Options tab and change abstraction back to none, the Simulation Type to Monte Carlo, and Simulation ID to prob, then press the Save and Run icon. Now, let's plot the results on a histogram by clicking on the Histogram tab and then double-clicking on the graph to bring up the histogram graph editor shown below. Open the prob folder, select the sim-rep file, and check the Use check box to get all fields.
<div class="p"><!----></div>
<center><img src="screenshots/editProbGraph.png" alt="screenshots/editProbGraph.png" />
</center>
<div class="p"><!----></div>
The histogram shown here indicates that CI goes above 20 molecules first about 21 percent of the time, CII goes above 50 molecules first about 74 percent of the time, and the simulation terminates before either happens about 5 percent of the time.
<div class="p"><!----></div>
<center> <img src="screenshots/probResults.png" alt="screenshots/probResults.png" />
</center>
<div class="p"><!----></div>
These results can also be visualized using the TSD graph tool. Click on the TSD graph tab, click on the graph, Deselect All, open the prob folder, select the Percent Termination file, and add both constraints to the graph. The result, shown below is the probability of each constraint terminating the simulation as time evolves.
<div class="p"><!----></div>
<center> <img src="screenshots/probResultsTSD.png" alt="screenshots/probResultsTSD.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc5">
5</a>&nbsp;&nbsp;Learn Tool</h2>
<div class="p"><!----></div>
This section describes how a model can be learned from time series data using <tt>iBioSim</tt>'s Learn Tool. To demonstrate the Learn Tool, first create a simple model, <tt>lambdaLearn</tt>, which just includes the two species CI and CII as shown below. Next, create a learn view by right-clicking on this model file and selecting Create Learn View. Give this learn view the ID <tt>learnLambda</tt>. At this point, a new learn view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
<div class="p"><!----></div>
<center><img src="screenshots/createLearn.png" alt="screenshots/createLearn.png" />
</center>
<div class="p"><!----></div>
The next step is to add some experimental data from which you wish to learn a model. In this demo, we will just utilize our simulation data as synthetic experimental data. To do this, click Copy From View, and select <tt>lambda/abs</tt>. Highlight <tt>lambda/abs/run-1.tsd</tt> and you should see the simulation data for CI and CII appear on the right in the data editor.
<div class="p"><!----></div>
<center><img src="screenshots/dataManager.png" alt="screenshots/dataManager.png" />
</center>
<div class="p"><!----></div>
Now, click on the Learn tab. Here you can edit the various learning options. For example, you can either use auto-generated levels or user-generated levels for your data encoding. Select Use User Generated Levels, which will make the levels below editable. At this point, you can ask the tool to suggest levels by clicking on the Suggest Levels button. Finally, click on the Save and Run icon which will bring up the model that has been learned from this experimental data using Graphviz's dotty program, and ask you for a model ID for the generated model.
<div class="p"><!----></div>
<center><img src="screenshots/learn.png" alt="screenshots/learn.png" />
</center>
<div class="p"><!----></div>
<h2><a name="tth_sEc6">
6</a>&nbsp;&nbsp;Advanced Modeling</h2>
<div class="p"><!----></div>
This section is less detailed than the others but it gives some intuition about modeling using reactions, components, and grids.
<div class="p"><!----></div>
<div class="p"><!----></div>
First, let's consider an alternative model of CII degradation which we are going to model using chemical reactions. To do this, create a new model named <tt>CII_degradation</tt>. In this model, create species CII, P1, and CII_P1, making CII have the input type so that we can connect to it later. Set an initial amount of 35 molecules for P1.
<div class="p"><!----></div>
<center><img src="screenshots/P1.png" alt="screenshots/P1.png" />
</center>
<div class="p"><!----></div>
Now, select the Add Reaction icon <img src="../gui/icons/modelview/add_reaction_selected.png" alt="../gui/icons/modelview/add_reaction_selected.png" /> and click on the schematic canvas to drop a reaction. This creates a reaction with a default ID and parameter values that we can change later, if we wish.
<div class="p"><!----></div>
<center><img src="screenshots/reaction.png" alt="screenshots/reaction.png" />
</center>
<div class="p"><!----></div>
Now, let's connect up the reactant species. To do this, select the Reaction icon <img src="../gui/icons/modelview/reaction_selected.png" alt="../gui/icons/modelview/reaction_selected.png" />, select the reactant species CII, and, while holding the mouse button, drag the reaction edge to the reaction R1. Similarly, add P1 as a reactant as well. If you double-click on a reactant edge, it brings up a Reactant editor where you can change the stoichiometry, if desired.
<div class="p"><!----></div>
<center><img src="screenshots/reactant.png" alt="screenshots/reactant.png" />
</center>
<div class="p"><!----></div>
Connecting product species is accomplished in much the same way, except in this case you select reaction R1 and drag the reaction edge to the product CII_P1. Again, there is a Product editor for changing the stoichiometry. Note that modifiers (i.e., species that are neither produced nor consumed by a reaction but simply catalyze a reaction) can be added in a similar way using the Modifier icon <img src="../gui/icons/modelview/modifier_selected.png" alt="../gui/icons/modelview/modifier_selected.png" /> instead.
<div class="p"><!----></div>
<center><img src="screenshots/product.png" alt="screenshots/product.png" />
</center>
<div class="p"><!----></div>
Now, let's adjust the parameters for this reaction by clicking on it to open the Reaction Editor. Press the Use Mass Action button to automatically create a kinetic law for this reaction. Then, make this reaction reversible and adjust its forward reaction rate to be 1.0.
<div class="p"><!----></div>
<center><img src="screenshots/localParam.png" alt="screenshots/localParam.png" />
</center>
<div class="p"><!----></div>
Follow the same steps to add another reaction that degrades CII in the CII_P1 form and releases the protease molecule P1. This reaction is not reversible and it should have a forward rate of 0.002.
<div class="p"><!----></div>
<center><img src="screenshots/kineticLaw.png" alt="screenshots/kineticLaw.png" />
</center>
<div class="p"><!----></div>
Let's now go and add this new degradation mechanism to our lambda model (you might actually want to copy your old model before you do this, which you can do by highlighting the file and selecting Edit &#8594; Copy or using the right mouse button menu). To simplify things, remove the rule, constraints, and event. Next, open the Species Editor on CII and deselect the degrades option. Finally, select the Add Component icon <img src="../gui/icons/modelview/add_component_selected.png" alt="../gui/icons/modelview/add_component_selected.png" /> and click on the Schematic canvas opening the Add Component(s) window. In this window, browse the combo box to find your CII_degradation model. Pressing OK will then add it to your schematic.
<div class="p"><!----></div>
<center><img src="screenshots/addComponent.png" alt="screenshots/addComponent.png" />
</center>
<div class="p"><!----></div>
Now, let's connect CII to this new component to relate the CII within the component to the outer CII species. To do this, select the CII species and, while holding the mouse button, drag a connection to the component connecting CII to the CII port on the component.
You may want to now go and try simulating this model, if you like.
<div class="p"><!----></div>
<center><img src="screenshots/addPort.png" alt="screenshots/addPort.png" />
</center>
<div class="p"><!----></div>
In the last example, we will build a model with a grid. First, edit the CII species and make it diffusible, and save the model. Now, create a grid model using the File &#8594; New &#8594; Grid Model menu, and name the new model <tt>Population</tt>. In the create grid window shown below, select your copy of your lambda model and change the number of rows and columns to 5.
<div class="p"><!----></div>
<center><img src="screenshots/createGrid.png" alt="screenshots/createGrid.png" />
</center>
<div class="p"><!----></div>
The schematic in a grid model is a bit different. It includes a grid in which each location can be empty or contain exactly one component. Only components can be added to grids.
<div class="p"><!----></div>
<center><img src="screenshots/gridModel.png" alt="screenshots/gridModel.png" />
</center>
<div class="p"><!----></div>
When you create a reaction-based model for a grid during analysis, reactions are created to move the diffusible species between the grid locations to provide a coarse form of spatial modeling. If the component within a grid location is enclosed in a compartment membrane (indicated by the rounded corners), the model generated also includes reactions to diffuse the species in and out of the compartment. In the analysis schematic, you can visualize your grid models by clicking on the component in the grid and selecting the species that you would like to see. For each such species, you can set its color, size, and/or opacity gradient. You can also copy these settings to all like models in your grid. Finally, you can click on the area outside of the component within the grid to allow you to also visualize the species that are in the medium.
<div class="p"><!----></div>
<center><img src="screenshots/compAppearances.png" alt="screenshots/compAppearances.png" />
</center>
<div class="p"><!----></div>
<div class="p"><!----></div>
A more detailed
<a href="iBioSim_Grid_Tutorial.html">
grid tutorial
</a>
is available in the <tt>docs</tt> directory that comes with the distribution.
<div class="p"><!----></div>
<br /><br /><hr /><small>File translated from
T<sub><font size="-1">E</font></sub>X
by <a href="http://hutchinson.belmont.ma.us/tth/">
T<sub><font size="-1">T</font></sub>H</a>,
version 3.81.<br />On 6 Sep 2014, 09:48.</small>
</html>

BIN
docs/iBioSim_SysBio_Tutorial.pdf Normal file
View file

Binary file not shown.

439
docs/iBioSim_SysBio_Tutorial.tex Normal file
View file

@ -0,0 +1,439 @@
\documentclass[titlepage,11pt]{article}
\textwidth 6.5in
\textheight 9in
\oddsidemargin -0.2in
\topmargin -0.5in
\usepackage{indentfirst,graphics,alltt,epsfig,color}
\title{iBioSim Version 2.5 \\ Tutorial}
\author{Chris J. Myers}
\begin{document}
\maketitle
%show only subsection granularity in the toc
%\setcounter{tocdepth}{2}
\tableofcontents
\clearpage
\section{Introduction}
\noindent
{\tt iBioSim} has been developed for the modeling, analysis, and design of genetic circuits. While {\tt iBioSim} primarily targets models of genetic circuits, models representing metabolic networks, cell-signaling pathways, and other biological and chemical systems can also be analyzed. {\tt iBioSim} includes the following components:
\begin{itemize}
\item Model Editor - a tool to create a model of a genetic circuit or other biological system.
%\item SBOL Browser - a tool to view SBOL files and associate DNA components to model elements.
\item Analysis Tool - an abstraction-based ODE, Monte Carlo, and Markov analysis tool.
\item Learn Tool - a tool to learn a model from \emph{time series data} (TSD).
\item TSD Graph Editor- a tool to visualize TSD files.
\item Histogram Graph Editor - a tool to visualize probability data.
\end{itemize}
This tutorial illustrates each of these features of {\tt iBioSim} using a simple model for the \emph{cI} and \emph{cII} genes and the $P_R$ and $P_{RE}$ promoters from the phage $\lambda$ decision circuit.
% TODO: add figures and more description of the example
\section{Project Management}
\noindent
Within {\tt iBioSim}, all files are collected within projects. A project is a collection of models, analysis views, learn views, and graphs. As shown below, {\tt iBioSim} displays all project files on the left, the open models, views, and graphs on the right, and a log of all external commands on the bottom. The menu bar is located on the top of the window in the Windows and Linux versions. It is located on the top of the screen in the MacOS version.
\begin{center}
\includegraphics[width=160mm]{screenshots/iBioSim}
\end{center}
\noindent
To create a new project, select New $\rightarrow$ Project from the File menu as shown below. You will then be prompted to browse to a desired location and to give a name to the project directory. Enter the name {\tt Tutorial}. After you do this, click the new button and a new project directory will be created.
\begin{center}
\includegraphics[width=60mm]{screenshots/project}
\end{center}
\section{Model Editor}
\noindent
After you have created a project, you can create a new model to add to the project by selecting New $\rightarrow$ Model from the File menu as shown below. You will then be prompted to enter a model ID. Enter {\tt lambda}. At this point, a Model editor will open in a new tab.
\begin{center}
\includegraphics[width=80mm]{screenshots/newModel}
\end{center}
\begin{center}
\includegraphics[height=25mm]{screenshots/ModelId}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/ModelEditor}
\end{center}
Compartments are the membrane-enclosed regions where species can be found and reactions take place. {\tt iBioSim} creates a default compartment initially with the ID of Cell. If you click on the schematic within the Cell compartment, it brings up the compartment editor. Uncheck the ``Is Mapped to a Port''. This indicates that this compartment should be enclosing this model and not replaced when instantiated in a larger model. Once you press OK, you will notice that the compartment now has rounded corners to indicate that this is membrane enclosed by the compartment Cell.
\begin{center}
\includegraphics[width=160mm]{screenshots/compartment}
\end{center}
To add a chemical species, select the Add Species icon \includegraphics{../gui/icons/modelview/add_species_selected} and click on the schematic canvas. This will drop a new species with default ID and other values. You may change these defaults by clicking on the selection icon
\includegraphics{../gui/icons/modelview/select_mode_selected}, and
double-clicking on the species to open the Species Editor. In this case, let us change the ID to CI, and click on degrades checkbox. We will leave all other values at their default values. One thing that is important to note is that when this model is analyzed a default degradation reaction will be created which has a rate of 0.0075.
\begin{center}
\includegraphics[width=160mm]{screenshots/species}
\end{center}
Add another species for the CI dimer molecule. The next step is to add a complex-formation reaction to convert CI monomers into CI dimers. Select the complex formation icon \includegraphics{../gui/icons/modelview/bio_activation_selected}, highlight the CI species, and, while holding the mouse button, stretch the complex formation arc to the S1 species. Next, edit this species to set its ID to CI2 and select that it degrades. This species is created using a complex-formation reaction with an equilibrium constant of 0.1. Change default to custom for the complex formation equilibrium and set it to this value as shown below.
\begin{center}
\includegraphics[width=160mm]{screenshots/species2}
\end{center}
If you double-click on the complex formation arc, an influence editor will open which indicates that this is a complex formation arc and the stoichiometry of binding (i.e., the number of molecules of the source species used to construct the sink species) is 2. The default in this case is correct as it does take two molecules of CI to make CI2.
\begin{center}
\includegraphics[width=160mm]{screenshots/complex}
\end{center}
Next, let's add the PR promoter, which initiates transcription of the gene that produces the protein CII. To do this, select the promoter icon \includegraphics{../gui/icons/modelview/promoter_mode_selected} and click on the schematic canvas to drop the promoter with a default ID and parameter values. Double-click on the promoter to bring up the promoter editor. Change the ID to PR, customize the RNAP binding equilibrium to be 0.69422, and set the open complex production rate to be 0.014.
\begin{center}
\includegraphics[width=160mm]{screenshots/promoter}
\end{center}
The PR promoter is repressed by the CI2 species. To create this relationship, select the repression arc icon
\includegraphics{../gui/icons/modelview/inhibition_selected}, highlight the CI2 species, and, while holding the mouse button, stretch the repression arc to the PR promoter. Next, double-click on the repression arc to bring up the influence editor. In this editor, customize the stoichiometry of binding to 1, indicating that just one CI dimer is necessary to repress this promoter, and change the repression binding equilibrium to 0.2165.
\begin{center}
\includegraphics[width=160mm]{screenshots/repression}
\end{center}
As mentioned earlier, the PR promoter initiates the production of the CII species. Add the CII species following the steps given earlier for adding a species (be sure to mark that it degrades). Then, highlight the PR promoter and, while holding the mouse button, stretch the production arc to the CII species. Note that the icons selected for this are not important because all arcs from promoters to species are always production arcs.
\begin{center}
\includegraphics[width=160mm]{screenshots/production}
\end{center}
Finally, CII species activates the production of the CI species from the PRE promoter. Promoters do not need to always be drawn. They can also be implicit on an influence. To add an activation arc with an implicit promoter, select the activation arc icon \includegraphics{../gui/icons/modelview/activation_selected}, highlight the CII species, and, while holding the mouse button, stretch the activation arc to the CI species. This creates not only the influence but also a default promoter. Double-click on the activation arc to bring up the influence editor. In this editor, customize the stoichiometry of binding to 1, indicating that just one CII molecule is necessary to activate this promoter, and change the activation binding equilibrium to 0.00161. Finally, click on the Edit Promoter button and change the ID of this promoter to PRE. Also, customize the RNAP binding equilibrium to be 0.01, the basal production rate to be 0.00004, and the activated production rate to be 0.015.
\begin{center}
\includegraphics[width=160mm]{screenshots/activation}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/activated_promoter}
\end{center}
Next, let's go look at some of the other model tabs. Click on the Functions tab. Here one can add/remove/edit definitions for functions. Click on Add Function, and let's create a function to compute the total number of molecules where $x$ is the number of monomers and $y$ is the number of dimers. Let's give this function an ID of total with arguments $x$ and $y$, and a definition of $x + 2 * y$.
\begin{center}
\includegraphics[width=160mm]{screenshots/function}
\end{center}
Click on the Units tab. Unit definitions allow the user to create custom units for use in models. As an example, click Add Unit and enter the ID nanoMole. A unit is defined using pre-defined base units. Click on Add to List and find mole in the Kind combo box, and change the scale to $-9$ to define a nanoMole in terms of moles. The exponent and multiplier are real numbers, and the scale is an integer that specifies the relationship between the derived unit and the base unit using the relation below:
\begin{eqnarray*}
\mathrm{unit} & = & (\mathrm{multiplier} * 10^\mathrm{scale} * \mathrm{baseUnit})^\mathrm{exponent}
\end{eqnarray*}
Follow the same steps to create a unit for microLitre.
\begin{center}
\includegraphics[width=160mm]{screenshots/units}
\end{center}
Next, click on the Schematic tab. Then, click on the Model button to bring up a window of default units for this model. These are the units to be used for various things when no units are provided. For this model, let's make the Substance Units be in nanoMoles, Time Units be in seconds, and Volume Units be in microLitres. The Extent Units indicate the units of change for reactions. Let's make that also be nanoMoles.
\begin{center}
\includegraphics[width=160mm]{screenshots/ModelUnits}
\end{center}
Next, click on the Constants tab. This tab includes the default model generation parameters as well as additional global variables. The model generation parameters are used for default values when creating a reaction-based model from our higher level model. These parameters can be edited by selecting them and entering a new initial value. They should not be removed. Note that new global constants can also be added by the user, if desired.
\begin{center}
\includegraphics[width=160mm]{screenshots/GCMparam}
\end{center}
While you can add a global variable here, the preferred way is to add it on the schematic. Click on the Schematic tab. Select the add variable icon \includegraphics{../gui/icons/modelview/variable_mode_selected}, and click a location to add the variable to the schematic. Then, click on the selection icon
\includegraphics{../gui/icons/modelview/select_mode_selected}, and double click on the variable to open the Parameter Editor. Change the ID to CI\_total, for the total amount of the species CI in both monomer and dimer form. Its units are in nanoMole and it is not constant.
\begin{center}
\includegraphics[width=160mm]{screenshots/parameter}
\end{center}
% Now, let's go to the Assignments tab. This tab includes initial assignments and rules. Initial assignments are used when you want the initial value of a compartment size, species amount or concentration, or parameter to be determined by a mathematical equation rather than a constant. Click on Add Initial, select CI2 as the Symbol, and enter the assignment 5*CI, which causes CI2's initial value to be five times that of CI's initial value. Therefore, if we were to go change CI's initial value, CI2's initial value would also change due to this initial assignment.
% \begin{center}
% \includegraphics[width=160mm]{screenshots/initial}
% \end{center}
Now, let's create a rule to compute the value of CI\_total. There are three types of rules: algebraic, assignment, and rate. Algebraic rules are used to specify relationships that must be maintained. Assignment rules are used to define one variable in terms of a mathematical expression. Finally, rate rules are used to indicate a differential equation to govern the evolution of a variable in terms of a mathematical expression on other variables. To add a rule, select the add rule icon
\includegraphics{../gui/icons/modelview/rule_mode_selected}. In the Rule editor,
select Assignment, select the variable CI\_total, and enter the expression total(CI,CI2). This uses our new function to compute that the amount of CI in total is the number of monomer molecules plus two times the number of dimer molecules.
\begin{center}
\includegraphics[width=160mm]{screenshots/rule}
\end{center}
% The next tab is the properties tab. Here you can specify probabilistic temporal logic properties using \emph{Continuous Stochastic Logic} (CSL) that you wish to check. For example, the property shown,
% Pr\{PF[0,2100](CI>20\}, would ask the analyzer to determine the probability that CI exceeds 20 molecules within 2100 seconds.
% \begin{center}
% \includegraphics[width=160mm]{screenshots/properties}
% \end{center}
Next, let's add a constraint. A constraint is a condition that must be satisfied or simulation should terminate. To add a constraint, select the add constraint icon
\includegraphics{../gui/icons/modelview/constraint_mode_selected}. Add a constraint that states that CI remains less than or equal to 20 molecules as shown below. Add a second constraint that states that CII remains less than or equal to 50 molecules.
\begin{center}
\includegraphics[width=160mm]{screenshots/constraint}
\end{center}
Finally, let's add an event. Events are used to specify discrete state changes. For example, let's describe an event for cell division. Click on the Add Event button, enter the ID CellDivision, trigger true, and delay of 2100. The trigger specifies the condition that should be satisfied to enable this event. In this case, we want it to be enabled initially. The delay indicates the time after which it is enabled that it should execute. Finally, select the Dynamic Process of Symmetric Division. This combination results in a cell division event at 2100 seconds after simulation begins. The event assignments specify the state change(s) for this event. Click on the Add Assignment button and select the CI variable, and enter the assignment CI / uniform(1,2). In other words, the number of molecules is being divided between the two daughter cells with a random distribution. Similarly, add event assignments to divide up CI2 and CII.
\begin{center}
\includegraphics[width=160mm]{screenshots/event}
\end{center}
At this point, you should have a model that looks like the one below (though locations of elements may be different). Now, let's make sure the model is saved by either clicking on the Save icon \includegraphics{../gui/icons/save} or selecting the Save option from the File menu.
\begin{center}
\includegraphics[width=160mm]{screenshots/save}
\end{center}
\section{Analysis Tool}
This section describes how to analyze the model just created. The first step is to create an analysis view. To do this, right-click on the model file and select Create Analysis View. Enter the analysis ID {\tt lambda} or just press enter. At this point, a new analysis view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
\begin{center}
\includegraphics[height=60mm]{screenshots/GCMAnalysis}\\
\includegraphics[width=160mm]{screenshots/analysisView}
\end{center}
In order to perform analysis, the analysis tool first converts the model into a reaction-based model in the \emph{Systems Biology Markup Language} (SBML). There are three different ways to see the reaction-based model that is produced. If GraphViz is installed on your computer, you can select Network for your Simulation Type. Then, either press the Save and Run icon \includegraphics{../gui/icons/run-icon} or select the Save and Run option from the File menu. The result will be a GraphViz window that will open to show the reaction-based model such as the one shown below for our example. If it does not open in GraphViz, make sure that you have files with the {\tt .dot} file extension associated with GraphViz on your computer. You can also view the model in a web browser by selecting Browser for your simulation type. In this case, you should ensure that you have files with the {\tt .xhtml} extension associated with your favorite browser. Finally, you can save the reaction-based model by selecting Model as your simulation type. In this case, you must provide a new model ID. This new model will appear in your project and it can be opened in the Model Editor. Since this model does not include any layout information, you will need to either lay it out by hand or using one of the default layout routines selectable using the Apply Layout icon \includegraphics{../gui/icons/modelview/choose_layout_selected},
\begin{center}
\includegraphics[width=120mm]{screenshots/viewNetwork}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/viewBrowser}
\end{center}
\begin{center}
\includegraphics[width=160mm]{screenshots/reactionModel}
\end{center}
Next, click on the SBML elements tab. This tab allows you to select which SBML model elements to include in your analysis. This includes initial assignments, rules, constraints, and events. Initially, let's only include the rule to compute CI\_total. Uncheck all the other elements.
\begin{center}
\includegraphics[width=160mm]{screenshots/SBMLElements}
\end{center}
Now, go back to the simulation options tab. Here, change the simulation type back to ODE, change the time limit to 2100.0, change the print interval to 10.0, and enter a Simulation ID of {\tt ode}. Then, either press the Save and Run icon \includegraphics{../gui/icons/run-icon} or select the Save and Run option from the File menu.
After the simulation completes, click on the TSD Graph tab. Double-click on the graph to bring up the graph editor.
Open the {\tt ode} simulation, highlight Average, select CI\_total and CII, change the Title to ``ODE Simulation Results'', change the X-Axis Label to ``Time (seconds)'', and change the Y-Axis Label to ``Number of Molecules''.
Press the OK button.
\begin{center}
\includegraphics[width=160mm]{screenshots/odeSim}\\
\includegraphics[width=160mm]{screenshots/odeResults}\\
\includegraphics[width=160mm]{screenshots/odeSimResults}
\end{center}
Graphs can be exported in a variety of formats including:
\begin{itemize}
\item Time series data format (tsd).
\item Comma separated value (csv).
\item Column separated data (dat).
\item Encapsulated postscript (eps).
\item Joint Photographic Experts Group (jpg).
\item Portable document format (pdf).
\item Portable network graphics (png).
\item Scalable vector graphics (svg).
\end{itemize}
In order to export a graph, you can either click on the Export icon \includegraphics{../gui/icons/export} or select one of the graph export options from the File menu. When using the Export icon, the type of file exported will depend on the extension provided to the file name. Click on the Export icon, browse to a location on your file system, and enter the file name of {\tt ode.pdf} to create a PDF file for your graph.
\begin{center}
\includegraphics[height=60mm]{screenshots/exportTSD}
\end{center}
Now, select the Simulation Options tab again, select {\tt Monte Carlo}, change the number of runs to 100, set the simulation ID to {\tt ssa}, and click on the Save and Run icon. Click on the TSD Graph tab. Double-click on the graph to bring up the graph editor. Open the {\tt ssa} simulation directory, and highlight {\tt run-1}. Select CI\_Total and CII, change the title to ``SSA Simulation Results'', change the X-Axis Label to ``Time (seconds)'', and change the Y-Axis Label to ``Number of Molecules''. Press the OK button. Click on the Export icon and enter the file name {\tt ssa-1.pdf}. Repeat these steps to generate graphs for the average ({\tt average.pdf}) and standard deviation ({\tt stddev.pdf}). Note that you can use the ``Deselect All'' button to remove all items from the graph.
\begin{center}
\includegraphics[width=160mm]{screenshots/ssaSim}\\
\includegraphics[width=160mm]{screenshots/ssaResults}\\
\includegraphics[width=160mm]{screenshots/ssaSimResults}
\end{center}
Another way to view simulation results is on the schematic. To do this, click on the schematic tab. At the bottom of the window, select the Choose Simulation button, which brings up a window with all the simulations in this analysis view. Open the {\tt ssa} directory, select {\tt run-1.tsd}, and press OK.
\begin{center}
\includegraphics[width=160mm]{screenshots/chooseSim}
\end{center}
Now, click on the CI species, which brings up the Edit Species window. Select the Appearance tab. Here you can select how you want the species to appear as you playback the simulation. You can have it change color, size, and/or opacity on a gradient. You can also select the range of molecule counts to specify the ends of the gradient(s). Finally, you can indicate that these selections are either for this species or all species in the model. For our example, let's make CI follow a green color gradient, CI2 follow a red color gradient, and CII follow a blue color gradient.
\begin{center}
\includegraphics[width=160mm]{screenshots/editSpeciesAppearance}
\end{center}
Once you have made your selections, you can now play back the simulation. You can either single-step the simulation by pressing the \includegraphics{../gui/icons/modelview/movie/single_step} icon or play continuously by pressing the \includegraphics{../gui/icons/modelview/movie/play} icon. The playback can also be paused by pressing the \includegraphics{../gui/icons/modelview/movie/pause} icon and restarted by pressing the \includegraphics{../gui/icons/modelview/movie/rewind} icon.
\begin{center}
\includegraphics[width=160mm]{screenshots/movieView}
\end{center}
Using the schematic tab, you can also adjust initial values and parameters allowing one to perform simulations to determine the effect of these changes. Clicking on any species, promoter, reaction, or influence brings up the corresponding editor. To change a value, switch the corresponding combo box to modified, which will then allow you to change the value. For example, as shown below, we have reduced the degradation rate for CI to 0.00075. Now, rerun the simulation and observe the change in the simulation data.
\begin{center}
\includegraphics[width=160mm]{screenshots/paramEdit}
\end{center}
In addition to making single changes, you can also sweep a value as shown below. When you click on the Sweep button, it brings up a window where you can select the start value, the stop value, and the step value. Using the values shown below for this example, simulations are generated using degradation rates of 0.001, 0.003, 0.005, and 0.007. The level indicates how the sweep should perform when multiple variables are swept at the same time. Variables at the same level are changed at the same time. Furthermore, all variables on level 2 are stepped through all their values before changing the values of those variables on level 1. After the values on level 1 are changed, the values on level 2 are stepped through all their values again. Rerun the simulation and create a graph that shows the value of CI for each of the different degradation rates.
\begin{center}
\includegraphics[width=160mm]{screenshots/sweep}
%\includegraphics[height=90mm]{screenshots/sweepPR}
\end{center}
The efficiency of simulation can be improved by employing various automatic abstraction techniques. Go back to the Schematic tab and change the degradation rate of CI back to the default value. Also, go to the SBML elements tab and uncheck the rule for CI\_total. To activate abstraction, click on the Simulation Options tab, select Abstraction and change the simulation ID to {\tt abs}. Press the Save and Run icon and note that the simulation time is substantially faster. Plot both the SSA results for CI\_total and CII with the abstraction results for CI (note this is now equivalent to CI\_total after abstraction) and CII.
\begin{center}
\includegraphics[width=160mm]{screenshots/absResults}
\end{center}
One way to understand why abstraction is so much faster is by looking at the complexity of the reaction-based model before and after abstraction. The reaction-based model after abstraction is shown below which is clearly much simpler than the full model shown earlier.
\begin{center}
\includegraphics[width=100mm]{screenshots/viewNetworkAbs}
\end{center}
Next, let's try checking some properties. To do this, go to the SBML Elements tab and check the boxes next to the constraints. Recall that these constraints terminate simulation whenever CI goes above 20 molecules or CII goes above 50 molecules. Go back to the Simulation Options tab and change abstraction back to none, the Simulation Type to Monte Carlo, and Simulation ID to prob, then press the Save and Run icon. Now, let's plot the results on a histogram by clicking on the Histogram tab and then double-clicking on the graph to bring up the histogram graph editor shown below. Open the prob folder, select the sim-rep file, and check the Use check box to get all fields.
\begin{center}
\includegraphics[width=160mm]{screenshots/editProbGraph}
\end{center}
The histogram shown here indicates that CI goes above 20 molecules first about 21 percent of the time, CII goes above 50 molecules first about 74 percent of the time, and the simulation terminates before either happens about 5 percent of the time.
\begin{center}
\includegraphics[width=160mm]{screenshots/probResults}
\end{center}
These results can also be visualized using the TSD graph tool. Click on the TSD graph tab, click on the graph, Deselect All, open the prob folder, select the Percent Termination file, and add both constraints to the graph. The result, shown below is the probability of each constraint terminating the simulation as time evolves.
\begin{center}
\includegraphics[width=160mm]{screenshots/probResultsTSD}
\end{center}
\section{Learn Tool}
This section describes how a model can be learned from time series data using {\tt iBioSim}'s Learn Tool. To demonstrate the Learn Tool, first create a simple model, {\tt lambdaLearn}, which just includes the two species CI and CII as shown below. Next, create a learn view by right-clicking on this model file and selecting Create Learn View. Give this learn view the ID {\tt learnLambda}. At this point, a new learn view should open. You should also notice that an icon appears next to your model file. When you click on this, it will show you all of the analysis and learn views associated with this model.
\begin{center}
\includegraphics[height=60mm]{screenshots/createLearn}
\end{center}
The next step is to add some experimental data from which you wish to learn a model. In this demo, we will just utilize our simulation data as synthetic experimental data. To do this, click Copy From View, and select {\tt lambda/abs}. Highlight {\tt lambda/abs/run-1.tsd} and you should see the simulation data for CI and CII appear on the right in the data editor.
\begin{center}
\includegraphics[width=160mm]{screenshots/dataManager}
\end{center}
Now, click on the Learn tab. Here you can edit the various learning options. For example, you can either use auto-generated levels or user-generated levels for your data encoding. Select Use User Generated Levels, which will make the levels below editable. At this point, you can ask the tool to suggest levels by clicking on the Suggest Levels button. Finally, click on the Save and Run icon which will bring up the model that has been learned from this experimental data using Graphviz's dotty program, and ask you for a model ID for the generated model.
\begin{center}
\includegraphics[width=160mm]{screenshots/learn}
\end{center}
\section{Advanced Modeling}
This section is less detailed than the others but it gives some intuition about modeling using reactions, components, and grids.
%% TODO: Need to add SBOL to tutorial
%It also introduces our preliminary support of the emerging \emph{Synthetic Biology Open Language standard} (SBOL). Let us take the last of these first. An SBOL file includes \emph{Collections} of \emph{DNA Components}. Each DNA component has a unique ID, name, description, type, and a DNA sequence. A DNA component can be a simple sequence feature like a promoter, ribosome binding site, open reading frame (i.e., gene), or terminator. It can also be an annotated DNA sequence that includes several of these individual features, perhaps organized hierarchically. For example, a DNA component may include a promoter followed by a ribosome binding site followed by a open reading frame followed by a terminator. When editing the model, you may have noticed the various SBOL fields. Namely, for a promoter, you can associate both a DNA component to the promoter as well as a terminator for the transcription initiated at this promoter. For a species, you can associate both a DNA component for the open reading frame for the gene that produces this species as well as the ribosome binding site where translation begins for this gene. This SBOL browser is opened by clicking on an Associate SBOL button within either the Species Editor or Promoter Editor. This browser only shows DNA components of the appropriate type. For example, when associating a species to its open reading frame, only DNA components of the open reading frame type are shown. After you have associated all genetically produced species (i.e., CI and CII in our model) and all promoters (i.e., PR and PRE in our model), you can then save the DNA component for your model into your SBOL file. You can also export it into a new or existing SBOL file outside your project.
%
% \begin{center}
% \includegraphics[width=160mm]{screenshots/AssociateSBOL}
% \end{center}
%
First, let's consider an alternative model of CII degradation which we are going to model using chemical reactions. To do this, create a new model named {\tt CII\_degradation}. In this model, create species CII, P1, and CII\_P1, making CII have the input type so that we can connect to it later. Set an initial amount of 35 molecules for P1.
\begin{center}
\includegraphics[width=160mm]{screenshots/P1}
\end{center}
Now, select the Add Reaction icon \includegraphics{../gui/icons/modelview/add_reaction_selected} and click on the schematic canvas to drop a reaction. This creates a reaction with a default ID and parameter values that we can change later, if we wish.
\begin{center}
\includegraphics[width=160mm]{screenshots/reaction}
\end{center}
Now, let's connect up the reactant species. To do this, select the Reaction icon \includegraphics{../gui/icons/modelview/reaction_selected}, select the reactant species CII, and, while holding the mouse button, drag the reaction edge to the reaction R1. Similarly, add P1 as a reactant as well. If you double-click on a reactant edge, it brings up a Reactant editor where you can change the stoichiometry, if desired.
\begin{center}
\includegraphics[width=160mm]{screenshots/reactant}
\end{center}
Connecting product species is accomplished in much the same way, except in this case you select reaction R1 and drag the reaction edge to the product CII\_P1. Again, there is a Product editor for changing the stoichiometry. Note that modifiers (i.e., species that are neither produced nor consumed by a reaction but simply catalyze a reaction) can be added in a similar way using the Modifier icon \includegraphics{../gui/icons/modelview/modifier_selected} instead.
\begin{center}
\includegraphics[width=160mm]{screenshots/product}
\end{center}
Now, let's adjust the parameters for this reaction by clicking on it to open the Reaction Editor. Press the Use Mass Action button to automatically create a kinetic law for this reaction. Then, make this reaction reversible and adjust its forward reaction rate to be 1.0.
\begin{center}
\includegraphics[width=160mm]{screenshots/localParam}
\end{center}
Follow the same steps to add another reaction that degrades CII in the CII\_P1 form and releases the protease molecule P1. This reaction is not reversible and it should have a forward rate of 0.002.
\begin{center}
\includegraphics[width=160mm]{screenshots/kineticLaw}
\end{center}
Let's now go and add this new degradation mechanism to our lambda model (you might actually want to copy your old model before you do this, which you can do by highlighting the file and selecting Edit $\rightarrow$ Copy or using the right mouse button menu). To simplify things, remove the rule, constraints, and event. Next, open the Species Editor on CII and deselect the degrades option. Finally, select the Add Component icon \includegraphics{../gui/icons/modelview/add_component_selected} and click on the Schematic canvas opening the Add Component(s) window. In this window, browse the combo box to find your CII\_degradation model. Pressing OK will then add it to your schematic.
\begin{center}
\includegraphics[width=160mm]{screenshots/addComponent}
\end{center}
Now, let's connect CII to this new component to relate the CII within the component to the outer CII species. To do this, select the CII species and, while holding the mouse button, drag a connection to the component connecting CII to the CII port on the component.
You may want to now go and try simulating this model, if you like.
\begin{center}
\includegraphics[width=160mm]{screenshots/addPort}
\end{center}
In the last example, we will build a model with a grid. First, edit the CII species and make it diffusible, and save the model. Now, create a grid model using the File $\rightarrow$ New $\rightarrow$ Grid Model menu, and name the new model {\tt Population}. In the create grid window shown below, select your copy of your lambda model and change the number of rows and columns to 5.
\begin{center}
\includegraphics[width=60mm]{screenshots/createGrid}
\end{center}
The schematic in a grid model is a bit different. It includes a grid in which each location can be empty or contain exactly one component. Only components can be added to grids.
\begin{center}
\includegraphics[width=160mm]{screenshots/gridModel}
\end{center}
When you create a reaction-based model for a grid during analysis, reactions are created to move the diffusible species between the grid locations to provide a coarse form of spatial modeling. If the component within a grid location is enclosed in a compartment membrane (indicated by the rounded corners), the model generated also includes reactions to diffuse the species in and out of the compartment. In the analysis schematic, you can visualize your grid models by clicking on the component in the grid and selecting the species that you would like to see. For each such species, you can set its color, size, and/or opacity gradient. You can also copy these settings to all like models in your grid. Finally, you can click on the area outside of the component within the grid to allow you to also visualize the species that are in the medium.
\begin{center}
\includegraphics[width=160mm]{screenshots/compAppearances}
\end{center}
%% TODO: Add Petri net modeling
\noindent
A more detailed
%%tth:\begin{html}<a href="iBioSim_Grid_Tutorial.html">\end{html}
grid tutorial
%%tth:\begin{html}</a>\end{html}
is available in the {\tt docs} directory that comes with the distribution.
\end{document}

23
docs/iBioSim_Tutorial.html
View file

@ -14,9 +14,9 @@
<title> iBioSim Version 2.5 \ Tutorial</title>
<title> iBioSim Version 2.7 \ Tutorial</title>
<h1 align="center">iBioSim Version 2.5 <br />Tutorial </h1>
<h1 align="center">iBioSim Version 2.7 <br />Tutorial </h1>
<div class="p"><!----></div>
@ -72,9 +72,7 @@
</ul>
<div class="p"><!----></div>
This tutorial illustrates each of these features of <tt>iBioSim</tt> using a simple model for the <em>cI</em> and <em>cII</em> genes and the P<sub>R</sub> and P<sub>RE</sub> promoters from the phage &#955; decision circuit.
<div class="p"><!----></div>
This tutorial illustrates each of these features of <tt>iBioSim</tt> using a model of the Gardner et al. Genetic Toggle switch.
<div class="p"><!----></div>
<h2><a name="tth_sEc2">
@ -101,7 +99,7 @@ To create a new project, select New &#8594; Project from the File menu as shown
3</a>&nbsp;&nbsp;Model Editor</h2>
<div class="p"><!----></div>
After you have created a project, you can create a new model to add to the project by selecting New &#8594; Model from the File menu as shown below. You will then be prompted to enter a model ID. Enter <tt>lambda</tt>. At this point, a Model editor will open in a new tab.
After you have created a project, you can create a new model to add to the project by selecting New &#8594; Model from the File menu as shown below. You will then be prompted to enter a model ID. Enter <tt>ToggleSwitch</tt>. At this point, a Model editor will open in a new tab.
<div class="p"><!----></div>
@ -129,7 +127,7 @@ Compartments are the membrane-enclosed regions where species can be found and re
<div class="p"><!----></div>
To add a chemical species, select the Add Species icon <img src="../gui/icons/modelview/add_species_selected.png" alt="../gui/icons/modelview/add_species_selected.png" /> and click on the schematic canvas. This will drop a new species with default ID and other values. You may change these defaults by clicking on the selection icon
<img src="../gui/icons/modelview/select_mode_selected.png" alt="../gui/icons/modelview/select_mode_selected.png" />, and
double-clicking on the species to open the Species Editor. In this case, let us change the ID to CI, and click on degrades checkbox. We will leave all other values at their default values. One thing that is important to note is that when this model is analyzed a default degradation reaction will be created which has a rate of 0.0075.
double-clicking on the species to open the Species Editor. In this case, let us change the ID to LacI, and click on the degrades checkbox. We will leave all the other values at their default values. One thing that is important to note is that when this model is analyzed a default degradation reaction will be created which has a rate of 0.0075.
<div class="p"><!----></div>
@ -137,20 +135,15 @@ double-clicking on the species to open the Species Editor. In this case, let us
</center>
<div class="p"><!----></div>
Add another species for the CI dimer molecule. The next step is to add a complex-formation reaction to convert CI monomers into CI dimers. Select the complex formation icon <img src="../gui/icons/modelview/bio_activation_selected.png" alt="../gui/icons/modelview/bio_activation_selected.png" />, highlight the CI species, and, while holding the mouse button, stretch the complex formation arc to the S1 species. Next, edit this species to set its ID to CI2 and select that it degrades. This species is created using a complex-formation reaction with an equilibrium constant of 0.1. Change default to custom for the complex formation equilibrium and set it to this value as shown below.
Repeat the steps above to add TetR and GFP species.
<div class="p"><!----></div>
<center><img src="screenshots/species2.png" alt="screenshots/species2.png" />
</center>
<div class="p"><!----></div>
If you double-click on the complex formation arc, an influence editor will open which indicates that this is a complex formation arc and the stoichiometry of binding (i.e., the number of molecules of the source species used to construct the sink species) is 2. The default in this case is correct as it does take two molecules of CI to make CI2.
<div class="p"><!----></div>
<center><img src="screenshots/complex.png" alt="screenshots/complex.png" />
</center>
<div class="p"><!----></div>
<div class="p"><!----></div>
Next, let's add the PR promoter, which initiates transcription of the gene that produces the protein CII. To do this, select the promoter icon <img src="../gui/icons/modelview/promoter_mode_selected.png" alt="../gui/icons/modelview/promoter_mode_selected.png" /> and click on the schematic canvas to drop the promoter with a default ID and parameter values. Double-click on the promoter to bring up the promoter editor. Change the ID to PR, customize the RNAP binding equilibrium to be 0.69422, and set the open complex production rate to be 0.014.
@ -611,5 +604,5 @@ is available in the <tt>docs</tt> directory that comes with the distribution.
T<sub><font size="-1">E</font></sub>X
by <a href="http://hutchinson.belmont.ma.us/tth/">
T<sub><font size="-1">T</font></sub>H</a>,
version 3.81.<br />On 1 Jun 2013, 15:56.</small>
version 3.81.<br />On 6 Sep 2014, 09:37.</small>
</html>

BIN
docs/iBioSim_Tutorial.pdf
View file

Binary file not shown.