%\VignetteIndexEntry{Main vignette: RedeR Overview}
%\VignetteKeywords{Graph}
%\VignettePackage{RedeR}

\documentclass[11pt]{article}
\usepackage{Sweave,fullpage}
\usepackage{hyperref}
\bibliographystyle{unsrt}
\usepackage{subfig}

\title{RedeR: bridging the gap between hierarchical network representation and functional analysis.}
\author{
Mauro A. A. Castro, Xin Wang, Florian Markowetz 
\thanks{Cancer Research UK - Cambridge Research Institute, Robinson Way Cambridge, CB2 0RE, UK.} \\
\texttt{\small http://www.markowetzlab.org/software/networks.html} \\
\texttt{\small florian.markowetz@cancer.org.uk} \\
}

\begin{document}

\maketitle

\tableofcontents

%<<Ropts, echo=FALSE, results=hide>>=
%options(width=100)
%@ 

\newpage 

\section{Overview}

\emph{RedeR} is an R-based package combined with a Java application for dynamic network visualization and manipulation. It
implements a callback engine by using a low-level R-to-Java interface to build and run common plugins. In this sense, \emph{RedeR} takes advantage of 
\emph{\textbf{R}} to run robust statistics, while the R-to-Java interface bridge the gap between network analysis and visualization: for \textbf{R Developers}, it allows 
the development of Java plug-ins exclusively using R codes; for \textbf{Java Users}, it runs R methods implemented in a stand-alone application,  
and for \textbf{R Users} \emph{RedeR} interactively displays R graphs using a robust Java graphic engine embedded in \emph{R}.  \\

\emph{RedeR} use different strategies to link R to Java: 

\begin{itemize}
    \item Data interface: implements the callback engine to make calls from R via xml-rpc protocol. It sets \emph{R} as client and \emph{RedeR} as server. 
    \item Graphic interface: implements the callback engine to make calls from Java via dynamic libraries. It wraps R graphics into RedeR classes. 
\end{itemize}

The design of the software is depicted from Figure 1. One unique feature of this concept is how R methods can be wrapped and exported. For example, in a few lines of code
\emph{RedeR} sends R methods to the Java app using the \emph{submitPlugin} function, which gives rise to a new Java plugin. Also, complex graphs with many attributes 
can be transferred from-and-to \emph{R} using \emph{addGraph} and \emph{getGraph} functions. \\


%%%%%%
%Fig1%
%%%%%%
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=1.0\textwidth]{fig1.pdf}
\end{center}
\label{fig1}
\caption{Schematic representation of RedeR calls. In the low-level interface, packages like XMLRPC\cite{XMLRPC} and rJava\cite{rJava} are used to link R to Java.}
\end{figure}

\section{Quick start}

\subsection{Main callback methods}

The first step is to build the server port, which will be required in all remote procedure calls. By default the constructor \emph{RedPort} should set all details:

\begin{small}
<<label=Main call, eval=TRUE>>=
   library (RedeR)
   rdp <- RedPort () 
@ 
\end{small}

Next, invoke RedeR using the method \emph{calld}:

\begin{small}
<<label=Main call, eval=FALSE>>=
   calld(rdp)
@ 
\end{small}

Within an active interface, then the method 'addGraph' can easily send R graphs to the application. For example, the following chunk adds an \emph{igraph}\cite{igraph} object:
\begin{small}
<<label= Add graph, eval= TRUE>>=
   g1 <- graph.lattice(c(5,5,5))
   addGraph( rdp, g1, layout.kamada.kawai(g1) )
@
\end{small}

%%%%%%
%Fig2%
%%%%%%
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=0.35\textwidth]{fig2.pdf}
\end{center}
\label{fig2}
\caption{A toy example added to \emph{RedeR} by the \emph{addGraph} function.}
\end{figure}


Conversely, RedeR graphs can be transferred to R and wrapped in \emph{igraph} objects:
\begin{small}
<<label= Get graph, eval= TRUE>>=
   g2 <- getGraph(rdp)
   resetd(rdp)
