iBioSim/docs/iBioSim.tex

\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.8 \\ User's Manual}

\author{Chris J. Myers, Nathan Barker, Scott Glass, Kevin Jones, Hiroyuki Kuwahara, Curtis Madsen,  Nam Nguyen, \\
Tramy Nguyen, Tyler Patterson, Nicholas Roehner, Jason Stevens, Leandro Watanabe, Zhen Zhang} 

\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} 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 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}
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, 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 and flux balance results. 
\end{itemize}

\subsection*{Credits}

\noindent
The iBioSim tool is being developed by 
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/~myers">\end{html}
Chris Myers 
%%tth:\begin{html}</A>\end{html}
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, Tramy Nguyen, Tyler Patterson, Nicholas Roehner, Jason Stevens, Leandro Watanabe, and Zhen Zhang.
% 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

\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}

\clearpage

\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 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 ten most recently opened projects by selecting the project name shown in the Open Recent menu within the File menu.

\begin{center}
\includegraphics[height=80mm]{screenshots/project}
\end{center}

\clearpage

\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 model, select New $\rightarrow$ Model from the File menu as shown below. You will then be prompted to enter a model ID.  At this point, a Model editor (see Section~\ref{ModelEdit}) will open in a new tab.  

\begin{center}
\includegraphics[height=80mm]{screenshots/newModel}
\end{center}

\begin{center}
\includegraphics[height=25mm]{screenshots/ModelId}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/ModelEditor}
\end{center}

To create a new grid model, select New $\rightarrow$ Grid Model from the File menu as shown below. You will then be prompted to enter a model ID.  Next, a Create Grid window opens that asks for the number of rows and columns in the grid.  It also asks which model to use to populate the grid initially.  You can select ``none'' if you wish to populate it later.  At this point, a Grid Model editor (see Section~\ref{ModelEdit}) will open in a new tab.  

\begin{center}
\includegraphics[width=60mm]{screenshots/createGrid}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/gridModel}
\end{center}

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{TSDGraph}) will open in a new tab. 

\begin{center}
\includegraphics[width=160mm]{screenshots/TopTSDgraph}
\end{center}

To create a new histogram, select New $\rightarrow$ Histogram from the File menu. You will then be prompted to give a name to the histogram.  At this point, a histogram editor (see Section~\ref{Histogram}) will open in a new tab.  

\begin{center}
\includegraphics[width=160mm]{screenshots/TopHistogram}
\end{center}

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 ``View/Edit'' or, alternatively, double-clicking on the object.  Note that a model can be opened in either a graphical or tabular editor.  An open model or graph can be closed by either clicking on the ``X'' in the tab or by selecting Close from the File menu.  The Close All option in the File menu closes all tabs.

 \clearpage

\subsection{Importing Models}

\noindent
You can also import files into the current working project.  These can be 
%%tth:\begin{html}<A HREF="http://www.sbml.org/">\end{html}
\emph{Systems Biology Markup Language}
%%tth:\begin{html}</A>\end{html}
~(SBML) models, models from the
%%tth:\begin{html}<A HREF="http://www.ebi.ac.uk/biomodels-main/">\end{html}
\emph{BioModels database},
%%tth:\begin{html}</A>\end{html}
models from the
%%tth:\begin{html}<A HREF="http://sbol.ncl.ac.uk:8081/">\end{html}
\emph{Virtual Parts repository},
%%tth:\begin{html}</A>\end{html}
\emph{Labeled Petri Net} (LPN) models, a 
%%tth:\begin{html}<A HREF="http://www.sbolstandard.org/">\end{html}
\emph{Synthetic Biology Open Language}
%%tth:\begin{html}</A>\end{html}  
(SBOL) file (see Section~\ref{SBOL}), or a 
%%tth:\begin{html}<A HREF="http://sed-ml.org/">\end{html}
\emph{Simulation Experiment Description Markup Language}
%%tth:\begin{html}</A>\end{html}  
(SED-ML) file. 

\begin{center}
\includegraphics[height=60mm]{screenshots/import}
\end{center} 

To import a SBML, select Import $\rightarrow$ SBML Model from the File menu.  
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 model into the project.  Before bringing the model into the project, it will be checked to see if it is 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.  Importing of an LPN model, an SBOL file, or a SED-ML file are similar in that you are asked to locate the appropriate file to import.  When importing a model from the BioModels database, the window below will open, initially only listing the BioModel numbers.  Selecting ``Get Names'' will fetch the model names from the database.  Beware that this can take a significant amount of time.  When you click on a model to select it, you can use the ``Get Description'' button to fetch a description of the model which will open in a browser.  Similarly, the ``Get Reference'' button will fetch the reference describing this model and again open it in a browser.

\begin{center}
\includegraphics[height=60mm]{screenshots/BioModels}
\end{center} 

%% TODO: NEED TO DISCUSS VIRTUAL PARTS REPOSITORY

\subsection{Exporting Models and Graphs}

\noindent
You can also export a SBML model or the SBOL associated with this model.  To export an SBML model, select  Export $\rightarrow$ Flat SBML or Export $\rightarrow$ SBML.  Then, you will be able to browse to find a location to export the SBML file.  A flat SBML file is a single flattened chemical reaction model while an SBML file is a single file hierarchical model with high-level genetic constructs.  
When exporting SBOL associated to a model, you must browse to find an existing SBOL file or enter the name for a new file.  The associated SBOL will then be added to the selected file or a new file.  Finally, you can export a JPG image of a model.

\begin{center}
\includegraphics[height=80mm]{screenshots/export}
\end{center} 

Data and graphs of time series data or histograms can be exported from the project in many formats.  The supported file formats are:  
\begin{itemize}
\item Time series data format (tsd), see Section~\ref{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}

\clearpage

\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 (these actions can also be done from the Edit menu).  For a model file, the ``View/Edit (graphical)'' option opens the graphical model editor while the ``View/Edit (tabular) opens the tabular model editor (see Section~\ref{ModelEdit}).  
For a TSD graph, the ``View/Edit'' option opens the TSD graph editor (see Section~\ref{TSDGraph}).  For a histogram, the ``View/Edit'' option opens the histogram graph editor 
(see Section~\ref{Histogram}).  
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}
\includegraphics[height=65mm]{screenshots/GCMAnalysis} 
\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.  Views can also be created using the Tools menu.  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}
%\includegraphics[height=65mm]{screenshots/GCMAnalysis} 
%\end{center}

\clearpage

\section{\label{ModelEdit}Model Editor}

\noindent
The model editor allows the user to create or modify a model of a genetic circuit or other biochemical system.  {\tt iBioSim} models are based on SBML Level 3 Version 1 models with added features to support visualization, hierarchy, and modeling of genetic regulation.  SBML models can be imported and exported to allow interfacing with SBML-compliant tools.  When exporting an SBML model, the hierarchy and genetic regulation can be flattened to create a single SBML model that uses only SBML L3V1 core constructs.  The model editor includes both a schematic editor as well as several tabular editors.  For large models, the schematic portion can also be edited tabularly instead.  You can create both ordinary models and grid models.

\begin{center}
\includegraphics[height=25mm]{screenshots/ModelId}
\end{center}

The schematic editor for an ordinary model is shown below.  There are two groups of icons.  By selecting the appropriate icon in the first group, the user can add \emph{compartments} (see Section~\ref{Compartments}), \emph{chemical species} (see Section~\ref{Species}), 
\emph{chemical reactions} (see Section~\ref{Reactions}), \emph{components} (see Section~\ref{Components}), \emph{promoters} (see Section~\ref{Promoters}), \emph{real variables} (see Section~\ref{Variables}), \emph{Boolean variables} (see Section~\ref{Booleans}), \emph{Petri net places} (see Section~\ref{Places}), \emph{Petri net transitions} (see Section~\ref{Transitions}), \emph{rules} (see Section~\ref{Rules}), \emph{constraints} (see Section~\ref{Constraints}), and \emph{events} (see Section~\ref{Events}) to the schematic.  When the select icon is highlighted, \includegraphics{../gui/icons/modelview/select_mode_selected}, double clicking on an object in the schematic opens the appropriate object editor.  In this mode, relationships can also be created between objects by selecting an object and, while holding the mouse, dragging the connection to another object.  The type of relationship (or \emph{influence}) is determined by the icon that is highlight in the second group  (see Section~\ref{Influences}).  Finally, if the self regulation icon,
\includegraphics{../gui/icons/modelview/self_influence_selected}, is selected, clicking on a species creates a self influence relationship.  The remaining items on the toolbar allow the user to apply an automatic layout routine \includegraphics{../gui/icons/modelview/choose_layout_selected}, zoom, restore to default size (Un-Zoom), pan, edit model attributes (see Section~\ref{ModelEditor}), and edit the SBOL information associated with the model (see Section~\ref{SBOL}).  Finally, the additional tabs allow the user to add, edit, or remove \emph{real constants} (see Section~\ref{Constants}), \emph{function definitions} (see Section~\ref{Functions}), and \emph{unit definitions} (see Section~\ref{Units}).  One last note, there are several options in the Edit menu, which are also available via hotkeys, that can be useful during model editing.  These include return undo, redo, return to select mode, delete, and moving and adding elements on the schematic.  The user can also return to the select mode using the ESC key while delete and selection options are available in a right click menu on schematic objects.  

