\documentclass[english]{article}
\usepackage{natbib}
\usepackage{hyperref}
\bibliographystyle{abbrvnat}

\begin{document}
\title{Quick Introduction to the rsbml Package}
%\VignetteIndexEntry{Quick start for rsbml}
\author{Michael Lawrence}

\maketitle

\section*{Introduction}
The \emph{rsbml} package supports the import, validation, and export of SBML data. 
It is similar in purpose to the \emph{SBMLR} package \citep{sbmlr}, except \emph{rsbml}
relies on the external library \emph{libsbml} \citep{libsbml} for its speed and reliability.
With \emph{rsbml}, the user may import an SBML model as a \emph{graph} object
or an S4-based Document Object Model (DOM). Parsed models may be checked
for consistency. \emph{rsbml} is capable of checking models for consistency
and exporting SBML to a character vector or directly to a file. This vignette 
provides a quick introduction to \emph{rsbml},
demonstrating how to import an SBML model, manipulate the model in R as a graph
or S4 object, validate the model, and export the model.

\section*{Importing an SBML document}
Most users will begin an rsbml session by importing an SBML file into R.
In the example below, we load an SBML file describing the glycolysis pathway.
It is also possible to parse an R character vector instead of an external file.

<<read>>=
library(rsbml)
doc <- rsbml_read(system.file("sbml", "GlycolysisLayout.xml", package = "rsbml"), dom = FALSE)
@

If errors are encountered, the function throws an error along with
warnings describing the specific problem(s) with the document.
Otherwise, the result is an opaque object referring to a low-level 
libsbml data structure. From here, the user currently has two options for 
accessing the data: as an S4 object conforming to the SBML document object 
model or as a Bioconductor graph object.

\section*{The S4 object representation}
Converting the opaque libsbml parse result to an S4 object is simple:

<<dom>>=
dom <- rsbml_dom(doc)
@

The result contains all of the information from the SBML. Methods exist for
accessing every element of the SBML specification (up to L2V1). Here is how
one would retrieve all of the species ID's from the SBML model:

<<ids>>=
sapply(species(model(dom)), id)
@

The user may also modify every part of the model. Note that very little 
validation is performed in response to modifications. See \ref{sec:checking} for
a guide to checking SBML models for consistency problems.

\section*{The graph representation}
All SBML models have an implicit graphical structure. To extract this into
a Bioconductor graph object, type the following:

<<graph>>=
g <- rsbml_graph(doc)
graph::nodes(g)
@

Note that the list of node ID's contains all of the species ID's retrieved from
the S4 object above. The additional ID's are for the reaction nodes.
At this point, the graph can be passed to other packages, such as RBGL, Rgraphviz, etc.

\section*{Checking SBML models for consistency}\label{checking}
The SBML specification provides many complex rules that ensure an SBML model
is internally consistent. The following is an example of checking a document
against those rules.

<<check>>=
rsbml_check(doc)
@

If there were any problems with the document, they would be communicated as
R console messages, warnings or errors. If you would like to compute on 
the problems, you will need to catch the conditions thrown by the
\texttt{rsbml\_read} function. There are three different types of
conditions: \textit{SBMLFatal}, \textit{SBMLError} and
\textit{SBMLWarning}. \textit{SBMLFatal} and \textit{SBMLError} both
inherit from \textit{error}, while \textit{SBMLWarning} inherits from
\textit{warning}. The following code catches the error
resulting from a non-existent file and prints the message:
<<problems>>=
tryCatch(rsbml_read("non-existent-file.xml"), 
         error = function(err) err$msg)
@

\section*{Writing SBML documents}
After creating/manipulating SBML objects in R, the result may be translated
back to XML in two different ways: directly to a file or to an R character vector.
This example is of the latter:

<<xml>>=
xml <- rsbml_xml(doc)
@

The result is a string XML representation of the SBML model.

\section*{More information}
For more details, please see the online help for the rsbml package. If you
encounter problems, please email lawremi at the domain iastate.edu.

\bibstyle{}
\bibliography{rsbml}

\end{document}