@
\end{small}
The interface accepts additional graph attributes, as for example edge direction, edge width, edge weight, node shape, node size, node color etc. In \emph{igraph} objects, vertex and edge attributes can be assigned as arbitrary R objects. In order to pass these extensible features to \emph{RedeR} the attributes must be provided in a valid syntax.
\footnote{See \emph{getGraph} and \emph{addGraph} specification for additional details.}


Another strategy is to wrap graphs into containers and then send it to the Java app. Next, the subgraphs g3 and g4 are assigned to different nested structures (Fig.3).
\begin{small}
<<label= Build subgraphs, eval= TRUE>>=
   g3 <- barabasi.game(10)
   g4 <- barabasi.game(10)
   V(g3)$name<-paste("sn",1:10,sep="")
   V(g4)$name<-paste("sm",1:10,sep="")
   addGraph(rdp, g3, isNest =TRUE, gcoord=c(25,25), gscale=50)
   addGraph(rdp, g4, isNest =TRUE, gcoord=c(75,75), gscale=50 )
@
\end{small}

%%%%%%
%Fig3%
%%%%%%
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=0.8\textwidth]{fig3.pdf}
\end{center}
\label{fig3}
\caption{Graphs nested in \emph{RedeR} by the command \emph{addGraph}.}
\end{figure}


In this case, the subgraphs can be handled apart from each other. For example, the following chunk selects all nodes assigned to the container "N0" and then gets back the subgraph (the selection step can also be done interactively!).

\begin{small}
<<label= Get subgraph, eval= TRUE>>=
   selectNodes(rdp,"N0")
   g5 <- getGraph(rdp, status= "selected")
   resetd(rdp)
@
\end{small}

\emph{As a suggestion, try some RedeR features in the Java side (e.g. open samples s2 or s3 in the main panel and enjoy the dynamic layout options!).}


\newpage


\subsection{Interactive work}

The next chunk generates a scale-free graph according to the Barabasi-Albert model\cite{igraph} and sends the graph to RedeR without any layout information.
\begin{small}
<<label= Build scale-free graph and send to the app, eval=TRUE>>=
   g6 <- barabasi.game(500)
   addGraph(rdp, g6, zoom=20)
@
\end{small}

Then using the "relax" options available in the app you can tune the graph layout as presented in Figure 4.
\begin{small}
<<label= Start relax , eval=TRUE>>=
   relax(rdp,p2=400,p5=30,ps=T)
@
\end{small}

%%%%%%
%Fig4%
%%%%%%
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=0.7\textwidth]{fig4.pdf}
\end{center}
\label{fig4}
\caption{Scale-free graph according to the Barabasi-Albert model\cite{igraph}.}
\end{figure}

In Figure 5a the same graph is used to exemplify the community structure mapped by the edge-betweenness function available in RedeR. In Figure 5b these communities are nested to containers, which are objects of the same class of the nodes but with additional behaviors: it can be hidden and anchored to the main panel (Fig.5c). You can build these containers either using \emph{R} or \emph{Java} functions (see options available in the \emph{clustering} main menu and in the shortcuts of nested objects, i.e., right-click a container!).

%%%%%%
%Fig5%
%%%%%%
\begin{figure}[htbp]
  \centering
  \subfloat[Communities]{\label{fig5a: Communities}\includegraphics[width=.5\textwidth]{fig5a.pdf}}              
  \subfloat[Graphs into containers]{\label{fig5b:Graphs into containers}\includegraphics[width=.5\textwidth]{fig5b.pdf}} \\
   \subfloat[Subnetworks]{\label{fig5c:Subnetworks}\includegraphics[width=.9\textwidth]{fig5c.pdf}}
  \caption{Community structure: (a) subgraphs detected based on edge betweenness; (b) nested communities into containers; (c) subnetworks in hidden containers.}
\end{figure} 