\begin{center}
\includegraphics[width=160mm]{screenshots/ModelEditor}
\end{center}

\begin{center}
\includegraphics[width=40mm]{screenshots/editMenu}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/deleteSelect}
\end{center}

For large models, it may be preferable to use the tabular model editor shown below.  The tabular editor includes all the same elements as the graphical editor except they are presented as lists of their Ids.  In each list, the user can add new element, remove existing elements, or edit the properties of existing elements.  Note that constants, real variables, Boolean variables, and places appear in the Parameter list, influences appear in the Reaction list, and Petri net transitions appear in the Event list.

\begin{center}
\includegraphics[width=160mm]{screenshots/textualEditor}
\end{center}

\noindent
{\tt iBioSim} also supports the creation of models on a grid.  The idea of a grid is to provide a coarse-grain spatial representation.  A single model can be instantiated within each grid location.  The models can be for individual cells, allowing one to model population dynamics.  The models can also be different segments of a single cell, allowing one to model diffusion within a cell.  Key to grid-based modeling are diffusible species, described in Section~\ref{Species}.  When the models within grid locations are compartment-enclosed components, reactions are added to represent the movement of these diffusible species between the compartment and the area outside the compartment within the grid location (i.e., \emph{membrane diffusion}).  When performing analysis, reactions are also automatically added to represent the movement of these diffusible species between the grid locations.  

The schematic for a model on a grid is a bit different than for an ordinary model, which is evident from the toolbar.  Namely, a grid-based model can only include components, with at most one component per grid location.  By pressing the Add Component icon \includegraphics{../gui/icons/modelview/add_component_selected} and clicking on an empty grid location, you are allowed to select a model to instantiate within that grid location.  You can also select Edit Grid Size to change the size of the grid.  If the grid is larger in one or more dimensions than before, you can select a model to populate the new grid locations.  A smaller grid size simply removes the component instantiations that fall outside the new grid.  You can also edit the grid by selecting individual grid locations by clicking on them or selecting multiple grid locations using the rectangle selection tool by left-clicking and dragging the mouse.  When you then use the right mouse button, it brings up the menu shown below.  This menu allows you to delete the component that was right-clicked on or to open its model in a Model Editor.  You can also use this menu to select or de-select all grid locations, and you can either clear occupied, or populate non-occupied, selected grid locations.  The grid model editor has one additional tab which allows the user to edit properties for the species that diffuse on the grid.

\begin{center}
\includegraphics[width=140mm]{screenshots/gridModel}
\end{center}

\begin{center}
\includegraphics[width=140mm]{screenshots/editGridSize}
\end{center}

\begin{center}
\includegraphics[width=140mm]{screenshots/gridRightButton}
\end{center}

\subsection{\label{Compartments}Compartments}

\noindent
Compartments are used to specify membrane-enclosed regions where species are found. A new model includes a compartment named {\tt Cell} by default.  Note that when a compartment has species or reactions assigned to it that it cannot be removed without first removing or reassigning these species and reactions.  To add a new compartment to the model, select the Add Compartment icon \includegraphics{../gui/icons/modelview/add_compartment_selected} and click on the schematic canvas.  This will drop a new compartment with default ID and other values.  You may change these defaults by double-clicking on the compartment to open the Compartment Editor.  
As shown below, a compartment has the following fields:
\begin{itemize}
\item ID: a unique ID composed of only alphanumeric characters and underscores.  Can also have optional array dimension(s) enclosed in square brakets.  Within each set of brackets, a constant parameter must be provided that sets the size of that dimension of the compartment array.
\item Name: an arbitrary string description (optional).
\item Is Mapped to a Port: a checkbox indicating whether or not this compartment is mapped to a port, so it can be replaced or deleted in hierarchical models (default=false).
\item Spatial Dimensions: number of spatial dimensions (default=3).
\item Spatial Size: initial size of the compartment (default=1.0).  This value can be a mathematical expression (see Section~\ref{SBMLMath}) which is called an \emph{initial assignment}.
\item Units: the units for the size (default=none).
\item Constant: Boolean indicating if the size is constant (default=true).
\end{itemize}
When a compartment is assigned to a port, it is assumed that the compartment is not membrane enclosed.  This is indicated by the compartment having square corners.  By assigning a compartment to a port, when this model is used as a subModel in another model, the compartment can be replaced with the one in the enclosing model.  When a compartment is not assigned to a port, it is assumed that the compartment is membrane enclosed which is indicated with rounded corners.

\begin{center}
\includegraphics[height=80mm]{screenshots/compartment}
\end{center}

\subsection{\label{Species}Species}

\noindent
Species are the molecules, such as proteins, that are produced by genes or chemical reactions.  To add a species to the model, 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 double-clicking on the species to open the Species Editor.  A species has the following elements:
\begin{itemize} 
\item ID: a unique ID composed of only alphanumeric characters and underscores.
\item Name: an arbitrary string description of the species (optional).
\item Port Type: used to indicate how this species can be connected in hierarchical models.  The \emph{input} type is used to indicate a species that is produced outside this model, the \emph{internal} type is used to indicate that a species is produced inside this model but cannot be used in other models, and the \emph{output} type is used to indicate that a species is produced by this model and can be used in other models (default=internal). 
\item Compartment: location of the species (default is set by where the species is placed in the schematic).
\item Compartment Indices: used to reference the compartment when it is an array.
\item Initial Amount/Concentration: initial value of the amount or concentration of the species (default=0.0).  This value can be a mathematical expression (see Section~\ref{SBMLMath}) which is called an \emph{initial assignment}.  If the value/expression is enclosed in brackets (i.e., $[e]$), it is a concentration, otherwise it is an amount.  
\item Units: the units for the amount/concentration (default=none).
\item Conversion Factor: is a constant global parameter, the value of which is used to convert this species' units into the units used for extent (i.e., the units of change due to reactions).
\item Conversion Factor Indicies: used to reference the conversion factor when the parameter is an array.
\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 Has Only Substance Units: Boolean indicating if the species is to be considered an amount in mathematical equations (default=true).
\item Constitutive: this checkbox indicates that a default production reaction should be created for this species (default=false).
\item Degrades: this checkbox indicates that a default degradation reaction should be created for this species (default=false).
\item Diffusible: this checkbox indicates if this species can diffuse in multi-compartment and grid-based models (default=false).
\item Open complex production rate (ko): once RNAP binds to this promoter, this is the rate at which transcription is initiated.  Note that this production rate is used in the production reaction created when a species is marked as constitutively produced.  The default value is the global parameter ko.
\item Stoichiometry of production (np): the average number of proteins that are produced by an mRNA before it degrades.  This value is used in the production reaction created when a species is marked as constitutively produced.  The default value is the global parameter np.
\item Degradation rate (kd): the degradation rate for this species.  This value is used in the degradation reaction created when a species is marked that it degrades.  The default is the value of the global parameter kd.  
\item Complex formation equilibrium (Kc): the equilibrium constant for formation of this species when it is produced by a complex formation reaction.  The default is the global parameter Kc.  The equilibrium constant can be specified as a forward and reverse rate constant using the $\langle$ forward rate $\rangle / \langle$ reverse rate $\rangle$ form.
\item Membrane diffusion rate (fd/rv) (kmdiff): the forward (in to out) and reverse (out to in) rate constants (slash-separated) for diffusion of this species through its compartment's membrane.  Note that when membrane diffusion reactions are generated, the rates are taken from the inner species.  If no reverse rate is given, a default of 1.0 is used.  The default is the global parameter kmdiff.
\end{itemize}
Finally, one can specify that an SBOL element is associated with this species by clicking on the Associate SBOL button.  More details can be found in Section~\ref{SBOL}.

