%\VignetteIndexEntry{Getting started with rbiouml}
%\VignetteKeywords{BioUML}
\documentclass[12pt]{article}
\usepackage{amsmath}
\usepackage{hyperref}
\usepackage[authoryear,round]{natbib}

\textwidth=6.2in
\textheight=8.5in
\oddsidemargin=.1in
\evensidemargin=.1in
\headheight=-.3in

\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}

\SweaveOpts{eval=FALSE}

\author{Ivan Yevshin and Tagir Valeev}

\begin{document}
\title{Description of rbiouml package}

\maketitle
\tableofcontents
\section{Introduction}
The \Rpackage{rbiouml} package provides functions to interact with BioUML server from within R.
BioUML is an open source integrated Java platform for analysis of data from omics sciences research and other advanced computational biology,
for building the virtual cell and the virtual physiological human.
It spans a comprehensive range of capabilities, including access to databases with experimental data,
tools for formalized description of biological systems structure and functioning, as well as tools for their visualization, simulation, parameters fitting and analyses.
\section{Getting started}
\subsection{Connecting to BioUML server}
The first thing you need to do is load the package and login to the BioUML server.
As an example we will connect to the free public BioUML server at \url{https://ict.biouml.org}. 
The function \Rfunction{biouml.login} connects to BioUML server and perform authentication.
<<>>=
library(rbiouml)
biouml.login("https://ict.biouml.org")
@
The \Rfunction{biouml.login} also accepts user and password, but we leave them empty in the example above for anonymous login.
Alternatively you can install BioUML on your local computer and connect to it in the same way.
\begin{Sinput}
> biouml.login("localhost:8080")
\end{Sinput}
See \url{http://wiki.biouml.org/index.php/BioUML\_server\_installation} for details on BioUML server installation.

\subsection{Querying BioUML repository}
The BioUML repository (or simply repository) is the central BioUML data storage place.
Basically, all the data you work with in BioUML is stored in the repository.
The repository has a hierarchical structure similar to file systems.
On the top level the repository consists of several root folders.
The most common ones are:
\begin{description}
\item[databases] contains preinstalled or user-defined modules.
\item[data] contains user projects and public examples. 
\end{description}
The \Rfunction{biouml.ls} function lists the contents of given folder in repository.
The list of databases available in BioUML server:
<<>>=
biouml.ls("databases")
@
\begin{verbatim}
 [1] "Biomodels"                         "EnsemblArabidopsisThaliana91"     
 [3] "EnsemblFruitfly91"                 "EnsemblHuman85_38"                
 [5] "EnsemblMouse81_38"                 "EnsemblNematoda91"                
 [7] "EnsemblRat91"                      "EnsemblSaccharomycesCerevisiae91" 
 [9] "EnsemblSchizosaccharomycesPombe91" "EnsemblZebrafish92"               
[11] "GTRD"                              "HOCOMOCO v11"                     
[13] "PantherDB 14"                      "Reactome Icons"                   
[15] "Reactome63"                        "Tests SBML 3.3.0"                 
[17] "Tests Stochastic"                  "Virtual Cell"                     
[19] "Virtual Human"                    
\end{verbatim}

The list of data elements available in BioUML examples folder:
<<>>=
biouml.ls("data/Examples/Optimization/Data/Experiments")
@
\begin{verbatim}
[1] "exp_data_1" "exp_data_2" "exp_data_3"
\end{verbatim}

The \Rfunction{biouml.get} fetches a table from BioUML repository as R data.frame:
<<>>=
x <- biouml.get("data/Examples/Optimization/Data/Experiments/exp_data_1")
head(x)
@
\begin{verbatim}
  time      p43p41     pro8      casp8
0    0  0.05772537 59.96316 0.00000000
1   10  0.26814367 57.56464 0.04107502
2   20  4.76048117 58.58981 0.31611658
3   30  8.25193519 59.42156 1.39735609
4   45 16.14448337 48.18975 3.52037089
5   60 17.02060557 38.95027 3.94722894
\end{verbatim}


This function allows to fetch not only true BioUML tables, but any data elements which have tabular
representation, including profiles, user uploaded tracks and so on.

To store data.frame as a table into BioUML repository use \Rfunction{biouml.put} function:
<<>>=
x[,5] <- x[,3] + x[,4]
biouml.put("data/Collaboration/Demo/tmp/exp_data_1_sum", x)
biouml.ls("data/Collaboration/Demo/tmp")
@
\begin{verbatim}
[1] "exp_data_1_sum"
\end{verbatim}

\subsection{Using BioUML analyses}
BioUML provides a set of analyses organized in groups.
The list of analyses available in the current server can be fetched with \Rfunction{biouml.analysis.list} function.
<<>>=
summary( biouml.analysis.list() )
@
\begin{verbatim}
 Import                          : 45   Add calculated column    :  1  
 Molecular networks              : 18   Add expression values    :  1  
 Differential algebraic equations: 17   Add reactants            :  1  
 Table manipulation              : 15   Algebraic steady state   :  1  
 Operations with genomic tracks  : 13   Annotate table           :  1  
 Statistics                      : 13   Annotate track with genes:  1  
 (Other)                         :105   (Other)                  :220  
\end{verbatim}

Each biouml analysis has a set of parameters, \Rfunction{biouml.analysis.parameters} returns
a data.frame with row names corresponding to parameter names and one column 'description'.
<<>>=
biouml.analysis.parameters("Filter table")
@
\begin{verbatim}
                                                                        description
inputPath                                                           Table to filter
filterExpression Expression in JavaScript like 'ColumnName1 > 5 && ColumnName2 < 0'
filteringMode                                                  Which rows to select
outputPath                                               Path to the filtered table
\end{verbatim}


The \Rfunction{biouml.analysis} launches analysis with given parameters.
<<>>=
biouml.analysis("Filter table", list(
  inputPath="data/Examples/Optimization/Data/Experiments/exp_data_1",
  filterExpression="time < 40",
  outputPath="data/Collaboration/Demo/tmp/exp_data_1 filtered"
))
@
\begin{verbatim}
38 %
INFO - Analysis 'Filter table' added to queue
INFO - Analysis 'Filter table' started
INFO - Filtering...
100 %
INFO - Writing result...
INFO - Analysis 'Filter table' finished (1.04 s)
[1] "RJOB155829081"
\end{verbatim}

%\subsection{Using BioUML workflows}
\subsection{Importing files to and from BioUML}
As described previously, data.frames can be fetched from and stored to BioUML repository using \Rfunction{biouml.get} and \Rfunction{biouml.put} functions.
In addition, data can be imported from files and exported to files in various formats.
The list of importers can be obtained with \Rfunction{biouml.importers} function.
<<>>=
head( biouml.importers() )
@
\begin{verbatim}
[1] "BioUML format(*.dml)"                
[2] "BioUML Simulation result"            
[3] "ZIP-archive (*.zip)"                 
[4] "Generic file"                        
[5] "Image file (*.png, *jpeg, *.gif etc)"
[6] "Text file (*.txt)"       
\end{verbatim}

As an example we will import fasta file to BioUML.
<<>>=
hiv.genome <- system.file("extdata","HIV-1.fa", package="rbiouml")
output.folder <- "data/Collaboration/Demo/tmp"
biouml.import(hiv.genome, output.folder,  importer="Fasta format (*.fasta)")
@
\begin{verbatim}
0 %
100 %
data/Collaboration/Demo/tmp/HIV-1[1] "data/Collaboration/Demo/tmp/HIV-1"
\end{verbatim}

<<>>=
biouml.ls(output.folder)
@
\begin{verbatim}
[1] "exp_data_1 filtered" "exp_data_1_sum" "HIV-1"
\end{verbatim}

Similarly, we can use \Rfunction{biouml.export*} functions to export data from BioUML repository.
<<>>=
head( biouml.exporters() )
@
\begin{verbatim}
head( biouml.exporters() )
[1] "JPEG file (*.jpg)"                 "Bitmap file(*.bmp)"               
[3] "Portable Network Graphics (*.png)" "BioUML format(*.dml)"             
[5] "BioUML state (*.xml)"              "Pair graph file(*.txt)"
\end{verbatim}
<<>>=
biouml.export("data/Collaboration/Demo/tmp/HIV-1",
  exporter="Fasta format (*.fasta)", target.file="HIV-1.fa")
file.exists("HIV-1.fa")
@
\begin{verbatim}
[1] TRUE
\end{verbatim}

\subsection{Disconnecting from BioUML server}
When you have finished with the BioUML server is recommended to do logout.
<<>>=
biouml.logout()
@

\end{document}