For the next example you will need to reproduce in \emph{RedeR} app the graph from Figure 5b (or any graph with containers), then select one of the communities and run the chunk below:  a simple degree distribution should be plotted in the R side (Fig.6). This is the first step to illustrate how to build an interactive plugin.
\begin{small}
<<label= Map clic communities, eval= TRUE>>=
   g <- getGraph(rdp, status= "selected")
   if(vcount(g)>0)plot(degree.distribution(g), xlab = "k", ylab = "P(k)", pch=19)
   resetd(rdp)
@
\end{small}


\newpage 


\section{Workflow samples}

This section provides a sequence of steps that illustrate how users might integrate its own pre-processed data with a given network in order to visualize subgraphs and nested networks. The full description soon will be available in a new communication!

\subsection{Subgraphs}

\begin{itemize}

\begin{scriptsize}

\item 1 - start the app (i.e. 'calld' method).

\item 2 - get a dataframe and an interactome:
<<label= Workflow 1: get a dataframe and an interactome, eval=TRUE>>=
data(ER.limma)
data(hs.inter)
dt <- ER.limma
gi <- hs.inter
@

\item 3 - extract a subgraph and set attributes to RedeR (i.e. logFC from t3-t0 contrast):
<<label=Workflow 1: extract a subgraph and set attributes to RedeR, eval=TRUE>>=
gt3  <- subg(g=gi, dat=dt[dt$degenes.t3!=0,], refcol=1)
gt3  <- att.setv(g=gt3, from="Symbol", to="nodeAlias")
gt3  <- att.setv(g=gt3, from="logFC.t3...t0", to="nodeColor", breaks=seq(-2,2,0.4), pal=2)
@
\emph{ps. some genes will not be found in the interactome!}

\item 4 - extract another subgraph and set attributes to RedeR  (i.e. logFC from t6-t0 contrast):
<<label=Workflow 1: extract another subgraph and set attributes to RedeR, eval=TRUE>>=
gt6  <- subg(g=gi, dat=dt[dt$degenes.t6!=0,], refcol=1)
gt6  <- att.setv(g=gt6, from="Symbol", to="nodeAlias")
gt6  <- att.setv(g=gt6, from="logFC.t6...t0", to="nodeColor", breaks=seq(-2,2,0.4), pal=2)
@

\item 5 - extract another subgraph and set attributes to RedeR  (i.e. logFC from t12-t0 contrast):
<<label=Workflow 1: extract another subgraph and set attributes to RedeR, eval=TRUE>>=
gt12 <- subg(g=gi, dat=dt[dt$degenes.t12!=0,], refcol=1)
gt12 <- att.setv(g=gt12, from="Symbol", to="nodeAlias")
gt12 <- att.setv(g=gt12, from="logFC.t12...t0", to="nodeColor", breaks=seq(-2,2,0.4), pal=2)
@

\item 6 - add subgraphs to the app:
<<label=Workflow 1: add subgraphs to the app, eval=TRUE>>=
n0 <- addGraph(rdp, gt3, gcoord=c(10,25), gscale=20, isNest=TRUE, theme='tm1', zoom=30)
n1 <- addGraph(rdp, gt6, gcoord=c(20,70), gscale=50, isNest=TRUE, theme='tm1', zoom=30)
n2 <- addGraph(rdp, gt12, gcoord=c(70,55), gscale=80, isNest=TRUE, theme='tm1', zoom=30)
@

\item 7 - nest subgraphs (i.e. overlap time-series):
<<label=Workflow 1: nest subgraphs, eval=TRUE>>=
nestNodes(rdp, nodes=V(gt3)$name, parent=n1, theme='tm2')
nestNodes(rdp, nodes=V(gt6)$name, parent=n2, theme='tm2')
@

\item 8 - assign edges to containers
<<label=Workflow 1: assign edges to containers, eval=TRUE>>=
mergeOutEdges(rdp)
@

\item 9 - relax the network
<<label=Workflow 1: relax the network, eval=TRUE>>=
relax(rdp,50,400)
@

\item 10 - add a color legend (other types are available):
\footnote{Legends are set only via command line in the current version.}