\begin{center}
\includegraphics[width=160mm]{screenshots/species}
\end{center}

\clearpage

\subsection{\label{Reactions}Reactions}

\noindent
Reactions are used to create or destroy molecular species in a biochemical reaction network.  
To add a reaction, select the Add Reaction icon \includegraphics{../gui/icons/modelview/add_reaction_selected} and click on the schematic canvas which drops a new reaction with a default ID and parameter values.  

\begin{center}
\includegraphics[width=155mm]{screenshots/reaction}
\end{center}

Reactions convert reactant species into product species with perhaps modifier species (e.g., enzymes or catalysts) affecting the rate of this conversion.  The next step, therefore, is to indicate which species are reactants, products, and modifiers for the reaction.  This is accomplished by selecting the Reaction icon \includegraphics{../gui/icons/modelview/reaction_selected} or Modifier icon \includegraphics{../gui/icons/modelview/modifier_selected}.  With the Reaction icon selected, selecting a species, holding the mouse button, and dragging the arc to a reaction makes the selected species a reactant in that reaction.  Similarly, selecting a reaction, holding the mouse button, and dragging the arc to a species makes the species a product in the selected reaction.  Finally, with the Modifier icon selected, dragging an arc between a species and reaction (in either direction) adds the species as a modifier in the reaction.  When you select a reactant edge, it opens a Reactants Editor.  This editor allows you to change the following things:
\begin{itemize}
\item ID: this is the ID for this reactant and should not be confused with the Species ID.  This ID can be used in equations such as rules and event assignments.  Use this ID when you want the stoichiometry to be determined by an equation or used in an equation.  The ID is optional.
\item Name: an arbitrary string description of the species (optional).
\item Species: the ID of the reactant species.
\item Stoichiometry: the number of molecules consumed by the reaction (default=1.0).  This value can be a mathematical expression (see Section~\ref{SBMLMath}) which is called an \emph{initial assignment}.  
\item Constant: indicates whether the stoichiometry can change dynamically (default=true).  
\end{itemize}
Similarly, the ID, Name, Species, Stoichiometry, and Constant fields can be edited for a Product edge as shown below.  Modifier edges do not have any of these fields, so they cannot be edited.

\begin{center}
\includegraphics[width=155mm]{screenshots/reactant} 
\end{center}

\begin{center}
\includegraphics[width=155mm]{screenshots/product}
\end{center}

When you select a reaction, it opens the Reaction Editor which allows you to edit the following reaction fields:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Is Mapped to a Port: a checkbox indicating whether or not this reaction is mapped to a port, so it can be replaced or deleted in hierarchical models (default=false).
\item Compartment: the location where this reaction takes place.  This is set by the location in which the reaction is placed in the schematic.
\item Reversible: a Boolean indicating if the reaction is reversible (default=false).  Note that reversible reactions are indicated in the schematic with double headed arrows.
\item Fast: a Boolean indicating if the reaction reaches equilibrium rapidly (default=false).  Note that this only has limited support in analysis, so it should be used sparingly.
\item SBOL DNA Component: the Associate SBOL button allows the user to associate an SBOL DNA component with the reaction (see Section~\ref{SBOL}).
\item List of Local Parameters: symbolic values that can be used in the \emph{kinetic law} for this reaction.  Their IDs only need to be unique to this reaction.  Local parameters can be added, removed, and edited using the appropriate buttons.  Each parameter is composed of an ID, Name (optional), Value, Units (optional), and a checkbox indicting whether or not this parameter is mapped to a port.  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. 
\item Kinetic Law: a mathematical formula (see Section~\ref{SBMLMath}) describing the rate or probability for this reaction.  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 assuming 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.  Note that the kinetic law formula can only include species IDs that are reactants, products, or modifiers to this reaction.
\end{itemize}

\begin{center}
\includegraphics[width=155mm]{screenshots/localParam}
\end{center}

\begin{center}
\includegraphics[width=155mm]{screenshots/kineticLaw} 
\end{center}

To simplify a schematic, one can use implicit reactions in some limited situations.  To create an implicit reaction, with the Reaction icon \includegraphics{../gui/icons/modelview/reaction_selected} highlighted and the mouse button selected, drag a reaction edge between two species.  This action creates a reaction with a default ID and parameters, including the source species as a reactant and sink species as a product.  If you connect an additional reaction edge to either species, you are asked if you wish to create a new reaction or add this new relationship to an existing reaction on the source and/or sink species.  Implicit reactions can only be used when the following conditions hold:
\begin{itemize}
\item The stoichiometry of all reactants and products for the reaction is 1.
\item The reaction has either a single reactant OR a single product.
\item The reaction has no modifier species.
\end{itemize}
The first condition is a default and cannot be changed.  Adding edges can, however, cause a violation of the second or third condition.  If this violation occurs, an explicit reaction is created to replace the implicit reaction.

\begin{center}
\includegraphics[width=155mm]{screenshots/implicitReactions} 
\end{center}

\subsection{\label{Components}Components}

\noindent
Components are instances of other models within the project, and they are used to create hierarchical, multi-compartment, and cellular population models.  To add a component, select the Add Component icon \includegraphics{../gui/icons/modelview/add_component_selected} and click on the schematic canvas.  You are then prompted to select the model for the component that you wish to add.  This window also allows you to add multiple instances of the component at one time.  To do this, select Tile Component and specify how many Columns, Rows, the Padding between them that you want, and whether to start the tiling in the top left corner of the schematic or at the mouse location.  

\begin{center}
\includegraphics[width=160mm]{screenshots/addComponent}
\end{center}

When a component is added, it appears in the schematic either with sharp or rounded corners.  A component with sharp corners is not enclosed within a compartment (i.e., its compartment is on a port).  In other words, this is likely part of a hierarchical model.  On the other hand, rounded corners indicate that it is enclosed within a compartment.  In this case, the component is likely to be part of either a multi-compartment or cellular population model.  If a diffusible species with the same ID exists inside and outside of a compartment-enclosed component, a membrane diffusion reaction will be created, allowing the species to be transported to/from the compartment-enclosed component.  If the compartment-enclosed component is on a grid, the outside diffusible species will be automatically created if the inside diffusible species exists.  
When a component has ports, connections to input ports can be made by selecting an object and, while holding the mouse button, drag an arc to the component.  If there are multiple input ports, you are asked which input port to connect this object to.  To connect to output ports, begin by selecting the component and drag an arc to the object to be connected to the output port.  Note that when you make these connections you are specifying that the object in the top-level model is the same object as the one in the component that it is connected too (i.e., it creates a \emph{replacement}).    

\begin{center}
\includegraphics[width=160mm]{screenshots/addPort}
\end{center}

Clicking on the component opens the Component Editor which allows you to edit the following fields:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Time Conversion Factor: is a constant global parameter, the value of which is used to convert the submodel's time units into the units used in the model that includes it.
\item Extent Conversion Factor: is a constant global parameter, the value of which is used to convert the submodel's extent units into the units used in the model that includes it.
\item SBOL DNA Component: the Associate SBOL button allows the user to associate an SBOL DNA component with the submodel (see Section~\ref{SBOL}).
\end{itemize}
The last part of the Component Editor is a table of replacements and deletions.  This table lists all items that are mapped to ports within the submodel.  For each port, it includes:
\begin{itemize}
\item Type: the type of SBML element.
\item Port: the ID of the SBML element.
\item Direction: the direction of replacement.  A $\leftarrow$ indicates that the item in the enclosing model replaces the one in the submodel.  A $\rightarrow$ indicates that the item in the enclosing model is replaced by the one in the submodel.
\item Replacement: this indicates the ID of the item in the enclosing model that is involved in the replacement.  If the replacement selection is ``delete'' then the object in the submodel is deleted when this model is flattened.  If the replacement selection is ``none'' then there is no replacement or deletion on this port.
\item Conversion: is a constant global parameter, the value of which is used to convert the submodel's units for this element into the units used by the item replacing it within the enclosing model.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/editComp}
\end{center}

When adding a component to a grid, you are simply asked which model to instantiate, and you cannot connect to ports as species are not allowed on a grid.

\begin{center}
\includegraphics[width=160mm]{screenshots/addCompGrid}
\end{center}

\clearpage

