krlhBlupine/iBioSim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iBioSim/docs/ATACS.tex
cjmyers 682a39b3e0 Minor updates.
2011-05-14 20:58:10 +00:00

1577 lines
No EOL
66 KiB
TeX
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

\documentclass[titlepage,11pt]{article}
\textwidth 6.5in
\textheight 9in
\oddsidemargin -0.2in
\topmargin -0.5in
\usepackage{indentfirst,graphics,alltt,epsfig,color}
\title{ATACS User's Manual}
\author{Chris J. Myers, Kevin Jones, Scott Little, Nicholas Seegmiller, Robert Thacker, David Walter}
% \date{Created: February 20th, 2009\\
% Last Revised: February 20th, 2009
% }
\begin{document}
\maketitle
%show only subsection granularity in the toc
%\setcounter{tocdepth}{2}
\tableofcontents
\clearpage
%\setlength{\parindent}{0em}
%\setlength{\parskip}{10pt}
\section{Introduction}
\noindent
LEMA has been developed for the formal verification of analog and mixed-signal (AMS) circuits. LEMA includes the following tools:
\begin{itemize}
\item LHPN Editor - a tool to create a model using the
\emph{labeled hybrid Petri net} (LHPN) format.\\
The LHPN format is described in
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/publications">\end{html}
David Walter and Scott Little's PhD dissertations
%%tth:\begin{html}</A>\end{html}
(UofUtah 2007/2008).
\item Verification tool - a tool to perform model checking on a LHPN model. The tool can use DBM, BDD, or SMT to represent the state space.
These model checkers are described in
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/publications">\end{html}
David Walter and Scott Little's PhD dissertations
%%tth:\begin{html}</A>\end{html}
(UofUtah 2007/2008).
\item Learn tool - a tool to learn a LHPN from simulation data.\\
This tool is described in
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/publications">\end{html}
Scott Little's PhD Dissertation
%%tth:\begin{html}</A>\end{html}
(UofUtah 2008).
\item TSD Graph Editor- a tool to visualize TSD files.
% \item Probability Graph Editor - a tool to visualize probability data.
\end{itemize}
\section{Project Management}
\noindent
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[height=80mm]{screenshots/iBioSim}
\end{center}
\subsection{Creating and Opening Projects}
\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. After you do this,
click the new button and a new project directory will be created.
To open a project, select Open $\rightarrow$ Project from the File menu.
You will then be prompted to browse to a project directory to
open, and clicking open will open the project. You may also open
a project by selecting one of your five most recently opened
projects by selecting the project name shown in the File drop
down menu shown below.
\begin{center}
\includegraphics[height=50mm]{screenshots/project}
\end{center}
\subsection{Creating Models and Graphs}
\noindent
After you have created or opened a project, you can create a
new model or graph to add to the project. To create a new
Genetic Circuit Model (see Section~\ref{GCM}), select
New $\rightarrow$ Genetic Circuit Model from the
File menu as shown below. You will then be prompted to give a model id. At this
point, a GCM editor (see Section~\ref{GCMEdit}) will open in a new
tab. To create a new SBML model, select New $\rightarrow$ SBML Model
from the File menu. You will then be prompted to give a model id.
At this point, an SBML editor (see Section~\ref{SBMLEdit}) will open
in a new tab. To create a new TSD graph, select New $\rightarrow$ TSD Graph
from the File menu. You will then be prompted to give a name to
the TSD graph. At this point, a TSD graph editor (see Section~\ref{TSDEdit})
will open in a new tab. To create a new probability graph, select
New $\rightarrow$ Probability Graph from the File menu. You will then
be prompted to give a name to the probability graph. At this point, a
probability graph editor (see Section~\ref{ProbEdit})
will open in a new tab. Once a model or graph is created, it can
be opened again later by right clicking on the object in the
project window and selecting ``Edit'', or alternatively
double-clicking on the object.
\begin{center}
\includegraphics[height=45mm]{screenshots/newModel}
\end{center}
\subsection{Importing Models}
\noindent
You can import into the current working project GCMs
or SBML Models created by other programs or stored in other projects.
To import a GCM, select Import $\rightarrow$ Genetic Circuit Model
from the File menu as shown below. You will then be able to browse to
find a model to import. After selecting the desired model, click the
import button
to bring the GCM into the project. Before bringing the model into the
project, it will be checked to see if it is a valid GCM file.
To import an SBML model, the procedure is the same except use the
Import $\rightarrow$ SBML Model option. Before bringing the model
into the project, it will be checked to see if it a valid SBML file.
The model will also be checked for consistency, and any errors or
warnings will be reported. These should be corrected before analysis
of the model is performed.
\begin{center}
\includegraphics[height=45mm]{screenshots/import}
\end{center}
\subsection{Editing Project Objects}
\noindent
All project objects can be modified by highlighting the object
and using a right mouse click to open a menu of options as shown
below. Using this menu, every type of object can be copied, renamed, or
deleted. For a GCM, the ``View/Edit'' option opens the
model in a GCM editor (see Section~\ref{GCMEdit}). For an SBML model,
the ``View/Edit'' option opens the model in an SBML editor
(see Section~\ref{SBMLEdit}). For a TSD graph, the ``View/Edit''
option opens the TSD graph in a TSD graph editor (see Section~\ref{TSDEdit}).
For a probability graph, the ``View/Edit'' option opens
the probability graph in a probability graph editor
(see Section~\ref{ProbEdit}).
For an analysis view, the ``Open Analysis View'' option opens the
analysis view (see Section~\ref{Analysis}). For a learn view, the
``Open Learn View'' option opens the learn view (see Section~\ref{Learn}).
\begin{center}
\begin{tabular}{ccc}
\includegraphics[height=65mm]{screenshots/modGCM} & &
\includegraphics[height=65mm]{screenshots/modSBML} \\ \\
\includegraphics[height=35mm]{screenshots/modAnalysis} & &
\includegraphics[height=35mm]{screenshots/modLearn}
\end{tabular}
\end{center}
\subsection{Viewing Project Objects}
\noindent
A GCM can also be viewed using
%%tth:\begin{html}<A HREF="http://www.graphviz.org/">\end{html}
GraphViz's
%%tth:\begin{html}</A>\end{html}
dotty program by right clicking on the model you want to view and
selecting the ``View Genetic Circuit'' option.
There are two additional ways to view an SBML model. You
can either select the ``View Network'' option or the
``View in Browser'' option. The ``View Network''
option converts the model to a GraphViz file and then will open that
file with GraphViz's dotty program. The ``View in Browser'' option
coverts the model to an xhtml file and opens that file with your
default xhtml browser.
\begin{center}
\begin{tabular}{ccc}
\includegraphics[height=65mm]{screenshots/modGCM} & &
\includegraphics[height=65mm]{screenshots/modSBML} \\ \\
\includegraphics[height=35mm]{screenshots/modAnalysis} & &
\includegraphics[height=35mm]{screenshots/modLearn}
\end{tabular}
\end{center}
\subsection{Creating Tool Views}
\noindent
To perform analysis or learning, right click on a model and
select ``Create Analysis View'' (see Section~\ref{Analysis})
to perform analysis or ``Create Learn View'' (see Section~\ref{Learn})
to perform learning. You will then be prompted to give a name to
your analysis or learn view. After a name is entered, a tab with
the newly created view will open. Once a view is created, it can
be opened again later by right clicking on an analysis directory
and selecting ``Open Analysis/Learn View'' or alternatively
double-clicking on the view.
\begin{center}
\begin{tabular}{ccc}
\includegraphics[height=55mm]{screenshots/createAnalysis} & &
\includegraphics[height=55mm]{screenshots/createLearn}
\end{tabular}
\end{center}
When you create an analysis view from a GCM, an SBML model is
automatically created for simulation and analysis. Within the
analysis view, you can edit the initial concentrations and
parameters. However, if you wish to be able to edit the
structure, you should first create an SBML model using Create
SBML Model option in the right click menu or the Save as SBML button in
the GCM Editor (see Section~\ref{GCMEdit}). You can then open and
edit this model using an SBML editor (see Section~\ref{SBMLEdit}) and
create an analysis view from this edited model.
\section{\label{SBMLEdit}SBML Editor}
\noindent
The SBML editor as shown below allows the user to create or modify an SBML
model of a biochemical reaction network. An SBML model includes
compartments (see Section~\ref{compartments}),
species (see Section~\ref{species}),
reactions (see Section~\ref{reactions}),
parameters (see Section~\ref{parameters}),
function definitions (see Section~\ref{funcDefn}),
unit definitions (see Section~\ref{unitDefn}),
compartment types (see Section~\ref{compTypes}),
species types (see Section~\ref{specTypes}),
initial assignments (see Section~\ref{initials}),
rules (see Section~\ref{rules}),
constraints (see Section~\ref{constraints}), and
events (see Section~\ref{events}).
Each of these items can be added, removed, or edited.
To add a new item, click on the appropriate add button. You
will then be prompted to provide a unique id and some properties
for this new item (as described below). After you have filled out
all of the required fields, click add and the new item will be
added to the SBML model.
To remove an item from the model, select that item and click
the remove button. The item will then be removed from the model.
However, if you try to remove an item that is being used
(for example, a species that is used in a reaction), you will first have
to remove its use.
To edit an existing item, select that item from the list and
click the edit button. An editing window will open and you will
be able to change the properties of that item. When you are done
editing this item, click save to save the changes to the item.
After the model is complete, press the Save SBML button to store
the model. The Save and Check SBML button also saves the model, but
in this case it also checks the models consistency.
Note that many checks are done on the fly, so it should be difficult
to create models with consistency problems. However, if a user does
not wish to be warned about undeclared units or does not wish to have
units checked at all can set preferences to turn this off
(see Section~\ref{Preferences}). The Save and Check SBML button
though will still present all the unit warnings and errors.
Finally, the Save As button can also be used to store the
model, but in this case, a new model ID will be requested and the
model will be saved using that ID.
\begin{center}
\includegraphics[height=90mm]{screenshots/SBMLedit}
\end{center}
\subsection{\label{SBMLMath}SBML Math Formulas}
\noindent
Math formulas appear in many SBML constructs. These formulas are
expressed as text strings using a simple C-like syntax.
SBML math formulas can include:
\begin{itemize}
\item Variables (compartment, species, parameter IDs, and reaction IDs)
\item Real Numbers
\item Built-in constants: exponentiale, pi, 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 (x\^{}y) which is equivalent to pow(x,y).
\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.
\item Unary functions: abs, ceiling, exp, factorial, floor, ln, log,
sqr, and sqrt.
\item Trigonometric functions: cos, cosh, sin, sinh, tan, tanh, cot,
coth, csc, csch, sec, sech, arccos, arccosh, arcsin, arcsinh,
arctan, arctanh, arccot, arccoth, arccsc, arccsch, arcsec, and arcsech.
\item The delay(expr1,expr2) function which returns the value of expr1 at a time
expr2 time units earlier (not currently supported by analysis).
\item The piecewise(value1, case1, value2, case2, ..., otherwise)
function returns value1 if case1 is true, value2 if case2 is true,
etc. If no cases are true, it returns otherwise value.
\end{itemize}
{\tt iBioSim}'s simulators also support several random functions which
are added by default to any SBML file created with its SBML editor.
The following random functions, therefore, can also be used in SBML
math formula:
\begin{itemize}
\item Continuous random functions: uniform(a,b), normal(m,s), exponential(mu),
gamma(a,b), lognormal(z,s), chisq(nu), laplace(a), cauchy(a), and
rayleigh(s).
\item Discrete random functions: poisson(mu), binomial(p,n), and bernoulli(p).
\end{itemize}
\subsection{\label{MainElem}Main Elements}
\noindent
This Main Elements tab shown below is used to specify
compartments (see Section~\ref{compartments}),
species (see Section~\ref{species}),
reactions (see Section~\ref{reactions}), and
parameters (see Section~\ref{parameters}).
This tab also includes the Model ID which is fixed to be the same as
the filename as well as the Model Name which can be used to provide an
arbitrary string description of the model.
\begin{center}
\includegraphics[height=80mm]{screenshots/mainElem}
\end{center}
\subsubsection{\label{compartments}Compartments}
\noindent
Compartments are used to specify locations where species are
found. Every model must include at least one compartment. A new
model includes a compartment named ``default'' that
cannot be removed unless a new compartment is provided.
A compartment to which species have been assigned also cannot be removed.
As shown below, a compartment has the following fields:
\begin{itemize}
\item ID: a unique ID composed of only alphanumeric characters and
underscores.
\item Name: an arbitrary string description (optional).
\item Type: selected from the list of compartment types (default=none).
\item Dimensions: number of spatial dimensions (default=3).
\item Outside: the compartment that is outside this compartment
(default=none).
\item Constant: Boolean indicating if the size is constant
(default=true).
\item Size: initial size of the compartment (default=1.0).
\item Units: the units for the size (default=none).
\end{itemize}
\begin{center}
\includegraphics[height=80mm]{screenshots/compartment}
\end{center}
\subsubsection{\label{species}Species}
\noindent
Species are the molecules that appear as reactants, products, or modifiers
in the reactions in the biochemical reaction network.
As shown below, a species has the following fields:
\begin{itemize}
\item ID: a unique ID composed of only alphanumeric characters and
underscores.
\item Name: an arbitrary string description (optional).
\item Type: selected from the list of species types (default=none).
\item Compartment: location of the species (default=default).
\item Boundary Condition: Boolean indicating if the species
amount/concentration
cannot be changed by reactions (default=false).
\item Constant: Boolean indicating if the species amount/concentration
is constant (default=false).
\item Initial Amount/Concentration: initial value of the amount or
concentration of the species. Whether it is an amount or concentration
can also be selected (default=amount/0.0).
\item Units: the units for the amount/concentration (default=none).
\end{itemize}
\begin{center}
\includegraphics[height=65mm]{screenshots/species}
\end{center}
\subsubsection{\label{reactions}Reactions}
\noindent
Reactions are used to create or destroy molecular species in a
biochemical reaction network. As shown below, a
reaction is composed of the following:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and
underscores.
\item Name: an arbitrary string description (optional).
\item Reversible: a Boolean indicating if the reaction is reversible
(default=false).
\item Fast: a Boolean indicating if the reaction is fast (default=false).
\item List of Reactants: species that are consumed by this reaction.
\item List of Products: species that are produced by this reaction.
\item List of Modifiers: species that are neither produced or consumed
by this reaction.
\item List of Local Parameters: symbolic values that can be used in
the kinetic law or stoichiometry math formulas for this reaction.
\item Kinetic law: an SBML math formula (see Section~\ref{SBMLMath})
describing the rate or probability for this reaction.
\end{itemize}
When adding a reactant or product, the user must specify a species ID and
the stoichiometry (i.e., the number of molecules produced or consumed by the
reaction). The stoichiometry can also be expressed as a stoichiometry math
formula. Each parameter is composed of an ID, Name, Value, and Units.
The list of parameters begins with a default forward
reaction rate (kf) and reverse reaction rate (kr). These names
and their values should likely be edited. The kinetic law can
either be automatically generated using the Use Mass Action
button or manually entered. The
``Use Mass Action'' button creates a rate law using the
law of mass action. It assumes that the first parameter in the
list is the forward reaction rate and the second parameter in the
list is the reverse reaction rate.
The ``Clear'' button clears the kinetic law editor.
The stoichiometry math and kinetic law formulas can only include
those species that appear as reactants, products, or modifiers.
\begin{center}
\includegraphics[height=70mm]{screenshots/reaction}
\begin{tabular}{cc}
\includegraphics[height=35mm]{screenshots/reactant} &
\includegraphics[height=35mm]{screenshots/product}
\end{tabular}
\includegraphics[height=35mm]{screenshots/localParam}\\
\includegraphics[height=35mm]{screenshots/kineticLaw}
\end{center}
\subsubsection{\label{parameters}Global Parameters}
\noindent
Global parameters are variables that can
be used in SBML math formulas (see Section~\ref{SBMLMath}).
As shown below, a parameter includes the following:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and
underscores.
\item Name: an arbitrary string description (optional).
\item Value: initial value for the parameter.
\item Units: the units for the parameter value (default=none).
\item Constant: Boolean indicating if the parameter value
is constant (default=true).
\end{itemize}
\begin{center}
\includegraphics[height=60mm]{screenshots/parameter}
\end{center}
\subsection{\label{DefnTypes}Definitions/Types}
\noindent
The Definitions/Types tab shown below allows users to provide
function definitions (see Section~\ref{funcDefn}),
unit definitions (see Section~\ref{unitDefn}),
compartment types (see Section~\ref{compTypes}), and
species types (see Section~\ref{specTypes}).
\begin{center}
\includegraphics[height=80mm]{screenshots/DefnTypes}
\end{center}
\subsubsection{\label{funcDefn}Function Definitions}
\noindent
Function definitions are used to create user defined functions that
can then be used in SBML math formulas (see Section~\ref{SBMLMath}).
As shown below, function definitions include an ID, an optional name field, a
comma-separated list of arguments, and its definition. The definition
is an SBML math formula though it is restricted to only use variable
names which are arguments to the function. While functions can
call other functions, they cannot be recursive (i.e., call themselves)
either directly or indirectly (i.e., through a cycle of function calls).
As mentioned earlier, several random functions supported by
{\tt iBioSim}'s simulators are added automatically.
\begin{center}
\includegraphics[height=70mm]{screenshots/function}
\end{center}
\subsubsection{\label{unitDefn}Unit Definitions}
\noindent
Unit definitions are used to construct user-defined units which are
derived from the set of base units. As shown below, a
unit definition includes an ID,
an optional name, and a list of units that define it. There are
buttons to add, remove, and edit elements in the list of units.
Each unit is composed of a kind, exponent, scale, and multiplier. The kind
is selected from the list of base units in the table below:
\begin{center}
\begin{tabular}{|c|c|c|c|c|c|}
\hline
ampere & gram & katal & metre & second & watt \\ \hline
bacquerel & gray & kelvin & mole & siemens & weber \\ \hline
candela & henry & kilogram & newton & sievert & ~\\ \hline
coulomb & hertz & litre & ohm & steradian & ~\\ \hline
dimensionless & item & lumen & pascal & tesla & ~\\ \hline
farad & joule & lux & radian & volt & ~\\ \hline
\end{tabular}
\end{center}
The exponent and scale are integers, and the multiplier is a real
number 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*}
\begin{center}
\includegraphics[height=75mm]{screenshots/units}
\end{center}
\subsubsection{\label{compTypes}Compartment Types}
\noindent
Compartment types are used to relate multiple compartments. As shown
below, a compartment type includes an ID and an optional name field.
\begin{center}
\includegraphics[height=50mm]{screenshots/compType}
\end{center}
\subsubsection{\label{specTypes}Species Types}
\noindent
Species types are used to relate multiple species. As shown below, a
species type includes an ID and an optional name field.
\begin{center}
\includegraphics[height=50mm]{screenshots/specType}
\end{center}
\subsection{\label{InitRuleConstEvent}Initial Assignments/Rules/Constraints/Events}
\noindent
The {\tt Initial Assignments/Rules/Constraints/Events}
tab as shown below allows users to provide initial assignments
(see Section~\ref{initials}),
rules (see Section~\ref{rules}),
constraints (see Section~\ref{constraints}), and
events (see Section~\ref{events}).
\begin{center}
\includegraphics[height=80mm]{screenshots/IRCE}
\end{center}
\subsubsection{\label{initials}Initial Assignments}
\noindent
Initial assignments as shown below are used to provide an SBML math formula
(see Section~\ref{SBMLMath}) that is evaluated at time 0 to determine
the initial value of a compartment size, species amount or
concentration, or parameter. The value of this formula takes precedence over
the initial value specified in the object.
\begin{center}
\includegraphics[height=40mm]{screenshots/initial}
\end{center}
\subsubsection{\label{rules}Rules}
\noindent
There are three types of rules: algebraic, assignment, and rate rules
which are in the following form:
\begin{center}
\begin{tabular}{|c|c|c|}
\hline
Algebraic & left-hand side is zero & $0 = f(W)$ \\ \hline
Assignment & left-hand side is a scalar & $x = f(W)$ \\ \hline
Rate & left-hand side is a rate-of-change & $\frac{dx}{dt} = f(W)$
\\ \hline
\end{tabular}
\end{center}
Algebraic rules specify relationships which must be maintained
(not currently supported by analysis). Assignment rules specify
the value of a compartment size, species amount or concentration, or
parameter in terms of an SBML math formula (see
Section~\ref{SBMLMath}). A variable cannot be determined by
both an assignment rule and initial assignment. Rate rules specify
the rate of change of a compartment size, species amount or
concentration, or parameter in terms of an SBML math formula
(see Section~\ref{SBMLMath}). A variable cannot be determined
by both an assignment rule and a rate rule. A species that is
a reactant or a product of any reaction cannot be updated by either
an assignment rule or rate rule.
When adding a rule, the user first selects the type of rule as shown
below. This
will automatically restrict the set of variables available for the
left-hand side to those that are valid. The user should then select
a variable, and enter an SBML math formula (see Section~\ref{SBMLMath})
for the rule. When editing a rule, the user cannot modify the rule type.
\begin{center}
\includegraphics[height=40mm]{screenshots/rule}
\end{center}
\subsubsection{\label{constraints}Constraints}
\noindent
Constraints are used to specify properties that should cause
simulation to terminate. Our analysis method can provide histograms
that show the proportion of simulations that are terminated due to each
possible constraint. As shown below,
each constraint is composed of an ID which is
used to identify it in these histograms, a constraint given as an
SBML math formula (see Section~\ref{SBMLMath}), and a message
describing the constraint. A default id is automatically generated
when a new constraint is created.
\begin{center}
\includegraphics[height=30mm]{screenshots/constraint}
\end{center}
\subsubsection{\label{events}Events}
\noindent
Events are used to specify discrete changes of compartment sizes,
species amounts or concentrations, and parameter values.
As shown below, each event
is composed of an ID, an optional name, a trigger formula, an optional
delay formula, and a list of event assignments. When adding a new
event, a default ID is provided. The behavior of an event is that during
each simulation cycle, the trigger formula is evaluated. If it was false
in the previous simulation cycle, and it is now evaluating to true,
the event is scheduled to occur at a time in the future specified by
the delay formula or immediately if no delay formula is provided.
It should be noted that since the trigger value must change from false
to true, no event is scheduled if the trigger evaluates to true at the
start of simulation. When an event occurs, it executes all the event
assignments. Each event assignment sets a compartment size, species
amount or concentration, or parameter value to the value specified by
the SBML math formula (see Section~\ref{SBMLMath}) provided with the event
assignment.
\begin{center}
\includegraphics[height=95mm]{screenshots/event}
\end{center}
\clearpage
\section{\label{GCMEdit}GCM Editor}
\noindent
The GCM editor shown below allows the user to create or modify a GCM
(see Section~\ref{GCM}). A GCM is a compact graphical representation
of a genetic circuit which can later be synthesized into an SBML model.
A GCM includes promoters (see Section~\ref{Promoters}),
GCM species (see Section~\ref{GCMSpecies}),
influences (see Section~\ref{Influences}),
GCM parameters (see Section~\ref{GCMParameters}), and an optional
SBML file. GCM species, influences,
and promoters can be added, removed, or edited. Parameters can only be edited.
An SBML file can also be selected to merge with the SBML generated from a GCM.
This allows either customization of the SBML model or the addition of SBML
constructs such as Initial Assignments, Rules, Constraints,
and Events (see Section~\ref{InitRuleConstEvent}).
\begin{center}
\includegraphics[height=80mm]{screenshots/GCMedit}
\end{center}
To add a new item to the GCM, click on the appropriate add button. You
will then be prompted to input information regarding the new
item. After you have filled out the required fields, click on ok
and the new item will be added into the GCM.
To remove an item from the GCM, select that item and click the
remove button. The item will then be removed from the GCM.
However, if you try to remove species or promoters that are used in
an influence, you will first have to remove the influence in
order to remove the species or promoter from the model.
To edit an existing item, select that item from the list and
click the edit button. An editing window will open and you will
be able to change the properties of that item. When you are done
editing this item, click save to save the changes to the item.
To merge an existing SBML file with the GCM output, click on
the SBML file and select the SBML file to use. This will merge
the contents of the selected SBML file with the SBML file that is
generated from the GCM. Finally, there are two abstractions that can
be selected to be performed when generating SBML, the biochemical and
dimerization abstractions.
Once a GCM is completed, the user can save the GCM or save the GCM
using a new name. The user can also save the GCM as SBML which creates
an SBML file of the same name as the GCM. Finally, the user can save
an SBML template which creates a blank SBML file with the same species
as the GCM. This is useful for creating an SBML file which will be
attached to the GCM, and includes rules, constraints, or events.
\subsection{\label{Promoters}Promoters}
\noindent
Promoters are special species which represent the region of the DNA
from which transcription is initiated.
When adding or editing promoters, the user must supply a unique ID.
An optional name can also be provided which is an arbitrary string
description for the promoter.
If desired, the user can then modify the initial promoter count (ng),
the RNAP binding equilibrium (Ko),
the open complex production rate (ko),
the stoichiometry of production (i.e., the number of transcripts
per mRNA, np), the basal production rate (kb), or
the activated production rate (ka).
\begin{center}
\includegraphics[height=70mm]{screenshots/promoter}
\end{center}
\subsection{\label{GCMSpecies}GCM Species}
\noindent
GCM species are the molecules (usually proteins) produced by genes.
When adding or editing a species, the user must provide a unique ID.
The user can also select the type of the species to be normal, constant,
or unconstrained.
A normal species will result in gene production and degradation reactions
being produced. A constant species will not generate any
production or degradation reactions. An unconstrained species will
produce a constant production and degradation reaction.
The user can also specify an initial species count (ns), a
Dimerization equilibrium (Kd), and a degradation rate (kd).
\begin{center}
\includegraphics[height=60mm]{screenshots/GCMspecies}
\end{center}
\subsection{\label{Influences}Influences}
\noindent
Influences describe the relationships between the GCM species.
When adding or editing an influence, the user must select an
input and output species, as well as the type of influence. If
the type is repression, then the input species represses the
production of the output species. If the type is activation, then
the input species activates the production of the output species.
The user can also specify whether the influence has a promoter.
If a promoter is selected, then this groups all influences using
the same promoter together.
\begin{center}
\includegraphics[height=80mm]{screenshots/influence}
\end{center}
For example, if there are two influences:\\
A $-|$ C, Promoter P1\\
B $-|$ C, Promoter P2\\
this will create two reactions, where in the presence of A and
B, C is repressed. This would behave roughly like a NAND gate.
If, on the other hand, there are two influences:\\
A $-|$ C, Promoter P1\\
B $-|$ C, Promoter P1\\
this creates one reaction, where in the presence of A or
B, C is repressed. This would behave roughly like a NOR gate.
Users can also specify if the influence is a biochemical
influence. A biochemical influence requires all input species
belonging to the same promoter to be present in order to affect
transcription.
For example, if there are two biochemical influences:\\
A $+|$ C, Promoter P1\\
B $+|$ C, Promoter P1\\
this will create two reactions, A and B combines into a
complex, and the complex represses the production of C. This is a
NAND gate. If, on the other hand, if biochemical is not selected,
this behaves as a NOR gate.
The user can also set the value for degree of cooperativity (nc)
which is the number of binding sites for transcription factors.
The N-mer as transcription factor (nd) field determines how many
monomers of the input species
must be bound together in order to affect transcription. The user
can also set the value of the repression or activation binding equilibrium
(Kr and Ka). Finally, the user can specify the biochemical equilibrium
(Kb).
\subsection{\label{GCMParameters}GCM Parameters}
\noindent
GCM parameters are a list of global parameters that are used
when generating the SBML model for the GCM. The parameter list
allows the user an easy way to change all the parameter values in
a convenient location. If a parameter in the GCM is set to
default, it will use the value found in the GCM parameter list.
These defaults can be modified in the user preferences
(see Section~\ref{Preferences}). The GCM parameters are listed below:
\begin{center}
\begin{tabular}{|c|c|c|c|c|}
\hline
ID & Default Value & Units & Structure & Description \\ \hline \hline
nr & 30 & molecule & model & Initial RNAP count \\ \hline
ns & 0 & molecule & species & Initial species count \\ \hline
Kd & 0.05 & $\frac{1}{\mathrm{molecule}}$ & species
& Dimerization equilibrium\\ \hline
kd & 0.0075 & $\frac{1}{\mathrm{sec}}$ & species
& Degradation rate \\ \hline
ng & 2 & molecule & promoter & Initial promoter count \\ \hline
np & 10 & molecule & promoter & Stoichiometry of
production \\ \hline
nc & 2 & molecule & promoter & Degree of cooperativity \\ \hline
Ko & 0.033 & $\frac{1}{\mathrm{molecule}}$ & promoter
& RNAP binding equilibrium\\ \hline
ko & 0.05 & $\frac{1}{\mathrm{sec}}$ & promoter
& Open complex production rate \\ \hline
kb & 0.0001 & $\frac{1}{\mathrm{sec}}$ & promoter
& Basal production rate \\ \hline
ka & 0.25 & $\frac{1}{\mathrm{sec}}$ & promoter
& Activated production rate\\ \hline
nd & 1 & molecule & influence & N-mer as transcription
factor \\ \hline
Kr & 0.5 & $\frac{1}{\mathrm{molecule}^{nc}}$ & influence
& Repression binding equilibrium \\ \hline
Ka & 0.0033 & $\frac{1}{\mathrm{molecule}^{(nc+1)}}$ & influence
& Activation binding equilibrium \\ \hline
Kb & 0.05 & $\frac{1}{\mathrm{molecule}}$ & influence
& Biochemical equilibrium \\ \hline
\end{tabular}
\end{center}
\begin{center}
\includegraphics[height=70mm]{screenshots/GCMparam}
\end{center}
\clearpage
\section{\label{Analysis}Analysis View}
\noindent
The analysis view is used to analyze biochemical reaction
network models. The analysis view as shown below includes tabs for
simulation options (see Section~\ref{simOptions}),
abstraction options (see Section~\ref{absOptions}),
%% advanced options (see Section~\ref{advOptions}),
a parameter editor (see Section~\ref{paramEdit}),
a TSD graph editor (see Section~\ref{TSDEdit}), and a
probability graph editor (see Section~\ref{ProbEdit}).
\begin{center}
\includegraphics[height=80mm]{screenshots/analysisView}
\end{center}
\subsection{\label{simOptions}Simulation Options}
\noindent
iBioSim comes with a number of simulation methods, ranging
from continuous-deterministic simulation methods to
discrete-stochastic simulation methods. In order to perform
efficient temporal behavior analysis, various model abstraction
can also be automatically applied. These routines are implemented
within the reb2sac tool described in
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/publications">\end{html}
Kuwahara's PhD Dissertation (UofUtah 2007)
%%tth:\begin{html}</A>\end{html}
.
The first set of radio buttons in this tab specifies the
levels of abstraction. ``None'' means to use no abstraction,
``Abstraction'' means to perform reaction-based abstraction, and
``Logical Abstraction'' means to perform both reaction-based and
logical abstractions.
The second set of radio buttons specify the type of analysis.
``ODE'' is for continuous-deterministic simulation,
``Monte Carlo'' is for discrete-stochastic simulation,
``Markov'' performs temporal probability distribution
analysis on finite-state Markov chain models, ``sbml''
outputs the model in SBML format, ``Network'' outputs the
structure of the model in the GraphViz format for display by dotty,
``Browser'' outputs the model in xhtml format for display
in a web browswer.
The last set of radio buttons asks if you want to ``Overwrite''
the simulation runs or if you want to ``Append'' more
simulation runs.
If you have not yet performed any simulation, this option is disabled.
The next field specifies the simulation method you want to use
based on the simulation type you specified. The methods available
are:
\begin{center}
\begin{tabular}{|c|c|l|}
\hline
Type & Method ID & Description \\ \hline \hline
ODE & Euler & The forward Euler Method \\ \hline
ODE & gear1 & Gear Method M=1 \\ \hline
ODE & gear2 & Gear Method M=2 \\ \hline
ODE & rk4imp & Implicit 4th order Runge-Kutta at Gaussian points \\ \hline
ODE & rk8pd & Embedded Runge-Kutta Prince-Dormand (8,9) method \\ \hline
ODE & rkf45 & Embedded Runge-Kutta-Fehlberg (4, 5) method \\ \hline
Monte carlo & Gillespie & Gillespie's SSA direct method \\ \hline
Monte carlo & emc-sim & Use jump count as next reaction time \\ \hline
Monte carlo & bunker & Uses mean for next reaction time \\ \hline
Monte carlo & nmc & Uses normally distributed next reaction time
\\ \hline
\end{tabular}
\end{center}
There are some properties that need to be set for simulation.
The table below specifies these:
\begin{center}
\begin{tabular}{|l|l|}
\hline
Field & Description \\ \hline \hline
Time Limit & The simulation time limit \\ \hline
Print Interval & The print time interval for each simulation run \\ \hline
Maximum Time Step & The maximum time step allowed \\
~ & (also minimum time step for the Euler method) \\ \hline
Absolute Error & Used by the adaptive time step ODE methods \\ \hline
Random Seed & An integer number as a seed to generate random
numbers \\ \hline
Runs & The number of Monte Carlo simulation runs to
perform \\ \hline
Simulation ID & Creates a simulation directory with the ID name \\ \hline
\end{tabular}
\end{center}
% <!--
% <H2><A NAME="USERDEFN"></A>User Defined Data File</H2>
% <P>This can deterministically specify how the state of a species
% should change at some specified time point during a simulation
% using Gillespie’s SSA. When "Use User Defined Data"
% is selected, you may add a new data point, edit a data point,
% remove a data point, or clear all data points. Each data point is
% composed of a time to make the change, the species to change, how
% it should change, and the value for the change. The change type
% can be "goes to" which sets the species to the value at
% the specified time point, "is added by" which adds the
% specified value to the species, "is subtracted by"
% which subtracts the specified value from the species, "is
% multiplied by" which multiplies the species value by the
% specified value, and "is divided by" which divides the
% species value by the specified value.
%
% -->
\subsection{\label{absOptions}Abstraction Options}
\noindent
This tab as shown below allows the user to set the properties of rapid
equilibrium, QSSA, and operator site abstraction methods.
\begin{itemize}
\item Rapid Equilibrium Condition 1 specifies threshold T1 such that the rapid
equilibrium condition fails when $T1 > E0 / (S0 + k-1/k1)$.
\item Rapid Equilibrium Condition 2 specifies threshold T2 such that the rapid
equilibrium condition fails when $T1 > k2 /k-1$.
\item The QSSA condition specifies threshold T used by
the QSSA abstraction method where $T > E0 / (S0 + KM)$.
\item The Max concentration threshold specifies the maximum
number of molecules that a species can have initially and still
be considered an operator site by the operator site reduction.
This tab also allows the user to select the interesting species.
Interesting species are the ones that are used in the
analysis, and hence are those which should never be abstracted away.
This tab shows all available species, and to make a species (or set of
species) interesting, highlight the species and press the Add Species
button. There is also a button to remove interesting species and to clear
all interesting species.
\end{itemize}
\begin{center}
\includegraphics[height=80mm]{screenshots/absOptions}
\end{center}
% <!--
% <H2><A NAME="TERMCOND"></A>Termination Conditions</H2>
% <P>The
% termination conditions specify a condition upon which a
% simulation should terminate. A record is kept of the proportion
% of simulations that are terminated by each condition. These
% conditions are specified using an ID, description, and the
% logical condition which when it holds results in termination of
% the simulation/analysis procedure. The logical condition is
% composed of comparative expressions joined by Boolean connectives
% AND (&amp;&amp;), OR (||), and NOT (!). Each comparative
% expression compares two numerical expressions using the
% comparison operators, "&lt;=", "&lt;", "&gt;=",
% "&gt;", and "=". Each numerical expression
% can be composed of variables and real valued constants which are
% combined with the arithmetic operators for addition (+),
% subtraction (-), multiplication (*), and division (/). There is
% also function support for exponentiation (exp(num_exp)), raising
% to a power (pow(num_exp,num_exp)), and natural logarithm
% (log(num_exp)). The variables can represent time (t), the
% molecular count of a species (&lt;species-id&gt; or
% #&lt;species-id&gt;), the concentration of a species
% (%&lt;species-id&gt;), or the number of firings of a reaction
% (@&lt;reaction-id&gt;).
%
% -->
% \subsection{\label{advOptions}Advanced Options}
% Here, you can specify additional options for your analysis.
% For each option, you must provide the name of the option and its
% value.
% % <!-- For example, property
% % <I>reb2sac.abstraction.method.1.x</I>&nbsp; specifies a list of
% % abstraction methods used for pre-processing, property
% % <I>reb2sac.abstraction.method.2.x </I>specifies a list of
% % abstraction methods used in the main abstraction loop, and&nbsp;
% % property <I>abstraction.method.3.x</I> is a list of abstraction
% % methods used for post-processing.&nbsp; These abstraction method
% % properties can take the following values:
% %
% % \begin{itemize}
% % <LI><P STYLE="margin-bottom: 0in">modifier-structure-transformer
% %
% % <LI><P STYLE="margin-bottom: 0in">modifier-constant-propagation
% %
% % <LI><P STYLE="margin-bottom: 0in">operator-site-forward-binding-remover
% %
% % <LI><P STYLE="margin-bottom: 0in">nary-order-unary-transformer2
% %
% % <LI><P STYLE="margin-bottom: 0in">kinetic-law-constants-simplifier
% %
% % <LI><P STYLE="margin-bottom: 0in">enzyme-kinetic-rapid-equilibrium-1
% %
% % <LI><P STYLE="margin-bottom: 0in">dimer-to-monomer-substitutor
% %
% % <LI><P STYLE="margin-bottom: 0in">dimerization-reduction
% %
% % <LI><P STYLE="margin-bottom: 0in">kinetic-law-constants-simplifier
% %
% % <LI><P STYLE="margin-bottom: 0in">irrelevant-species-remover
% %
% % <LI><P STYLE="margin-bottom: 0in">inducer-structure-transformer
% %
% % <LI><P STYLE="margin-bottom: 0in">final-state-generator
% %
% % <LI><P STYLE="margin-bottom: 0in">similar-reaction-combiner
% %
% % <LI><P STYLE="margin-bottom: 0in">absolute-inhibition-generator
% %
% % <LI><P STYLE="margin-bottom: 0in">reversible-to-irreversible-transformer
% %
% % <LI><P STYLE="margin-bottom: 0in">multiple-products-reaction-eliminator
% %
% % <LI><P STYLE="margin-bottom: 0in">multiple-reactants-reaction-eliminator
% %
% % <LI><P STYLE="margin-bottom: 0in">single-reactant-product-reaction-eliminator
% %
% % <LI><P STYLE="margin-bottom: 0in">stop-flag-generator
% %
% % <LI><P STYLE="margin-bottom: 0in">enzyme-kinetic-qssa-1
% %
% % <LI><P STYLE="margin-bottom: 0in">birth-death-generator4
% %
% % <LI><P STYLE="margin-bottom: 0in">max-concentration-reaction-adder
% %
% % \item dummy-abstraction-method
% %
% % \end{itemize}
% % <P>
% % -->
% On this tab, there are buttons to add a new option, edit an
% existing option, remove an existing option, or clear all options.
\subsection{\label{paramEdit}Parameter Editor}
\noindent
The parameter editor as shown below is similar in form to the SBML editor,
but it only allows initial concentrations and parameters to be
adjusted. Each of these parameters starts with the original value
specified in the SBML or GCM associated with
this analysis view. By changing the type to ``Custom'', a
new value can be entered. Changing the type back to ``Original'',
restores the original value. These values can also be swept by
selecting the ``Sweep'' type. In this case, you should
provide a start value, a stop value, a step amount, and a level
(1 or 2). When analyzing using sweep parameters, one analysis run
is produced for each value stepped through from start to stop.
The parameters at level 2 are changed first. When they have all
reached their stop value, the parameters at level 1 are stepped
once, and the parameters at level 2 are stepped through again.
This process repeats until all parameters at level 1 have stepped
to their stop value.
\begin{center}
\includegraphics[height=80mm]{screenshots/paramEdit}
\end{center}
\section{\label{Learn}Learn View}
\noindent
The learn view is used to discover genetic circuit
connectivity from time series data. The learn view includes tabs
for a data manager (see Section~\ref{dataManager}),
a learn tool (see Section~\ref{learnTool}), and a
TSD graph editor (see Section~\ref{TSDEdit}).
\subsection{\label{dataManager}Data Manager}
\noindent
The data manager as shown below is used to both enter time series
experimental data as well as bring data
into the learn view. The Add button is used to create a new data
file. After pressing this button, enter the name of the new data
file, and then enter the data for this file using the data editor
to the right. The Remove button deletes all highlighted files.
Note that after highlighting one file, you can use the ctrl key
to highlight additional files or the shift key to highlight a
range of files. The Rename button is used to change the name of a
data file. The Copy button copies a data file. The Copy From View
button brings up a list of all analysis and learn views in the
current project, and data from the selected view will be copied
into this learn view. Finally, the Import button brings up a file
browser, and it allows you to import a data file from outside
this project. These files can be in time series data (TSD) format
(see Section~\ref{TSD}), comma separated value (CSV) format, or tab
delimited format (DAT).
The contents of the data file highlighted on the left appear in the
data editor on the right. Individual data entries can be modified,
new data points can be added using the Add Data Point button, data
points can be removed using the Remove Data Point button, and data
points can be copied using the Copy Data Point button. When you are
satisfied with all your changes, you should press the Save button
to record your changes.
\begin{center}
\includegraphics[height=85mm]{screenshots/dataManager}
\end{center}
\clearpage
\subsection{\label{learnTool}Learn Tool}
\noindent
The learn tool shown below uses the GeneNet algorithm described in
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/publications">\end{html}
Barker's PhD dissertation (UofUtah 2007)
%%tth:\begin{html}</A>\end{html}
. To use this learn tool, adjust
any options described below, if desired, then press the Save and
Learn button. The resulting genetic circuit is specified using
our Genetic Circuit Model (GCM) Format (see Section~\ref{GCM}) and is shown
graphically using GraphViz's Dotty tool. On this tab, there are also
buttons to save the parameters without learning, view the last learned
circuit, save the generated circuit into the project, and view the last run
log.
\begin{center}
\includegraphics[height=85mm]{screenshots/learn}
\end{center}
Below are the basic learning options as shown above are as follows:
\begin{itemize}
\item Minimum Number of Initial Vectors (Tn) (default=2): \\
Tn is a threshold value used in the CreateInfluenceVectorSet
algorithm and represents the minimum number of influence vectors
constructed in this algorithm.
\item Maximum Influence Vector Size (Tj) (default=2): \\
Tj is a threshold value used in the CombineInfluenceVectors
algorithm to determine the maximal size of merged influence
vectors.
\item Score for Empty Influence Vector (Ti) (default=0.5): \\
The score for an influence vector with no influences in it.
\item Number of Bins (default=4): \\
The number of bins value specifies how many values the
encoded time series data can assume.
\item Equal Data Per Bins / Equal Spacing of Bins: \\
This radio button selects whether the auto generated levels
should be determined by equaling dividing the data between the
bins or by equally dividing the range of the data.
\item Use Auto Generated Levels / Use User Generated Levels: \\
This radio button allows the user to select whether they want
the levels separating the bins to be auto generated or the user
would like to provide them.
\item When using user provided levels, the Suggest Levels
button will provide the levels that would have been auto
generated as a suggestion. These levels can then edited by the
user. The number of bins for each species can also be individually adjusted.
\end{itemize}
The advanced learning options shown below are as follows:
\begin{itemize}
\item Ratio for Activation (Ta) (default=1.15): \\
A probability ratio above this value results in a vote for an
influence vector that has a majority of activation influences.
\item Ratio for Repression (Tr) (default=0.75): \\
A probability ratio above this value results in a vote for an
influence vector that has a majority of repression influences.
\item Merge Influence Vectors Delta (Tm) (default=0.0): \\
Two influence vectors cannot be merged unless the difference
in their scores is less than this value.
\item Relax Thresholds Delta (Tt) (default=0.025): \\
The values of Ta and Tr are modified by this amount when
these thresholds are relaxed.
\item Debug Level (default=0): \\
This controls how much information is displayed by the
GeneNet algorithm when it runs.
\item Successors / Predecessors / Both (default=Successors): \\
This radio button selects whether successor data point pairs,
predecessor data point pairs, or both are used.
\item Basic FindBaseProb (default=unchecked): \\
When selected, the basic FindBaseProb function is used.
\end{itemize}
\begin{center}
\includegraphics[height=85mm]{screenshots/advLearn}
\end{center}
\section{\label{TSDEdit}TSD Graph Editor}
\noindent
The TSD graph editor appears as a tab in both analysis and learn
views. TSD graphs can also be created at the top-level of the project
to allow you to integrate results from several analysis or learn
views. These graphs can be created using the New $\rightarrow$ TSD Graph
menu option. Once created, they can be viewed and edited by double
clicking on the graph in the project window. An example graph is
shown below.
\begin{center}
\includegraphics[height=80mm]{screenshots/TSDgraph}
\end{center}
In the TSD graph editor shown below,
a graph is created by double clicking on the graph. You can then set
various parameters and select what values you would like to have
graphed. The parameters that you can select for a graph include:
\begin{itemize}
\item Title - The title of the graph.
\item X-Axis Label - The label displayed for the x-axis.
\item Y-Axis Label - The label displayed for the y-axis.
\item X-Min - The starting value for the x-axis.
\item X-Max - The ending value for the x-axis.
\item X-Step - The increment for the x-axis.
\item Y-Min - The starting value for the y-axis.
\item Y-Max - The ending value for the y-axis.
\item Y-Step - The increment for the y-Axis.
\item Auto Resize Check Box -
Determines whether to automatically resize the graph for best fit.
\end{itemize}
\begin{center}
\includegraphics[height=80mm]{screenshots/editGraph}
\end{center}
The data selection menu on the left displays all of the
available sets of data that can be graphed. In particular, one can
graph the average, variance, standard deviation, or results from
individual simulation runs. For a top-level graph, these
data sets will be organized hierarchically. Hierarchy is also
introduced when simulations in an analysis view are given
simulation IDs or after performing an analysis while sweeping parameter
values. After selecting a data set, one can select individual species to
graph and how they are to be displayed. In other words, for each
species, there are the following options:
\begin{itemize}
\item Use Check Box - Determines
whether or not this species is displayed on the graph. Checking or
unchecking the box at the top changes the state for all species in
the data set.
\item Species Label - The name displayed in the legend.
\item Drop Down Menu Of Colors - The color that is used for this species.
\item Drop Down Menu Of Shapes - The shape that is used to mark the
data points.
\item Connect Check Box -
Determines whether to connect the points with a line. Checking or
unchecking the box at the top changes the state for all species in
the data set.
\item Visible Check Box - Determines
whether shapes are visible on the line. Checking or
unchecking the box at the top changes the state for all species in
the data set.
\item Fill Check Box - Determines whether shapes are filled
on the line. Checking or
unchecking the box at the top changes the state for all species in
the data set.
\end{itemize}
Note that a check mark 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.
The ``Save Graph'' button saves the settings for the graph to
a file, so when you re-open the graph, it will reload this data and display
in the same way as before. The ``Save As'' button prompts for a
filename and creates a new top-level graph with that name.
Finally, the ``Export'' button prompts for a filename and exports
the data to the given name. The extension provided for the filename
is used to determine how the graph is to be exported. The
supported file types are:
\begin{itemize}
\item csv - comma separated value data file.
\item dat - column separated data file.
\item eps - encapsulated postscript.
\item jpg - JPEG (Joint Photographic Experts Group).
\item pdf - portable document format.
\item png - portable network graphics.
\item svg - scalable vector graphics.
\item tsd - time series data format (see Section~\ref{TSD}).
\end{itemize}
If no extension is given, then the file type is the one
specified in the file filter (default is pdf). For image (i.e.,
not data) file types, you will be prompted to give a desired
pixel height and width for the file before the file is exported.
\section{\label{ProbEdit}Probability Graph Editor}
\noindent
Probability graphs are used to display histograms for reasons that
simulations terminated. This is used in conjunction with SBML constraints
to determine the likelihood of various conditions.
The probability graph editor appears as a tab in analysis
views. Probability graphs can also be created at the top-level of the project
to allow you to integrate results from several analysis views.
These graphs can be created using the New $\rightarrow$ Probability Graph
menu option. Once created, they can be viewed and edited by double
clicking on the graph in the project window. An example probability
graph is shown below.
\begin{center}
\includegraphics[height=80mm]{screenshots/probGraph}
\end{center}
In the probability graph editor,
a graph is created by double clicking on the graph. You can then set
various parameters and select what values you would like to have
graphed. The parameters that you can select for a graph include:
\begin{itemize}
\item Title - The title of the graph.
\item X-Axis Label - The label displayed for the x-axis.
\item Y-Axis Label - The label displayed for the y-axis.
\end{itemize}
\begin{center}
\includegraphics[height=80mm]{screenshots/editProbGraph}
\end{center}
The data selection menu on the left displays all of the
available sets of data that can be graphed.
For a top-level graph, these
data sets will be organized hierarchically. Hierarchy is also
introduced when simulations in an analysis view are given
simulation IDs or after performing an analysis while sweeping parameter
values. After selecting a data set, one can select individual constraints to
graph and how they are to be displayed. In other words, for each
constraint, there are the following options:
\begin{itemize}
\item Use Check Box - Determines
whether or not this constraint is displayed on the graph. Checking or
unchecking the box at the top changes the state for all constraints in
the data set.
\item Constraints Label - The name displayed in the legend.
\item Drop Down Menu Of Colors - The color that is used for this constraint.
\end{itemize}
Note that a check mark appears on a data set to indicate that some
constraints have been selected in that data set. Also, all constraints can
be deselected by pressing the Deselect All button.
The ``Save Graph'' button save the settings for the graph to
a file, so when you re-open the graph, it will reload this data and display
in the same way as before. The ``Save As'' button prompts for a
filename and creates a new top-level graph with that name.
Finally, the ``Export'' button prompts for a filename and exports
the data to the given name. The extension provided for the filename
is used to determine how the graph is to be exported. The
supported file types are:
\begin{itemize}
\item eps - encapsulated postscript.
\item jpg - JPEG (Joint Photographic Experts Group).
\item pdf - portable document format.
\item png - portable network graphics.
\item svg - scalable vector graphics.
\end{itemize}
If no extension is given, then the file type is the one
specified in the file filter (default is pdf). For image (i.e.,
not data) file types, you will be prompted to give a desired
pixel height and width for the file before the file is exported.
\section{\label{Preferences}Preferences}
\noindent
User preferences can be set by selecting the {\tt Preferences} option
under the {\tt File} menu on Linux and Windows or the {\tt iBioSim}
menu on MacOS. As shown below, the user can decided whether they wish
to see warnings about undeclared units in SBML and whether they wish
to check units at all. The user can also change the GCM default
parameter values by clicking on the {\tt GCM Defaults} button.
\begin{center}
\begin{tabular}{cc}
\includegraphics[height=80mm]{screenshots/SBMLPref} &
\includegraphics[height=80mm]{screenshots/GCMPref}
\end{tabular}
\end{center}
\section{\label{GCM}Genetic Circuit Model Format}
\noindent
Our genetic circuit model (gcm) format specifies a genetic
circuit using the same format used by the GraphViz graph drawing
tool. The vertices in the graph are the species in
the genetic circuit, and the edges in the graph represent the
activation and repression relationships between the species. An
activation relationship is shown with a blue (blue4) arrow (vee)
and a repression relationship is shown with a red (firebrick4)
tee. The label field in the species declaration is the name of
the species. The arrowhead field in the relationship declaration
represents the type of relationship between the species.
Repression is labeled with a tee and activation is labeled with a
vee. The label field in the relationship declaration represents
how many molecules are necessary to activate or repress the
production of the species. An example is shown below for a simple
genetic circuit in which the species CI represses CII while CII
activates CI production. The $s1 -> s2$ edge has a label field of
``2'' which means two molecules of CI are required to form a dimer
to repress CII.
\begin{verbatim}
digraph G {
CI [shape=ellipse,color=black,label="CI"];
CII [shape=ellipse,color=black,label="CII"];
CII -> CI [color="blue4",arrowhead=vee];
CI -> CII [color="firebrick4",label="2",arrowhead=tee];
}
\end{verbatim}
More advanced behavior can be modeled by using extra fields.
The promoter field groups a set of species together. The examples
below shows how the promoter field works. In the genetic circuit
model below, species A represses the production of species B and
C, independently. If there was exactly 1 molecule of species A,
it would only be able to repress production of species B or C,
but not both.
\begin{verbatim}
digraph G {
A [shape=ellipse,color=black,label="A"];
B [shape=ellipse,color=black,label="B"];
C [shape=ellipse,color=black,label="C"];
A -> B [color="blue4",arrowhead=tee];
A -> C [color="blue4",arrowhead=tee];
}
\end{verbatim}
With the promoter field, one species A now represses the
promoter ``P1'', which produces both species B and C.
This means that one molecule of species A will repress the
production of both species B and C.
\begin{verbatim}
digraph G {
A [shape=ellipse,color=black,label="A"];
B [shape=ellipse,color=black,label="B"];
C [shape=ellipse,color=black,label="C"];
A -> B [color="blue4",arrowhead=tee,promoter="P1"];
A -> C [color="blue4",arrowhead=tee,promoter="P1"];
}
\end{verbatim}
The promoter field can also be used to separate production
reactions. In the example below, both species A and B can repress
the production of species C. If either is present, then very
little C will be produced. This behavior is like a NOR gate.
\begin{verbatim}
digraph G {
A [shape=ellipse,color=black,label="A"];
B [shape=ellipse,color=black,label="B"];
C [shape=ellipse,color=black,label="C"];
A -> C [color="blue4",arrowhead=tee];
B -> C [color="blue4",arrowhead=tee];
}
\end{verbatim}
However, if there needs to be two different sources of
production for species C, the promoter field can be used to
accomplish this. In the example below, A represses the production
of C by binding to the P1 promoter, and B represses the
production of C by binding to the P2 promoter. Both A and B need
to be present to fully repress the level of C. If either is at a
low level, then the level of C will be high. This behavior is
like a NAND gate.
\begin{verbatim}
digraph G {
A [shape=ellipse,color=black,label="A"];
B [shape=ellipse,color=black,label="B"];
C [shape=ellipse,color=black,label="C"];
A -> C [color="blue4",arrowhead=tee,promoter="P1"];
B -> C [color="blue4",arrowhead=tee,promoter="P2"];
}
\end{verbatim}
The example below shows how to model an AND gate. The species
A and B have the constant flag set to true. This means that A and
B have no production and degradation reactions. The reactions
contain a promoter label ``P1''. This means that the
species C can be activated by both A and B. Combined with the
type flag of biochemical, this creates a biochemical reaction
where species A and B combine together to form a complex to
activate production of species C.
\begin{verbatim}
digraph G {
A [shape=ellipse,color=black,label="A",const=true];
B [shape=ellipse,color=black,label="B",const=true];
C [shape=ellipse,color=black,label="C"];
A -> C [color="blue4",arrowhead=vee,promoter="P1",type=biochemical];
B -> C [color="blue4",arrowhead=vee,promoter="P1",type=biochemical];
}
\end{verbatim}
\section{\label{TSD}Time Series Data Format}
\noindent
The time series data (tsd) format is composed of a
parenthesized and comma-separated set of time points. Each time
point is composed of a parenthesized and comma-separated set of
data for that time point. This first time point is composed of a
set of strings that are the labels for the data entries. The
first entry in each time point is by convention the time for that
time point. Below is an example simulation of the species CI and
CII from 0 to 1000 seconds with time points separated by 100
seconds.
(("time","CI","CII"), (0,0,0), (100,0,19), (200,20,25), (300,19,18),
(400,17,20), (500,17,46), \\
(600,26,40), (700,43,43), (800,63,28), (900,72,34), (1000,72,28))
\section{\label{HotKeys}List of Hot Keys}
Below is a list of the hot keys used in Windows and Linux with the
MacOS equilvalents in parantheses.
\begin{itemize}
\item Ctrl-X (Cmd-Q) - Exit or quit % Alt-X
\item Ctrl-, (Cmd-,) - Preferences
\item Ctrl-A - About % Alt-A
\item Ctrl-M - Manual
\item (Cmd-H) - Hide window
\item (Alt-Cmd-H) - Hide other windows
\item Ctrl-C - Copy % Alt-C
\item Ctrl-R - Rename % Alt-R
\item Ctrl-D - Delete % Alt-D
\item Ctrl-P - New Project % Alt-P
\item Ctrl-O - Open Project % Alt-O
\item Ctrl-G - New Genetic Circuit Model % Alt-G
\item Ctrl-S - New SBML Model % Alt-S
\item Ctrl-V - New VHDL % Alt-V
\item Ctrl-L - New LHPN % Alt-L
\item Ctrl-N - Import Genetic Circuit Model or LHPN % Alt-N
\item Ctrl-B - Import SBML % Alt-B
\item Ctrl-H - Import VHDL % Alt-H
\item Ctrl-T - TSD Graph % Alt-T
\item Ctrl-Y - Probability Graph % Alt-Y
\end{itemize}
\section{Tutorial}
\noindent
A detailed
%%tth:\begin{html}<a href="tutorial.html">\end{html}
tutorial
%%tth:\begin{html}</a>\end{html}
is available in the {\tt docs} directory that comes with the distribution.
\section{Reporting Bugs and Feature Requests}
\noindent
In order to report a bug or to request a change or feature, please
send an email to:\\
%%tth:\begin{html}<a href="mailto:atacs-bugs@vlsigroup.ece.utah.edu">\end{html}
{\tt atacs-bugs@vlsigroup.ece.utah.edu}.\\
%%tth:\begin{html}</a>\end{html}
The subject line must begin with one of the following keywords or the
mail will be filtered by our spam filters:
\begin{itemize}
\item BUG - error or crash of the software
\item CHANGE - something which can be improved
\item FEATURE - something new
\end{itemize}
\section{Credits}
\noindent
The iBioSim tool is being developed at the University of Utah
by
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/~myers">\end{html}
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.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}
and
%%tth:\begin{html}<A HREF="http://www.cs.utah.edu/~namphuon">\end{html}
Nam Nguyen.
%%tth:\begin{html}</A>\end{html}
Nathan Barker is now with Southern Utah University, and Hiroyuki
Kuwahara is now with the Centre for Computational and System
Biology in Trento, Italy.
\end{document}
Reference in a new issue View git blame Copy permalink