<<label=Workflow 1: add a color legend (other types are available), eval=TRUE>>=
scl <- gt3$legNodeColor$scale
leg <- gt3$legNodeColor$legend 
addLegend.color(rdp, colvec=scl, labvec=leg, title="node color (logFC)")
@

\newpage

\item 11 -  select a gene:
<<label=Workflow 1: select a gene, eval=TRUE>>=
selectNodes(rdp,"RET")
@

\item 12 - reset graph:
<<label=Workflow 1: reset graph, eval=TRUE>>=
resetd(rdp)
@

\end{scriptsize}

\end{itemize}


\subsection{Nested networks and clustering}


\begin{itemize}

\begin{scriptsize}

\item 1 - get a dataframe and an igraph object:
<<label=get a dataframe and an igraph object, eval=TRUE>>=
data(ER.deg)
dt <- ER.deg$dat
sg <- ER.deg$ceg
@

\item 2 - map the dataframe to the graph:
<<label=Workflow 2: map the dataframe to the graph, eval=TRUE>>=
sg <- att.mapv(sg, dat=dt, refcol=1)
@

\item 3 - set attributes to RedeR (i.e. gene symbols and two available numeric data):
<<label=Workflow 2: set attributes to RedeR , eval=TRUE>>=
sg <- att.setv(sg, from="Symbol", to="nodeAlias")
sg <- att.setv(sg, from="logFC.t3...t0", to="nodeColor", breaks=seq(-1,1,0.2), pal=2)	
sg <- att.setv(sg, from="ERbdist", to="nodeSize", nquant=10, isrev=TRUE, xlim=c(5,40,1))
@

\item 4 - add graph to the app:
<<label=Workflow 2: add graph to the app, eval=TRUE>>=
addGraph(rdp,sg)
@

\item 5 - compute a hierarchical clustering using standard R functions:
<<label=Workflow 2: compute a hierarchical clustering using standard R functions, eval=TRUE>>=
hc <- hclust(dist(get.adjacency(sg, attr="weight")))
@

\item 6 - map the hclust object onto the network (pvclust objects are also compatible!):
<<label=Workflow 2: map the hclust object onto the network, eval=TRUE>>=
nesthc(rdp,hc, cutlevel=3, nmemb=5, cex=0.3, labels=V(sg)$nodeAlias)
@

\emph{...at this point nested objects from the network should also be mapped to a dendrogram!  different levels of the nested structure can be set by the nesthc method. Additionally, significant clusters can be computed by the pvclust package, which is already compatible with RedeR interface.}

\item 7 - assign edges to containers:
<<label=Workflow 2: assign edges to containers, eval=TRUE>>=
mergeOutEdges(rdp)
@

\item 8 - relax the network:
<<label=Workflow 2: relax the network, eval=TRUE>>=
relax(rdp)
@

\item 9 - add color and size legends: 
\footnote{Legends are set only via command line in the current version.}

<<label=Workflow 2: add color legend, eval=TRUE>>=
scl <- sg$legNodeColor$scale
leg <- sg$legNodeColor$legend
addLegend.color(rdp, colvec=scl, labvec=leg, title="diff. gene expression (logFC)")
@

<<label=Workflow 2: add node size legend, eval=TRUE>>=
scl <- sg$legNodeSize$scale
leg <- sg$legNodeSize$legend
addLegend.size(rdp, sizevec=scl, labvec=leg, title="bd site distance (kb)")
@

\item 10 - reset graph:
<<label=Workflow 2: reset graph, eval=TRUE>>=
resetd(rdp)
@

\end{scriptsize}

\end{itemize}

\newpage

\section{Plugin builder}

RedeR plug-ins have two main sections: methods and add-ons. The 'methods' section can be regarded as the plug-in trigger. 
When installed in the Java app, this trigger is used to start a given analysis by unfolding the R expressions wrapped in the methods. 
Add-ons use the same strategy, but remains hidden in the app -- and it is optional. Formal functions can be passed to add-ons as additional arguments. 
Prior to the main call, all functions are automatically loaded in R, making the source code available to the subsequent analysis.\