\subsection{\label{Promoters}Promoters}

\noindent
Promoters are the locations on a DNA sequence in which transcription is initiated to create a \emph{messager} RNA (mRNA), which can then be translated by a ribosome into a protein.  To add a promoter to a model, select the Add Promoter icon \includegraphics{../gui/icons/modelview/promoter_mode_selected} and click on the schematic canvas, which creates a new promoter with a default ID and parameter values.  Clicking on the promoter opens the Promoter Editor and allows you to edit the following fields:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Port Type: used to indicate how this object can be connected in hierarchical models.  The \emph{input} type is used to indicate a object that is produced outside this model, the \emph{internal} type is used to indicate that a object is produced inside this model but cannot be used in other models, and the \emph{output} type is used to indicate that a object is produced by this model and can be used in other models (default=internal). 
\item Initial promoter count (ng): the number of copies of this promoter.  The default is the value of the global parameter ng.   
\item RNAP binding equilibrium (Ko): the equilibrium constant to use for the binding of RNAP to this promoter.  The default value is the global parameter Ko.  Note that this can either be specified as a single equilibrium constant or as a forward rate ``/'' reverse rate.
\item Activated RNAP binding equilibrium (Kao): the equilibrium constant to use for the binding of RNAP to a promoter with an activator.  The default value is the global parameter Kao.  Note that this can either be specified as a single equilibrium constant or as a forward rate ``/'' reverse rate.
\item Open complex production rate (ko): once RNAP binds to this promoter, this is the rate at which transcription is initiated.  Note that this production rate is only used for promoters with no activators.  The default value is the global parameter ko.
\item Basal production rate (kb): once RNAP binds to an activated promoter, this is the rate at which transcription is initiated without the activator also being bound.  The default value is the global parameter kb.
\item Activated production rate (ka): once RNAP binds to an activated promoter, this is the rate at which transcription is initiated when the activator is also bound to the promoter.  The default value is the global value ka.
\item Stoichiometry of production (np): the average number of proteins that are produced by an mRNA before it degrades.  The default value is the global parameter np.
\item SBOL DNA Component: the Associate SBOL button allows the user to associate an SBOL  with the promoter (see Section~\ref{SBOL}).
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/promoter}
\end{center}

\clearpage

\subsection{\label{Variables}Real Variables}

\noindent
Real variables are non-constant global parameters that can be used in math formulas (see Section~\ref{SBMLMath}).  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 Initial value: initial value for the parameter.  This value can be a mathematical expression (see Section~\ref{SBMLMath}) which is called an \emph{initial assignment}.
\item Units: the units for the parameter value (default=none).
\item Constant: Boolean indicating if the parameter value is constant (default=false).
\item Port Type: used to indicate how this object can be connected in hierarchical models.  The \emph{input} type is used to indicate a object that is produced outside this model, the \emph{internal} type is used to indicate that a object is produced inside this model but cannot be used in other models, and the \emph{output} type is used to indicate that a object is produced by this model and can be used in other models (default=internal). 
\end{itemize}
Note that changing a the Constant attribute to true removes the parameter from the schematic, and it puts it in the list of Constants found in the Constant tab (see Section~\ref{Constants}).

\begin{center}
\includegraphics[width=160mm]{screenshots/parameter}
\end{center}

\clearpage

\subsection{\label{Booleans}Boolean Variables}

\noindent
Boolean variables are global parameters that can only take the values of true and false.  A Boolean variable 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 Initial value: initial value for the parameter (default=false).
\item Port Type: used to indicate how this object can be connected in hierarchical models.  The \emph{input} type is used to indicate a object that is produced outside this model, the \emph{internal} type is used to indicate that a object is produced inside this model but cannot be used in other models, and the \emph{output} type is used to indicate that a object is produced by this model and can be used in other models (default=internal). 
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/Boolean}
\end{center}

\clearpage

\subsection{\label{Places}Petri Net Places}

\noindent
Places are a special type of global parameter that is used in Petri net models.  A place can either be \emph{marked} with a token or \emph{not marked} with a token.  A place 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 Initial marking: indicates if there is a token in this place initially (default=false).
\item Port Type: used to indicate how this object can be connected in hierarchical models.  The \emph{input} type is used to indicate a object that is produced outside this model, the \emph{internal} type is used to indicate that a object is produced inside this model but cannot be used in other models, and the \emph{output} type is used to indicate that a object is produced by this model and can be used in other models (default=internal). 
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/place}
\end{center}

\clearpage

\subsection{\label{Transitions}Petri Net Transitions}

\noindent
Transitions are a special kind of event used Petri net models.  Each transition is composed of the following items:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Enabling condition: a mathematical formula which must evaluate to true for the transition to fire.
\item Delay: a mathematical formula which is evaluated when a transition becomes enabled, and the result is the amount of time before the transition is fired.
\item Priority: a mathematical formula which sets the priority for this transition when multiple transitions are scheduled to be executed simultaneously.  In this situation, the transition with the highest priority is the next to be executed.
\item Enabling is persistent: this Boolean indicates the behavior when an enabling condition becomes false before a transition is fired.  If it is persistent, then it still fires when ready.  If it is not persistent, then the transition is disabled and no longer scheduled to fire (default=false).
\item Fail transition: this Boolean indicates if the firing of this transition should be considered as a failure or not (default=false).
\item Is Mapped to a Port: this Boolean indicates whether this transition should be mapped to a port, so it can be replaced or deleted in hierarchical models.
\item List of Assignments: these indicate how the state is supposed to change when the transition fires.  Use the add, remove, and edit assignment buttons to update them.  In the assignment editor, the variable to change must be selected and the assignment to be performed must be specified as a mathematical formula.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/transition}
\end{center}

Places and transitions are connected to form a \emph{token flow relation}.  To connect a place to the \emph{preset} of a transition, select the place and, while holding the mouse button, drag the connection to the transition.  Similarly, to connect a place to the \emph{postset} of a transition, select a transition and, while holding the mouse button, drag the connection to the place.  A transition is enabled when all of its preset places are marked and its enabling condition is true. Once it is enabled, it can fire after the amount of time specified in the delay assignment has elapsed.  When multiple transitions can occur at the same time, the priority expression is evaluated.  The transition with the highest priority gets to fire first.  When a transition fires, it removes tokens from all preset places, and places tokens in all postset places.  Similarly, it will execute the assignments associated with the transition.

\begin{center}
\includegraphics[width=160mm]{screenshots/flowRelation}
\end{center}

\clearpage

\subsection{\label{Rules}Rules}

\noindent
There are three types of rules: algebraic, assignment, and rate rules:
\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}

\noindent
Algebraic rules specify relationships which must be maintained.  Assignment rules specify the value of a compartment size, species amount or concentration, or parameter in terms of a mathematical formula (see Section~\ref{SBMLMath}).  A quantity cannot be determined by both an assignment rule and an initial assignment (i.e., its initial value is an expression).  Rate rules specify the rate of change of a compartment size, species amount or concentration, or parameter in terms of a mathematical formula.  A quantity 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 (note that when editing a rule, the user cannot modify the rule type).  
This automatically restricts the set of quantities available for the left-hand side to those that are valid.  The user should then select a variable (except in the case of an algebraic rule) and enter a mathematical formula for the rule.  In addition, the following attributes can be edited for a rule:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Is Mapped to a Port: this Boolean indicates whether this rule should be mapped to a port, so it can be replaced or deleted in hierarchical models.
\item SBOL DNA Component: the Associate SBOL button allows the user to associate an SBOL DNA component with the rule (see Section~\ref{SBOL}).
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/rule}
\end{center}

\clearpage

\subsection{\label{Constraints}Constraints}

\noindent
Constraints are used to specify properties that should cause simulation to terminate.  As shown below, each constraint is composed of an ID which is used to identify it in graphs, a constraint given as a mathematical formula (see Section~\ref{SBMLMath}), and a message describing the constraint.  A default ID is automatically generated when a new constraint is created.
Special functions are provided to support a form of \emph{Continuous Stochastic Logic} (CSL) within these constraints (see Section~\ref{SBMLMath}).  

\begin{center}
\includegraphics[width=160mm]{screenshots/constraint}
\end{center}

Our analysis methods can provide histograms that show the proportion of simulations that are terminated due to a constraint.  Analysis can also show time-series plots showing the proportion of simulations at each time point that have terminated due to a constraint. 

\clearpage

\subsection{\label{Events}Events}

