%
% NOTE -- ONLY EDIT ESEA.Rnw!!!
% ESEA.tex file will get overwritten.
%
%\VignetteIndexEntry{ESEA Overview}
%\VignetteKeywords{pathway}
%\VignettePackage{ESEA}
%\VignetteDepends{igraph,XML,parmigene}

\documentclass[10pt]{article}

\usepackage{hyperref}
\usepackage[pdftex]{graphicx}
\SweaveOpts{keep.source=TRUE,eps=FALSE,pdf=TRUE,prefix=FALSE} 
\author{Junwei Han}

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

\newcommand{\xiaowuhao}{\fontsize{9pt}{\baselineskip}\selectfont}
\newcommand{\liuhao}{\fontsize{7.875pt}{\baselineskip}\selectfont}
\newcommand{\qihao}{\fontsize{5.25pt}{\baselineskip}\selectfont}

\newcommand\Rpackage[1]{{\textsf{#1}\index{#1 (package)}}}
\newcommand\RpackageNoindex[1]{{\textsf{#1}}}
\newcommand\Rclass[1]{{\textit{#1}\index{#1 (class)}}}
\newcommand\Rfunction[1]{{{\small\texttt{#1}}\index{#1 (function)}}}
\newcommand\Rmethod[1]{{\small\texttt{#1}}}
\newcommand\Rcommand[1]{{{\small\texttt{#1}}\index{#1 (function)}}}
\newcommand\Rfunarg[1]{{\small\texttt{#1}}}
\newcommand\Robject[1]{{\small\texttt{#1}}}
\bibliographystyle{plainnat}

\begin{document}
\setkeys{Gin}{width=1.0\textwidth}
\title{How To Use ESEA}
\maketitle
\tableofcontents

\section{Overview}
This vignette demonstrates how to easily use the \Rpackage{ESEA} package. The package can identify dysregulated pathways associated with a specific phenotype by investigating the changes of biological relationships of pathways in the context of gene expression data. Our system constructs a background set of edges by extracting pathway structure (e.g. interaction, regulation, modification, and binding etc.) from the seven public databases (KEGG; Reactome; Biocarta; NCI; SPIKE; HumanCyc; Panther) (see the section \ref{GetDatasection}). Our system also constructs the edge sets of pathways for each of the above databases (see the section \ref{GetDatasection}). The ESEA can quantify the change of correlation between genes for each edge based on gene expression data with cases and controls (see the section \ref{calEdgeCorScoresection}). The ESEA uses the weighted Kolmogorov-Smirnov statistic to calculate an edge enrichment score (EES), which reflects the degree to which a given pathway is associated the specific phenotype (see the section \ref{Getpathwaysection}).
<<echo=FALSE>>=
library(ESEA)
@ 


\section{Get the edge background set data and pathways edge sets data}\label{GetDatasection} 
The section introduces how to obtain the edge background set data and pathways edge sets data. The human pathways data are collected from the seven popular public databases (KEGG; Reactome; Biocarta; NCI; SPIKE; HumanCyc; Panther). Each pathway in the above databases is converted into an undirected graph. Each node in the graph represents a gene, and each edge represents a relationship such as interaction, regulation or modification etc. between genes. The edge set for each pathway can be extracted from the corresponding pathway graph. These pathway graphs are merged into a global gene interaction network. All the edges in the global network are used as the background set of edges.

For each pathway in the seven pathway database (KEGG; Biocarta; Reactome; NCI; SPIKE; HumanCyc; Panther), the edge set are extracted from the corresponding pathway graph. The edge sets of pathways are therefore created for each of the above databases.

The following commands can obtain the edge background set data and pathways edge sets data.

<<>>= 
#obtain the data for background set of edges.
edgesbackgrand<-GetEdgesBackgrandData()
edgesbackgrand[1:10,]

#obtain the edge sets of pathways.
pathwayEdge.db<-GetPathwayEdgeData()
@

\section{Discovering the dysregulated pathways based on edge set enrichment analysis}

The section introduces the Edge Set Enrichment Analysis (ESEA) method for identifying canonical biological pathways associated with a a specific phenotype. ESEA identifies dysregulated pathways by investigating the changes of biological relationships of pathways in the context of gene expression data. ESEA integrates pathway structure (e.g. interaction, regulation, modification, and binding etc.) and differential correlation among genes. The biological pathways were collected from the seven public databases (KEGG; Reactome; Biocarta; NCI; SPIKE; HumanCyc; Panther). A background set of edges is constructed by extracting pathway structure from each pathway in the seven databases. The information-theoretic measure, mutual information (MI), is applied to quantify the change of correlation between genes for each edge based on gene expression data with cases and controls (see the section \ref{calEdgeCorScoresection}). An edge list was formed by ranking the edges according to their changes of correlation. Finally, the weighted Kolmogorov-Smirnov statistic is used to prioritize the pathways by mapping the edges in the pathway to the edge list (see the section \ref{Getpathwaysection}).

\subsection{Calculate the differential correlation score for edges}\label{calEdgeCorScoresection}

For each edge, we estimated the mutual information (MI) between two genes in the expression data of all samples and control samples respectively. The difference of MI between all samples and control samples is used as the differential correlation score of the edge.

The function \Rfunction{calEdgeCorScore} can calculate the differential correlation scores of two genes in the edge. The following commands can calculate the differential correlation scores of edges in a given gene expression dataset.

<<>>= 

#get example data
dataset<-GetExampleData("dataset")
class.labels<-GetExampleData("class.labels")
controlcharactor<-GetExampleData("controlcharactor")

#get the data for background set of edges
edgesbackgrand<-GetEdgesBackgrandData()

#Calculate the differential correlation score for edges
EdgeCorScore<-calEdgeCorScore(dataset, class.labels, controlcharactor, edgesbackgrand)

#print the top ten results to screen
EdgeCorScore[1:10]

#Each element is the differential correlation score of an edge and whose name
# correspond to the edge in the background set of edges.
@

\subsection{Discovering the dysregulated pathways}\label{Getpathwaysection}

ESEA identify dysregulated pathways by investigating the changes of biological relationships of pathways in the context of gene
expression data. The weighted Kolmogorov-Smirnov statistic is used to evaluate each pathway and the permutation is used to calculate the statistical significance of pathways.

The function \Rfunction{ESEA.Main} can identify the dysregulated pathways. The following commands can identify the dysregulated pathways in a given gene expression dataset with default parameters. 

<<>>=
#get example data
dataset<-GetExampleData("dataset")
class.labels<-GetExampleData("class.labels")
controlcharactor<-GetExampleData("controlcharactor")

#get the data for background set of edges
edgesbackgrand<-GetEdgesBackgrandData()

#get the edge sets of pathways
pathwayEdge.db<-GetPathwayEdgeData()

#calculate the differential correlation score for edges
EdgeCorScore<-calEdgeCorScore(dataset, class.labels, controlcharactor, edgesbackgrand)

#identify dysregulated pathways by using the function ESEA.Main
Results<-ESEA.Main(
EdgeCorScore,
pathwayEdge.db,
weighted.score.type = 1, 
pathway = "kegg", 
gs.size.threshold.min = 15, 
gs.size.threshold.max = 1000,
reshuffling.type = "edge.labels",
nperm =10, 
p.val.threshold=-1,
FDR.threshold = 0.05, 
topgs =1
)

#print the summary results of pathways to screen
Results[[1]][[1]][1:5,]

#print the detail results of pathways to screen
Results[[2]][[1]][1:5,]

#write the summary results of pathways to tab delimited file.
write.table(Results[[1]][[1]], file = "kegg-SUMMARY RESULTS Gain-of-correlation.txt",
 quote=F, row.names=F, sep = "\t")
write.table(Results[[1]][[2]], file = "kegg-SUMMARY RESULTS Loss-of-correlation.txt",
 quote=F, row.names=F, sep = "\t")

#write the detail results of genes for each pathway with FDR.threshold< 0.05 to tab delimited file.
for(i in 1:length(Results[[2]])){
PathwayList<-Results[[2]][[i]]
filename <- paste(names(Results[[2]][i]),".txt", sep="", collapse="")
write.table(PathwayList, file = filename, quote=F, row.names=F, sep = "\t")
}
@ 

\section{Plot running result diagram}

\subsection{Plot global edge correlation profile}

The function \Rfunction{PlotGlobEdgeCorProfile} can plot global edge correlation profile for differential correlation scores of edges.

<<>>=
#get example data
dataset<-GetExampleData("dataset")
class.labels<-GetExampleData("class.labels")
controlcharactor<-GetExampleData("controlcharactor")

#get the data for background set of edges
edgesbackgrand<-GetEdgesBackgrandData()

#calculate the differential correlation score for edges
EdgeCorScore<-calEdgeCorScore(dataset, class.labels, controlcharactor, edgesbackgrand)

@ 
<<GlobEdgeCorProfile, fig=TRUE, include=FALSE, prefix=FALSE>>=
#plot global edge correlation profile
PlotGlobEdgeCorProfile(EdgeCorScore)
@

Figure \ref{GlobEdgeCorProfile} shows the global edge correlation profile for differential correlation scores of edges.

\begin{figure}[htbp]
\begin{center}
\includegraphics[width=1.0\textwidth]{GlobEdgeCorProfile}
\caption{The visualization of global edge correlation profile for differential correlation scores of edges}\label{GlobEdgeCorProfile}
\end{center}
\end{figure}
@
\subsection{Plot running Edge enrichment score}

The function \Rfunction{PlotRunEnrichment} can plot running edge enrichment score for the pathway result.

<<>>=
#get example data
dataset<-GetExampleData("dataset")
class.labels<-GetExampleData("class.labels")
controlcharactor<-GetExampleData("controlcharactor")

#get the data for background set of edges
edgesbackgrand<-GetEdgesBackgrandData()

#get the edge sets of pathways
pathwayEdge.db<-GetPathwayEdgeData()

#calculate the differential correlation score for edges
EdgeCorScore<-calEdgeCorScore(dataset, class.labels, controlcharactor,edgesbackgrand)

#identify dysregulated pathways by using the function ESEA.Main
#Results<-ESEA.Main(EdgeCorScore,pathwayEdge.db)
Results<-GetExampleData("PathwayResult")

#obtain the detail results of genes for a significant pathway
PathwayResult<-Results[[2]][1]

@ 
<<RunEdgeCorScore, fig=TRUE, include=FALSE, prefix=FALSE>>=
#Plot running edge enrichment score for the pathway result
PlotRunEnrichment(EdgeCorScore,PathwayResult,weighted.score.type = 1)
@

Figure \ref{RunEdgeCorScore} shows the running edge enrichment score for the pathway result

\begin{figure}[htbp]
\begin{center}
\includegraphics[width=1.0\textwidth]{RunEdgeCorScore}
\caption{The visualization of the running edge enrichment score for the pathway result}\label{RunEdgeCorScore}
\end{center}
\end{figure}
@

\subsection{Plot the pathway-result network diagram}

The function \Rfunction{PlotPathwayGraph} can plot the pathway-result network diagram, and the edges which contribute to the pathway enrichment score are marked with red.

<<>>=
#get example data
dataset<-GetExampleData("dataset")
class.labels<-GetExampleData("class.labels")
controlcharactor<-GetExampleData("controlcharactor")

#get the data for background set of edges
edgesbackgrand<-GetEdgesBackgrandData()

#get the edge sets of pathways
pathwayEdge.db<-GetPathwayEdgeData()

#calculate the differential correlation score for edges
EdgeCorScore<-calEdgeCorScore(dataset, class.labels, controlcharactor,edgesbackgrand)

#identify dysregulated pathways by using the function ESEA.Main
#Results<-ESEA.Main(EdgeCorScore,pathwayEdge.db)
Results<-GetExampleData("PathwayResult")

#obtain the detail results of genes for a significant pathway
PathwayNetwork<-Results[[2]][[1]]

@ 
<<PathwayNetwork, fig=TRUE, include=FALSE, prefix=FALSE>>=
#Plot the pathway-result network diagram, the edges which contribute to the ES are labeled with red.
PlotPathwayGraph(PathwayNetwork,layout=layout.random)
@

Figure \ref{PathwayNetwork} shows the pathway-result network diagram, the edges which contribute to the ES are labeled with red

\begin{figure}[htbp]
\begin{center}
\includegraphics[width=1.0\textwidth]{PathwayNetwork}
\caption{The visualization of the pathway-result network diagram, the edges which contribute to the ES are labeled with red.}\label{PathwayNetwork}
\end{center}
\end{figure}
@

\subsection{Save a pathway-result network to a file which can be input to the Cytoscape software}

The function \Rfunction{SavePathway2File} can save a pathway-result network to a file which can be input to the Cytoscape software.

<<>>=
#get example data
dataset<-GetExampleData("dataset")
class.labels<-GetExampleData("class.labels")
controlcharactor<-GetExampleData("controlcharactor")

#get the data for background set of edges
edgesbackgrand<-GetEdgesBackgrandData()

#get the edge sets of pathways
pathwayEdge.db<-GetPathwayEdgeData()

#calculate the differential correlation score for edges
EdgeCorScore<-calEdgeCorScore(dataset, class.labels, controlcharactor,edgesbackgrand)

#identify dysregulated pathways by using the function ESEA.Main
#Results<-ESEA.Main(EdgeCorScore,pathwayEdge.db)
Results<-GetExampleData("PathwayResult")

#obtain the detail results of genes for a significant pathway
PathwayNetwork<-Results[[2]][[1]]

#save the pathway-result network to a file which can be input to the Cytoscape software. 
SavePathway2File(PathwayNetwork,layout=layout.circle,file="Graph")
@ 


\newpage
\section{Session Info}
The script runs within the following session:
<<sessionInfo, echo=FALSE, results=verbatim>>=
sessionInfo()
@

\begin{thebibliography}{}

\bibitem[Subramanian {\it et~al}., 2005]{Subramanian2009} Subramanian, A., Tamayo, P., Mootha, V.K., Mukherjee, S., Ebert, B.L., Gillette, M.A., Paulovich, A., Pomeroy, S.L., Golub, T.R., Lander, E.S. et al. (2005) Gene set enrichment analysis: a knowledgebased approach for interpreting genome-wide expression profiles. Proc Natl Acad Sci U S A, 102, 15545-15550.

\bibitem[Mani {\it et~al}., 2008]{Mani2008} Mani, K.M., Lefebvre, C., Wang, K., Lim, W.K., Basso, K., Dalla-Favera, R. and Califano, A. (2008) A systems biology approach to prediction of oncogenes and molecular perturbation targets in B-cell lymphomas. Molecular systems biology, 4, 169.

\bibitem[de la Fuente {\it et~al}., 2008]{de la Fuente2008} de la Fuente, A. (2010) From 'differential expression' to 'differential networking' - identification of dysfunctional regulatory networks in diseases. Trends Genet, 26, 326-333.

\end{thebibliography}

\end{document}