\subsubsection*{A simple example} 

\begin{itemize}

\item Wrap methods in functions

Here, the degree distribution is used in the same way as illustrated in the previous section but -- prior to execute the analysis -- the plugin requires two commands: \emph{RedPort} to set the interface, and \emph{dynwin} to wrap R graphics in RedeR Java classes. Additionally, the "JavaGD" package should be available in R.
\footnote{Due to build/check errors, this package was not available at the occasion of Bioconductor release; therefore, it had to be removed from RedeR dependencies. It can be installed by command line, as indicate in \emph{Installation} section.}

\begin{small}
<<label= Set a simple method, eval= TRUE>>=
      mt1 <- function() 
      {
  	rdp <- RedPort('MyPort')
  	dynwin(rdp)
   	g <- getGraph(rdp, status= "selected")
	if(vcount(g)>0)plot(degree.distribution(g), xlab = "k", ylab = "P(k)", pch=19)
       }
@
\end{small}

\item Initiate plugin skeleton:

Now the method \emph{mt1} is added to the \emph{PluginBuilder}, and is ready to be sent to the application.
\begin{small}
<<label= Build a plugin skeleton, eval= TRUE>>=
    plugin <- PluginBuilder(title="MyPlugin", allMethods=list(mt1=mt1))
@                             
\end{small}

\item Submit new plugins to RedeR:

The submission is straightforward: in the Java side, the plugin will be displayed in the main menu provided that the interface is properly set to find \emph{R}.
\begin{small}
<<label= Submit plugin to the app (p.s. JavaGD will be required: see footnotes!), eval= TRUE>>=
  submitPlugin(rdp, plugin)
  updatePlugins(rdp)
  exitd(rdp)
@
\end{small}

\end{itemize}




%%%%%%
%Fig6%
%%%%%%
\begin{figure}[htbp]
\begin{center}
\includegraphics[width=0.6\textwidth]{fig6.pdf}
\end{center}
\label{fig6}
\caption{RedeR plugins: a simple example to illustrate the concept (degree distribution of selected subgraphs). One subgraph from Figure 5b was interactively selected in \emph{RedeR} and then plotted either in the R side or in the Java side of the interface using the plugin described above.}
\end{figure}


\newpage 

\section{Installation}

\subsubsection*{Release version}
The RedeR package is freely available from Bioconductor at \url{http://bioconductor.org/packages/release/bioc/html/RedeR.html}.

\subsubsection*{Developing version}
The developing version is available at \url{http://bioconductor.org/packages/devel/bioc/html/RedeR.html}.  In order to install RedeR devel please download the \emph{Package Source} (the .tar.gz file!!) and install all dependences in R:

\begin{scriptsize}
<<label= Devel version, eval= FALSE>>=
install.packages(c("RCurl", "XML", "rJava", "igraph", "JavaGD"), repos = "http://cran.r-project.org")
install.packages("XMLRPC", repos = "http://www.omegahat.org/R", type = "source")
install.packages('/devel.tar.gz', type='source')  ## i.e. the path to the downloaded .tar.gz file!
@
\end{scriptsize}

\subsubsection*{The JAVA application}
The RedeR jar file is already included in the R package and, as usual, to run Java applications your system should have a copy of the JRE (Java Runtime Environment, version>= 5). The RedeR software can be used as a stand-alone application, or even embedded in other softwares, but in order to use plugins the interface must be set properly in the Java side to find R (e.g. path to R home). This should be a simple task, but if your R environment deviates a lot from the default installation then it might be necessary to add some path manually. If you find any difficulty, please contact us.


\newpage

\section{Session information}

\begin{scriptsize}
<<label=Session information, eval=TRUE,echo=FALSE>>=
print(sessionInfo(), locale=FALSE)
@
\end{scriptsize}


\newpage 

\bibliography{bib}

\end{document}