\noindent
Events are used to specify discrete changes of compartment sizes, species amounts or concentrations, and parameter values.  Each event is composed of the following items:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Trigger: a mathematical formula which, when it changes evaluation from false to true, indicates that the event is triggered.
\item Delay: a mathematical formula which is evaluated when an event is triggered, and the result is the amount of time before the event is to be executed.
\item Priority: a mathematical formula which sets the priority for this event when multiple events are scheduled to be executed simultaneously.  In this situation, the event with the highest priority is the next to be executed.
\item Use values at trigger time: this Boolean indicates if values for the event assignments should be calculated at trigger time or execution time (default=false).
\item Trigger is persistent: this Boolean indicates the behavior when a trigger expression becomes false before an event is executed.  If it is persistent, then it still executes when ready.  If it is not persistent, then the event is disabled and no longer scheduled to execute (default=false).
\item Trigger is initially true: this Boolean indicates the behavior when a trigger evaluates to true at time 0.  If it is initially true, there is no change in evaluation, so the event is not triggered.  If it is not initially true, there is now a change in evaluation, so the event is triggered.
\item Dynamic Process: indicates if this is a dynamic event.  The possible dynamic even types are symmetric and asymmetric cell division, cell death, and cell movement in a specified direction.
\item Is Mapped to a Port: this Boolean indicates whether this rule should be mapped to a port, so it can be replaced or deleted in hierarchical models.
\item List of Event Assignments: these indicate how the state is supposed to change when the event executes.  Use the add, remove, and edit assignment buttons to update them.  In the event assignment editor, the variable to change must be selected and the assignment to be performed must be specified as a mathematical formula.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/event}
\end{center}

\clearpage

\subsection{\label{Influences}Influences}

There are several types of influences between species that can be specified.  A species may \emph{activate} or \emph{repress} the production of other species.  This relationship is made from a species to the promoter that it activates or represses.  It can also be made directly between two species with an implicit promoter annotating the edge.  One can also specify when there is no influence between two species.  An activating or repressing self-influence can also be specified.  Species can also be related by complex-formation reactions, which indicate that multiple identical or different species can be combined to form a complex species.  

To add a complex-formation reaction, select the complex formation icon \includegraphics{../gui/icons/modelview/bio_activation_selected}, highlight a species that is part of a complex, and, while holding the mouse button, stretch the complex formation arc to the complex species.  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, which you can customize, if desired.

\begin{center}
\includegraphics[width=160mm]{screenshots/complex} 
\end{center}

To create a repression influence, select the Repression icon 
\includegraphics{../gui/icons/modelview/inhibition_selected}, highlight the species that is acting as a repressor, and, while holding the mouse button, stretch the repression arc to either the promoter or another species.  In the later, case, an implicit promoter is added.  Double clicking on the repression arc brings up an influence editor.  In this editor, you can customize the stoichiometry of binding as well as the repression binding equilibrium constant.  You can also change the type of influence, as well as, the promoter on which this influence takes place.  Note that pressing the Edit Promoter button brings up the Promoter Editor for the corresponding promoter (see Section~\ref{Promoters}). 

\begin{center}
\includegraphics[width=160mm]{screenshots/repression} 
\end{center}

To create an activation influence, select the Activation icon 
\includegraphics{../gui/icons/modelview/activation_selected}, highlight the species that is acting as an activator, and while holding the mouse button stretch the activation arc to either the promoter or another species.  In the latter case, an implicit promoter is added.  Double-clicking on the activation arc brings up an influence editor.  In this editor, you can customize the stoichiometry of binding as well as the activation binding equilibrium constant.  You can also change the type of influence, as well as, the promoter on which this influence takes place.  

\begin{center}
\includegraphics[width=160mm]{screenshots/activation}
\end{center}

To indicate that a species has no influence on another species, select the No Influence icon 
\includegraphics{../gui/icons/modelview/no_influence_selected}, highlight the species that has no influence, and, while holding the mouse button, stretch the no-influence arc to the species it has no influence upon.  Double-clicking on the no-influence arc brings up an influence editor.  In this editor, you can change its type to indicate that it actually has an influence, if you like, and edit accordingly.  No-influence arcs are used by the Learn Tool to avoid adding influences where you are certain there isn't one.  You can also change the type of influence, as well as, the promoter on which this species has no influence.  

\begin{center}
\includegraphics[width=160mm]{screenshots/noInfluence}
\end{center}

The last type of influence is a self-influence.  A self-influence can be either activation or repression.  To create a self-influence, select the Self-influence icon \includegraphics{../gui/icons/modelview/self_influence_selected}, select the appropriate Activation or Repression icon, and click on the species that influences itself.  If you click on a self-influence, you will be able to edit its promoter, its type of influence, its stoichiometry of binding, as well as the appropriate binding equilibrium constant. 

\begin{center}
\includegraphics[width=160mm]{screenshots/selfInfluence}
\end{center}

\clearpage

\subsection{\label{ModelEditor}Model Editor}

\noindent
Clicking on the Model button on the schematic tab brings up the Model Editor.  This editor includes:
\begin{itemize}
\item Model ID: a unique ID composed only of alphanumeric characters and underscores.  This cannot be changed here.  To change it, you must rename the model file.
\item Name: an arbitrary string description (optional).
\item Substance units: the default units for species.
\item Time units: the default units for time.
\item Volume units: the default units for 3-dimensional compartments.
\item Area units: the default units for 2-dimensional compartments.
\item Length units: the default units for 1-dimensional compartments.
\item Extent units: the default units for the amount changed due to a reaction.  Kinetic laws have default units of extent units / time units.  
\item Conversion factor: the constant global parameter to be used as the default conversion factor to convert species units into extent units.
\item Conversion factor indices: used to reference a conversion factor in a parameter array.
\item SBOL DNA Component: the Associate SBOL button allows the user to associate an SBOL DNA component with the model (see Section~\ref{SBOL}).
\item Flux Objective: add/edit flux balance objectives for a flux balance model.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/ModelUnits}
\end{center}

\clearpage

\subsection{\label{Constants}Constants}

\noindent
The Constants tab includes a list of all the constant global parameters.  They are not included in the schematic, but they can appear in math formulas (see Section~\ref{SBMLMath}).  This tab can be used to add, remove, or edit these constants.  The following attributes can be edited for a global parameter:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Port Type: used to indicate how this object can be connected in hierarchical models.  The \emph{input} type is used to indicate a object that is produced outside this model, the \emph{internal} type is used to indicate that a object is produced inside this model but cannot be used in other models, and the \emph{output} type is used to indicate that a object is produced by this model and can be used in other models (default=internal). 
\item Initial value: initial value for the parameter.  This value can be a mathematical expression (see Section~\ref{SBMLMath}) which is called an \emph{initial assignment}.
\item Units: the units for the parameter value (default=none).
\item Constant: Boolean indicating if the parameter value is constant (default=true).
\item SBOL DNA Component: the Associate SBOL button allows the user to associate an SBOL  with the promoter (see Section~\ref{SBOL}).
\end{itemize}
Note that changing the Constant attribute to false removes the parameter from the constants list, and it places the parameter on the schematic.

\begin{center}
\includegraphics[width=160mm]{screenshots/GCMparam}
\end{center}

\noindent
Some constants are added to the model automatically because they are needed to provide default parameter values when converting genetic regulation elements into a reaction-based model.  
In the Species, Promoter, and Influence Editors, any parameter set to default uses the value found in this list.  These defaults can be modified in the user preferences (see Section~\ref{Preferences}).  The user can also edit these parameters for an individual model here.  
The complete list of model generation parameters is listed below:

\begin{center}
\begin{tabular}{|c|c|c|c|c|}
\hline
ID & Default Value & Units      & Structure & Description \\ \hline \hline
ka & 0.25          & $\frac{1}{\mathrm{sec}}$ & promoter  
& Activated production rate\\ \hline 
Ka & 0.0033        & $\frac{1}{\mathrm{molecule}^{(nc+1)}}$ & influence
& Activation binding equilibrium \\ \hline
kb & 0.0001        & $\frac{1}{\mathrm{sec}}$ & promoter  
& Basal production rate \\ \hline
kd & 0.0075        & $\frac{1}{\mathrm{sec}}$ & species   
& Degradation rate \\ \hline
kecd & 0.005        & $\frac{1}{\mathrm{sec}}$ & species   
& Extracellular degradation rate \\ \hline
nc & 2             & molecule   & influence  & Stoichiometry of binding \\ \hline
nr & 30            & molecule   & model     & Initial RNAP count \\ \hline
ng & 2             & molecule   & promoter  & Initial promoter count \\ \hline
ko & 0.05          & $\frac{1}{\mathrm{sec}}$ & promoter  
& Open complex production rate \\ \hline
Ko & 0.033         & $\frac{1}{\mathrm{molecule}}$ & promoter  
& RNAP binding equilibrium\\ \hline
Kao & 1         & $\frac{1}{\mathrm{molecule}}$ & promoter  
& Activated RNAP binding equilibrium\\ \hline
Kr & 0.5           & $\frac{1}{\mathrm{molecule}^{nc}}$ & influence
& Repression binding equilibrium \\ \hline
np & 10            & molecule   & promoter  & Stoichiometry of
production \\ \hline
Kc & 0.05          & $\frac{1}{\mathrm{molecule}}$ & species
& Complex formation equilibrium \\ \hline
kmdiff\_f & 1.0          & $\frac{1}{\mathrm{molecule}}$ & species   
& Forward membrane diffusion rate\\ \hline
kmdiff\_r & 0.01          & $\frac{1}{\mathrm{molecule}}$ & species   
& Reverse membrane diffusion rate\\ \hline
kecdiff & 1.0          & $\frac{1}{\mathrm{molecule}}$ & species   
& Extracellular diffusion rate\\ \hline
\end{tabular}
\end{center}

\clearpage

\subsection{\label{Functions}Functions}

\noindent
The functions tab is used to add, remove, and edit function definitions. Function definitions are used to create user-defined functions that can then be used in math formulas (see Section~\ref{SBMLMath}).  As shown below, function definitions include:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Arguments: a comma-separated list of arguments for the function.
\item Definition: a math formula, though it is restricted to the use of variable names which are arguments to the function.
\item Is Mapped to a Port: this Boolean indicates whether this transition should be mapped to a port, so it can be replaced or deleted in hierarchical models.
\end{itemize}
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).  

\begin{center}
\includegraphics[width=160mm]{screenshots/function}
\end{center}

\clearpage

\subsection{\label{Units}Units}

\noindent
The Units tab is used to add, remove, and edit unit definitions.  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:
\begin{itemize}
\item ID: a unique ID composed only of alphanumeric characters and underscores.
\item Name: an arbitrary string description (optional).
\item Is Mapped to a Port: this Boolean indicates whether this transition should be mapped to a port, so it can be replaced or deleted in hierarchical models.
\item List of Units: the units that make up the unit definition.  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.  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*}
\end{itemize}

\begin{center}
\begin{tabular}{|c|c|c|c|c|c|}
\hline
ampere        & farad  & joule    & lux  & radian    & volt \\ \hline
avogadro     & 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
\end{tabular}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/units}
\end{center}

\clearpage

\section{\label{SBOL}SBOL Editors}

SBOL is an emerging standard under development for the exchange of information about synthetic biology designs.  An SBOL file includes \emph{Collections} of \emph{DNA Components}.  Each DNA component has a unique ID, name, description, \emph{Sequence Ontology} type, and a DNA sequence.  A DNA component can be a simple sequence feature such as a \emph{promoter}, \emph{ribosome entry site}, \emph{coding sequence}, or \emph{terminator}.  It can also be a region of DNA annotated with several of these individual features.  For example, a DNA component that is a gene may have its sequence annotated with a promoter DNA component followed by components for a ribosome binding site, a coding sequence, and a terminator.  {\tt iBioSim} includes an SBOL browser that allows the user to view an individual SBOL file by clicking on it in the list of project files.  In this browser, the user can highlight individual DNA components and see the information stored about them.  The user can also filter the list by SO type by selecting the desired type from a list.

\begin{center}
\includegraphics[width=160mm]{screenshots/SBOLBrowser}
\end{center}

When the user clicks on an Associate SBOL button in the editor for a model element, it opens up a window that includes an ordered list of DNA components associated with that model element.  In this window, highlighting a DNA component and pressing the Remove button removes this component from the list.  Pressing the Add button opens an SBOL Browser that can be used to find a DNA component to add to this list.  By selecting a DNA component and pressing OK, the selected component is added to the list.  It is added to the end of the list when no component is highlighted in the list, and it is added before the highlighted component otherwise.

\begin{center}
\includegraphics[width=100mm]{screenshots/AssociateSBOL}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/AssociateSBOLBrowser}
\end{center}

The SBOL Association window is a bit different when associating SBOL to the SBML model itself as opposed to the individual model elements.  In particular, this window includes a button to Add/Move Composite.  Upon save, any model which has SBOL associated with some of its elements automatically generates a composite DNA component which is typically associated with the model itself.  It is possible, though, to add additional DNA components either before or after this composite component.  One can also remove the composite DNA component and replace it with a DNA component from an SBOL file.  The purpose of the Add/Move Composite button is to restore the composite component to the list if it has been removed.  This button has the added functionality of moving the composite component before the highlighted component if the former is currently in the list.

\begin{center}
\includegraphics[width=160mm]{screenshots/AssociateSBOLModel}
\end{center}

The last SBOL window is the Composite SBOL Descriptors window which is opened by pressing the SBOL button on the schematic.  In this window, the user can select which SBOL file in which to store the composite DNA component generated for this model upon save.  The user can also specify the ID, name, and description for this composite component.  When the user saves this model, this information is stored as part of the composite component in the specified SBOL file.

\begin{center}
\includegraphics[width=160mm]{screenshots/SBOLbutton}
\end{center}

\clearpage

\section{\label{Analysis}Analysis Tool}

\noindent
The analysis tool is used to analyze biochemical reaction network models.  {\tt iBioSim} comes with a number of simulation methods, ranging from continuous-deterministic (ODE) simulation methods to discrete-stochastic (Monte Carlo) simulation methods.  In order to perform efficient temporal behavior analysis, various model abstractions can also be automatically applied.  Many of the analysis and abstraction 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}
  An analysis view includes several tabs.  The Simulation Options tab, described in Section~\ref{simOptions}, selects the different simulation methods and parameters.  The Abstraction Options tab described in Section~\ref{absOptions} configures model abstraction.  The Schematic tab, described in Section~\ref{AnalysisSchematic}, allows the user to modify or sweep various parameters on the schematic.  It also provides an alternative way of visualizing simulation data upon the schematic.  The Parameters tab allows the user to modify or sweep global parameters, and it is described in Section~\ref{AnalysisParameters}.  The SBML elements tab described in Section~\ref{SBMLElements} allows the user to add or remove parts of the model during analysis.  The TSD Graph tab is a graph editor for time series data, and it is described in Section~\ref{TSDGraph}.  Finally, the Histogram tab is a graph editor for probability data, and it is described in Section~\ref{Histogram}.

\subsection{\label{simOptions}Simulation Options}

\noindent
The first set of radio buttons in this tab specifies the type of abstraction. 
\begin{itemize}
\item None: use no abstraction.
\item Abstraction: perform reaction-based abstraction.
\item Logical Abstraction: perform both reaction-based and logical abstractions.
\end{itemize}
The second set of radio buttons specify the type of analysis.  
\begin{itemize}
\item ODE: perform continuous-deterministic simulation.
\item Monte Carlo: perform discrete-stochastic simulation.
\item Markov: perform temporal probability distribution analysis on finite-state Markov chain models (this option requires logical abstraction).
\item Model: produces a flattened model and puts it in the list of project files.
\item Network: outputs the model in the GraphViz format for display by dotty.
\item Browser: outputs the model in xhtml format for display in a web browser.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/analysisView}
\end{center}
 
Some results selecting Model, Network, and Browser options are shown below.

\begin{center}
\includegraphics[width=160mm]{screenshots/reactionModel}
\end{center}

\begin{center}
\includegraphics[width=120mm]{screenshots/viewNetwork}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/viewBrowser}
\end{center}

\noindent
The next group of options are for simulation-based analysis only.
\begin{itemize}
\item Report concentrations: if checked, report concentrations rather than amounts (default=Amounts).
\item Do Not Generate Runs: if checked, simulation data is not produced, though summary probabilistic data is still produced (default=Generate Runs).
\item Append Simulation Runs: if checked, additional simulation runs are added to the existing set of simulation runs rather than first removing the previous runs (default=Overwrite).  Note that the seed changes automatically when this gets checked, because otherwise the additional runs will be the same as the previous set.
\item Generate Statistics: if checked, statistics such as average and standard deviation data are generated immediately after completing simulation.  Otherwise, they are only generated on demand (i.e., for example, when included in a TSD graph).
\end{itemize} 

\noindent
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 
ODE  & Runge-Kutta-Fehlberg & Runge-Kutta-Fehlberg method (java)\\ \hline 
Monte Carlo & gillespie & SSA-direct method \\ \hline   
Monte Carlo & SSA-Hierarchical & SSA-direct method on hierarchical models (java) \\ \hline    
Monte Carlo & SSA-Direct & SSA-direct method (java) \\ \hline    
Monte Carlo & SSA-CR & SSA composition and rejection method (java) \\ \hline  
Monte Carlo & iSSA & incremental SSA \\ \hline    
Monte Carlo & interactive & Interactive SSA-direct method \\ \hline  
Monte Carlo & emc-sim   & Uses 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 
Markov & steady-state & Steady-state Markov chain analysis \\ \hline
Markov & transient & Transient Markov chain analysis \\ \hline
Markov & reachability & Only perform reachability analysis \\ \hline
Markov & atacs & Use {\tt atacs} steady-state Markov analysis engine \\ \hline
Markov & ctmc-transient & Transient distribution analysis \\ \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
Choose one:    &  \\ \hline
~~~Print Interval    & The print time interval for each simulation run \\ \hline 
~~~Minimum Print Interval    & Print on change but no more often than this interval \\ \hline  
~~~Number of Steps    & Number of steps to print \\ \hline  
Minimum Time Step & The smallest time step allowed \\ \hline
Maximum Time Step & The largest time step allowed \\ 
      ~           & (also the time step used 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 random simulation runs to perform \\ \hline
Simulation ID     & Creates a simulation directory with the ID name \\ \hline
\end{tabular}
\end{center}

\clearpage

\subsection{\label{absOptions}Advanced Options}

\noindent
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.
{\tt iBioSim} supports many different types of abstraction.  However, there are a few critical ones that we list here:
\begin{itemize}
\item complex-formation-and-sequestering-abstraction: this attempts to remove complex formation reactions.  It replaces the complex species in rate laws with a function of its constituent species.
\item operator-site-reduction-abstraction: this removes reactions and corresponding species involved in the binding of transcription factors to operator sites.
\item distribute-transformer: applies the distributive law to kinetic law formulas to make it easier to identify the forward and reverse rates within a reversible reaction.
\item reversible-to-irreversible-transformer: this converts a reversible reaction into two irreversible reactions.  This is critical for the Monte Carlo simulation methods that require there to be no reversible reactions.
\item kinetic-law-constants-simplifier: this replaces constant parameters within kinetic laws with their values to improve their evaluation time.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/absOptions}
\end{center}

This tab also includes a few parameters for the 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 QSSA Condition: specifies threshold T used by the QSSA abstraction method where $T > E0 / (S0 + KM)$.
\item 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. 
\item Grid Diffusion Stoichiometry Amplification: the number of molecules that are moved per diffusion reaction. 
\end{itemize}
Note that these are not used by the common abstractions listed above.

Finally, there are a few options used by the incremental SSA simulation method.  The user can select the type of iSSA (MPDE, Mean Path, or Median Path).  The user can also select whether or not to use an adaptive time step.  Finally, the user can select the number of paths to follow during the iSSA.

%% 
% 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.

\clearpage

\subsection{\label{AnalysisSchematic}Schematic}

\noindent
Using the schematic tab, you can 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.  
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.  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.  

\begin{center}
\includegraphics[width=160mm]{screenshots/paramEdit}
\end{center}

%\begin{center}
%\includegraphics[width=160mm]{screenshots/sweep}
%\end{center}

The schematic tab can also be used to visualize simulation results.  To do this, after you have generated some simulation results, you can press the Choose Simulation button to bring up a window with all the simulations in this analysis view.  You can then select the data that you would like to visualize.

\begin{center}
\includegraphics[width=160mm]{screenshots/chooseSim}
\end{center}

If you now click on a species, component, or grid location, you can modify how it appears 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.  Appearances can be saved by clicking the save button.

\begin{center}
\includegraphics[width=160mm]{screenshots/editSpeciesAppearance}
\end{center}

The appearances editor for components and grid locations is similar.  The differences are that you can select any species within the component (or diffusible species for the grid location).  You also can copy the settings to all instantiations of the same model.

\begin{center}
\includegraphics[width=160mm]{screenshots/compAppearances}
\end{center}

Once you have made your selections, you can now playback 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.  The slider can be dragged around to quickly reach a particular spot in simulation

\begin{center}
\includegraphics[width=160mm]{screenshots/movieView}
\end{center}

\clearpage

\subsection{\label{AnalysisParameters}Parameters}

\noindent
The parameter tab allows the user to modify the value of any model generation or global parameter for a given analysis.  Like the values on the schematic tab, they can also be swept to generate multiple simulation runs stepping through different values.

\begin{center}
\includegraphics[width=160mm]{screenshots/parameterEditor}
\end{center}

\subsection{\label{SBMLElements}SBML Elements}

\noindent
The SBML elements tab allows you to select which SBML model elements to include in your analysis.  This includes initial assignments, rules, constraints, and events.  Elements that are checked are used during analysis.  Otherwise, they are not used.

\begin{center}
\includegraphics[width=160mm]{screenshots/SBMLElements}
\end{center}

\clearpage

\section{\label{Learn}Learn Tool}

\noindent
The Learn Tool is used to discover genetic circuit connectivity from time series data.  This tool uses the GeneNet algorithm described in
%%tth:\begin{html}<A HREF="http://www.async.ece.utah.edu/publications">\end{html}
Barker's PhD dissertation (University of Utah 2007).
%%tth:\begin{html}</A>\end{html}
  The first tab of the Learn Tool is the \emph{data manager} which is shown below.  It 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[width=160mm]{screenshots/dataManager}
\end{center}

\noindent
The second tab allows the user to configure the basic options for the Learn Tool.  The basic options include:
\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}

\begin{center}
\includegraphics[width=160mm]{screenshots/learn}
\end{center}

The third tab allow the user to select some advanced options for the Learn Tool.  These include:
\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.
\item View Log button:\\
Opens a window containing the log file generated by GeneNet during the learn process for debugging purposes.  
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/advLearn}
\end{center}

Once the Learn Tool has been provided data and configured as desired, pressing the Save and Run icon \includegraphics{../gui/icons/run-icon} causes the tool to attempt to produce a model that may have produced this data.  The resulting model is displayed using GraphViz, and the user is prompted to provide a model ID for the resulting model.  If learning fails, an error message will be reported instead.

\clearpage

\section{\label{TSDGraph}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 in the File menu. 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[width=160mm]{screenshots/ssaSimResults}
\end{center}

In the TSD 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. 
\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. 
\item X-Axis Combo Box - selects which variable to use for the x-axis (default=time).
\item LogX - selects that the scale of the x-axis should be logarithmic.
\item LogY - selects that the scale of the y-axis should be logarithmic.
\item Visible Legend - selects that the legend should appear on the graph.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{screenshots/ssaResults}
\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 are organized hierarchically.  Hierarchy is also introduced when different simulations in an analysis view are given different simulation IDs or after performing an analysis while sweeping parameter values.  In addition to being able to plot results from individual simulation runs, the average, standard deviation, and variance are also provided.  Finally, when constraints are used, the Termination Time and Percent Termination data is also computed.  The Termination Time gives a plot of the number of runs that have terminated versus time, while Percent Termination gives the percentage of runs that have terminated versus time.

After selecting a data set, one can select individual variables (typically 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 Color Palette - clicking on the color palette lets one customize the color selection. 
\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}
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.

When in a TSD graph editor, pressing the Save icon \includegraphics{../gui/icons/save} 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.  Pressing the Save As icon \includegraphics{../gui/icons/saveas} prompts for a new filename and creates a new top-level graph with that name.  Finally, pressing the Export icon \includegraphics{../gui/icons/export} 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 Time series data format (tsd), see Section~\ref{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}
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. 

\clearpage

\section{\label{Histogram}Histogram Graph Editor}

\noindent
{\tt iBioSim} includes a histogram graph editor for visualizing probability data.  In particular, this editor can display the reasons that a simulation terminated.  Namely, it displays statistics on which constraints failed to hold, allowing the user to determine the likelihood of various conditions.  The histogram graph editor appears as a tab in analysis
views.  Histograms 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$ Histogram menu option in the File menu. Once created, they can be viewed and edited by double-clicking on the graph in the project window.  An example histogram is shown below.

\begin{center} 
\includegraphics[width=160mm]{screenshots/probResults}
\end{center}

In the histogram 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. 
\item Paint in Gradient Style - creates a color gradient in the bars.
\item Paint Bar Shadows - enables the bars to cast shadows.
\item Visible Legend - selects whether a legend should be included in the graph.
\end{itemize}

\begin{center}
\includegraphics[width=160mm]{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 are organized hierarchically.  Hierarchy is also introduced when different simulations in an analysis view are given different simulation IDs or after performing an analysis while sweeping parameter values.  After selecting a data set, one can select individual constraints to graph.  The constraint labeled time-limit indicates that the simulation terminated while all constraints were still satisfied.  One can also select how each result is 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 Constraint Label - sets the name displayed in the legend. 
\item Drop Down Menu Of Colors - the color of the bar used for this constraint.
\item Color Palette - clicking on the color palette lets one customize the color selection. 
\end{itemize}
Note that a checkmark 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.

When in a histogram graph editor, pressing the Save icon \includegraphics{../gui/icons/save} 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.  Pressing the Save As icon \includegraphics{../gui/icons/saveas} prompts for a new filename and creates a new top-level graph with that name.  Finally, pressing the Export icon \includegraphics{../gui/icons/export} 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 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}
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. 

\clearpage

\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, under the General Preferences tab, the user can decide whether they wish to:
\begin{itemize}
\item Use a File Dialog for selecting files or the default Java File Chooser.  
\item Use plus/minus for expanding and collapsing file trees.  
\item Want to confirm file deletions.
\item Use the libsbml or the {\tt iBioSim} flatten procedure.
\item Use the libsbml or a webservice to validate models.
\item Whether or not to report validation warnings.
\item The command to open html or xhtml files in a browser.
\item The command to open Graphviz files.
\end{itemize}
The Restore Defaults button on this tab and the others restores the default preferences.  In the Schematics preference tab, the user can decide the shape, color (fill, stroke, and font), and opacity for each schematic object.  The Model Preferences tab allows users to select whether they wish to see warnings about undeclared units in SBML and whether they wish to check units at all.  It also allows users to change the default model generation parameter values.  The Analysis Preferences tab allows users to change the default values used by the analysis tool.  The simulation command in particular can be useful to select an alternative simulator.  We've used it to select a script that executes the simulation on a compute server.  The SBOL Assembly Preferences tab allows the user to select a default URI authority for composite SBOL DNA components generated by iBioSim, a regular expression for validating the SO types of the subcomponents making up these generated components, whether to validate assembled constructs, and whether to give an incomplete construct warning.  Finally, the Learn Preferences tab allows users to change the default values used by the learn tool.

\begin{center}
\begin{tabular}{cc}
\includegraphics[width=80mm]{screenshots/GenPref} &
\includegraphics[width=80mm]{screenshots/SchPref} 
\end{tabular} \\
\begin{tabular}{cc}
\includegraphics[width=80mm]{screenshots/SynPref} &
\includegraphics[width=80mm]{screenshots/ModelPref}
\end{tabular} \\
\begin{tabular}{cc}
\includegraphics[width=80mm]{screenshots/AnaPref} &
\includegraphics[width=80mm]{screenshots/LearnPref}
\end{tabular}
\end{center}

%% 
% \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{\label{SBMLMath}Mathematical Formulas}

\noindent
Math formulas appear in many model constructs.  These formulas are expressed as text strings using a simple syntax.  In particular, model math formulas can include: 
\begin{itemize}
\item Variables (compartments, species, parameters, reaction IDs, and species reference IDs).
\item Real numbers followed optionally by its units.
\item Vector constant (\{~\}) which can be nested.
\item Array selector(s) ([~]) can occur after array variables or vector constants.  
\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 (/), power (\^{} or pow(x,y)), root(x,y), quotient(x,y), rem(x,y), min, and max.
\item Rate function (rateO(x)) that returns the current rate of change of compartment, species, or parameter.
\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.
\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 the otherwise value.
\end{itemize}

{\tt iBioSim} simulators support a few special purpose built-in functions that are not standard parts of SBML.  These include:
\begin{itemize}
\item $\mbox{rate}(a)$ - returns the current rate of change for $a$.
\item $\mbox{BIT}(a,b)$ - assuming $a$ is an expression that evaluates to an integer, this returns the bit at location specified by expression $b$.
\item $\mbox{BITNOT}(a)$ - assuming $a$ is an expression that evaluate to an integer, this returns bitwise NOT of $a$.
\item $\mbox{BITAND}(a,b)$ - assuming $a$ and $b$ are expressions that evaluate to integers, this returns bitwise AND of $a$ and $b$.
\item $\mbox{BITOR}(a,b)$ - assuming $a$ and $b$ are expressions that evaluate to integers, this returns bitwise OR of $a$ and $b$.
\item $\mbox{BITXOR}(a,b)$ - assuming $a$ and $b$ are expressions that evaluate to integers, this returns bitwise XOR of $a$ and $b$.
\item $\mbox{mod}(a,b)$ - assuming $a$ and $b$ are expressions that evaluate to integers, this returns the remainder after dividing $a$ by $b$ (i.e., $a-floor(a/b)*b)$).
\end{itemize}
{\tt iBioSim}'s simulators also support several random functions which are added by default to any model file.  The following random functions, therefore, can also be used in model 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}
Finally, {\tt iBioSim} includes built-in functions to support stochastic model checking of CSL formulas.  CSL is a temporal logic which allows one to specify probabilistic temporal logic properties.  Analysis of a CSL property should return the probability that the property is true.  These properties can either be transient properties to ask if something happens within a certain amount of time, or steady-state properties to ask the probability of a given state as time goes to infinity.  The built-in functions include:
\begin{itemize}
\item $PG(t,x)$ - returns the probability that the expression $x$ remains true during the time period specified by the expression $t$.
\item $G(t,x)$ - returns true if the expression $x$ remains true during the time period specified by expression $t$ (i.e., $\neg t \vee x$). 
\item $PF(t,x)$ - returns the probability that the expression $x$ becomes true during the time period specified by the expression $t$.
\item $F(t,x)$ - returns false if the expression $x$ becomes true during the time period specified by the expression $t$ (i.e., $\neg t \vee \neg x$). 
\item $PU(t,x,y)$ - returns the probability that the expression $x$ remains true until $y$ becomes true, and $y$ becomes true during the time period specified by the expression $t$.
\item $U(t,x,y)$ - returns true if the expression $x$ remains true until $y$ becomes true, and $y$ is true by the time specified by expression $t$ (i.e., $G(t,x) \wedge F(t,y)$). 
\end{itemize}

\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{Tutorials}

\noindent
There is a detailed systems biology oriented 
%%tth:\begin{html}<a href="iBioSim_SysBio_Tutorial.html">\end{html}
tutorial 
%%tth:\begin{html}</a>\end{html}
that uses the phage $\lambda$ decision circuit as an example.
There is also a separate synthetic biology oriented
%%tth:\begin{html}<a href="iBioSim_SynBio_Tutorial.html">\end{html}
tutorial
%%tth:\begin{html}</a>\end{html}
that uses the genetic toggle switch as an example.
These are located in the {\tt docs} directory that comes with the distribution.

\section{Submitting Bugs and Feature Requests}

\noindent
When there is an un-handled exception, the window below allows the user to see more details about the exception.  These are likely not particularly useful to a user, but they are useful to us.  Therefore, the user can also submit this information as a bug report.  To make the bug report more useful, please provide an email address, a brief description of the bug, and a detailed description about how the bug occurred.  While all these fields are optional, the more information provided, the better.  A report can also be submitted from the Help menu.  In this case, the user can select whether the report is a BUG (an error or crash of the software), a CHANGE (something which can be improved), or a FEATURE (something new).  Finally, report can be submitted by sending 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}
Note that the subject line must begin with the keyword BUG, CHANGE, or FEATURE or the
mail will be filtered by our spam filters.

\begin{center}
\includegraphics[width=60mm]{screenshots/exception}
\end{center}

\begin{center}
\includegraphics[width=160mm]{screenshots/bugReport}
\end{center}

\end{document}