%\VignetteIndexEntry{GRAPH Interaction from pathway Topological Environment}
%\VignetteDepends{graph}
%\VignetteDepends{graphite}
%\VignetteDepends{SPIA}
%\VignetteDepends{hgu133plus2.db}
%\VignetteDepends{topologyGSA}

\documentclass{article}
\usepackage[utf8]{inputenc}

<<style, eval=TRUE, echo=FALSE, results=tex>>=
BiocStyle::latex()
@

\title{GRAPH Interaction from pathway Topological Environment}
\author{
  Gabriele Sales (gabriele.sales@unipd.it) \\
  Enrica Calura (enrica.calura@gmail.com) \\
  Chiara Romualdi (chiara.romualdi@unipd.it)
}

\begin{document}
\SweaveOpts{concordance=TRUE}

\maketitle

\tableofcontents

<<startup, echo=FALSE, results=hide>>=
library(graph)
library(graphite)
@

\section{Introduction}

\Biocpkg{graphite} (GRAPH Interaction from pathway Topological Environment) is an R package built to i) provide networks derived from eight pathway public databases, ii) allowing the conversion of nodes identifiers; and finally, iv) to easily run topological pathway analyses directly on \Biocpkg{graphite} networks.

The pathway databases available in \Biocpkg{graphite} are:

KEGG \cite{KEGG}; Biocarta (www.biocarta.com); Reactome \cite{Reactome}; NCI/Nature Pathway Interaction Database \cite{NCI}; HumanCyc \cite{humancyc}; Panther \cite{panther}; smpdb (www.smpdb.ca) \cite{smpdb}; PharmGKB
(www.pharmgkb.org) \cite{pharmgkb}.
All the pathways provided are annotated in human and, since the version 1.14, pathways from other 13 species are available.

The topological pathway analyses directly available in the package are: \Biocpkg{SPIA} \cite{Tarca2009,Adi2009,Draghici2007}, \Biocpkg{clipper} \cite{Martini2013} and \Biocpkg{topologyGSA} \cite{Massa2010}.

Since version 1.24, \Biocpkg{graphite} pathways are composed by: i) only genes, where metabolites nodes have been removed and edges have been propagated through the metabolites; ii) only metabolites, where protein nodes have been removed and edges have been propagated through the proteins; iii) both genes and metabolites to support and foster metabolomic and transcriptomic data integration analyses.

\section{Pathway topology conversion to gene network}
In order to gather curated information about pathways, we have collected data from different public databases that have emerged as reference points for the systems biology community.
The KEGG database has been in development by Kanehisa Laboratories since 1995, and is now a prominent knowledge base for integration and interpretation of large-scale molecular data sets generated by genome sequencing and other high-throughput experimental technologies. KEGG is the only pathway database not in {\tt BioPax} format, as it stores the information using the KGML format. KEGG pathways (KGML format) provides maps for both signaling and metabolic pathways \cite{KEGG}.
Reactome, backed by the EBI, is one of the most complete repository; it is frequently updated and provides a semantically rich description of each pathway \cite{Reactome}.
BioCarta (www.biocarta.com) is a developer, supplier and distributor company of reagents and assays for biopharmaceutical and academic research. Through an "open source" approach, this community-fed forum constantly integrates emerging proteomic information from the scientific community. It also catalogs and summarizes important resources providing information for over 120,000 genes. BioCarta pathway data in {\tt BioPax} format are available through the NCI website. NCI (NCI/Nature Pathway Interaction Database \cite{NCI}) is a highly-structured, curated collection of information about known biomolecular interactions and key cellular processes assembled into signaling pathways. This was a collaborative project between the NCI and Nature Publishing Group (NPG).
Finally, Panther \cite{panther} is data are a comprehensive, curated database of pathways, protein families, trees, subfamilies and functions available at http://pantherdb.org backed by the University of Southern California.
HumanCyc is part of the BioCyc database collection of pathways \cite{humancyc}.
Since version 1.24, \Biocpkg{graphite} cointains also SMPDB \cite{smpdb} and PharmGKB \cite{pharmgkb}, important resources for metabolomic data analyses.

\subsection{Pathway definition}
\Biocpkg{graphite} pathways are derived by conversion of {\tt KGML} and {\tt BioPax} data formats.
KEGG database provides a separate {\tt xml} file, one for each pathway. Thus, a pathway is defined by all the reactions defined within each file. For the other databases, we define a pathway for each element of type {\tt pathway} in the {\tt BioPax} document.

\subsection{Nodes with multiple elements}
Within a pathway, a node can correspond to multiple gene products. These nodes with multiple elements can be divided into protein complexes (proteins linked by protein-protein interactions) and the groups containing alternative members (genes generally with similar biochemical functions). When considering signal propagation these groups should be considered differently; the first (hereafter group AND) should be expanded into a clique (all proteins connected to the others), while the second (hereafter group OR) should be expanded without connection among the contained elements.

In the KGML format there are two ways of defining nodes with multiple elements: protein complexes (group AND defined by entry {\tt type="group"}) and group with alternative members (group OR defined by entry {\tt type="gene"}).
In the BioPax format only one type of group is allowed: protein complexes (group AND) with type {\tt complex}. However, it often happens that {\tt protein} tag contains multiple {\tt xref} pointing to alternative elements of the process (group OR).

\subsection{Metabolite and protein-mediated interactions}
Metabolites mediated interactions are interactions for which a metabolite acts as a bridge between two proteins. Since metabolites are not measured during gene expression analysis (using microarray or RNA-seq), their removal from the original network is useful. However, the trivial elimination of the metabolites, without signal propagation, will strongly bias the topology, interrupting the signals that pass through them. If element $A$ is linked to metabolite $c$ and metabolite $c$ is linked to element $B$, thus elements $A$ should be linked to elements $B$.

Within the KGML format, there are two different ways of describing a metabolite mediated interaction: i) direct interaction {\tt type="PPrel"} ($A$ interacts whit $B$ through metabolite $c$) and ii) indirect one {\tt type="PCrel"} ($A$ interacts whit metabolite $c$ and $c$ interacts whit $B$).

Since proper signal propagation is crucial for topological gene set analysis we decided to include additional rules for the propagation reconstructing a connection between two genes connected through a series of metabolites.
Not all metabolites are considered for the propagation because some of them, such as Hydrogen, H2O, ATP, ADP etc., are highly frequent in map descriptions and the signal propagation through them would lead to degenerate too long chains of metabolites. The metabolites not considered for propagation are not characteristic of a specific reaction but secondary substrates/products widely shared among different processes.

Since version 1.24, \Biocpkg{graphite} can be used also for metabolomics pathway analyses. We applied the same procedure descibed above to provide network with metabolites only propagating the signal through proteins.

Finally, \Biocpkg{graphite} includes pathways containing both proteins and metabolites (without edges propagation) allowing also integrated pathway analyses of gene expression and metabolomic data.

\subsection{Edge attributes}
\Biocpkg{graphite} allows the user to see the single/multiple relation types that characterize an edge.
The type of edges have been preserved to remain  as close as possible to the original annotations. Some new types have been introduced due to the needs of the topological conversion. For instance a {\it Process(indirect)} is introduced when the edge is generated propagating the signal from a gene to another gene passing through metabolites, or from a metabolite to another metabolite passing through proteins.

\subsection{Loading pathways}
Human pathways are natively distribuited with the package. Since the version 1.14.0, non-human pathway data are also available and can be dowloaded automatically using the \Rfunction{pathways} function.

\Rfunction{pathways} requires the name of the specie of interest and the name of the pathway database name as follows:

<<base1>>=
humanReactome <- pathways("hsapiens", "reactome")
names(humanReactome)[1:10]
p <- humanReactome[["ABC-family proteins mediated transport"]]
p
@

A pathway database is a list of pathways. We can access a pathway through its name, as above, or through its position in the list, as follow:

<<base2>>=
p <- humanReactome[[21]]
pathwayTitle(p)
@

In the pathway, nodes represent genes/proteins:
<<base3>>=
head(nodes(p))
@

Edges can be characterized by multiple functional relationships:

<<base4>>=
head(edges(p))
@

By default, the function \Rfunction{edges} and \Rfunction{nodes} provide the edges or the nodes of the pathway containing only proteins with signals propagated through metabolites. Since version 1.24, using the option {\it which} we can access the pathway with proteins and metabolites ({\it which = "mixed"}) or the pathway with only metabolites with edges propagated through proteins ({\it which} = "metabolites").
<<base5>>=
head(nodes(p), which = "mixed")
head(edges(p), which = "mixed")
@

These same steps can be used to access the KEGG, Biocarta, Panther, HumanCyc, NCI, SMPDB and PharmGKB databases for Homo sapiens pathways (through the \Robject{kegg}, \Robject{biocarta}, \Robject{panther}, \Robject{humancyc} and \Robject{nci}  \Robject{smpdb}, \Robject{pharmgkb} lists, respectively), but not all the databases are present for all the species.
To know the pathway data available the user can use the \Rfunction{pathwayDatabases}.

<<base6>>=
pathwayDatabases()
@

\section{Pathway graph}

The function \Rfunction{pathwayGraph} builds a \Rclass{graphNEL} object from a pathway \Robject{p}:
<<graph1>>=
g <- pathwayGraph(p)
g
@

<<graph2>>=
edgeData(g)[1]
@

Similarly to the \Rfunction{edges} and \Rfunction{nodes}, by default, the function \Rfunction{pathwayGraph} provide the pathway with only proteins and edges propagated through metabolites. Since version 1.24, using the option {\it which} we can access the pathway with proteins and metabolites ({\it which = "mixed"}) or the pathway with only metabolites with edges propagated through proteins ({\it which} = "metabolites").

<<graph3>>=
g <- pathwayGraph(p, which = "mixed")
g
@

<<graph4>>=
edgeData(g)[1]
@

\section{Identifiers}
Gene annotations databases are widely used as public repositories of biological information. Our current knowledge on biological elements is spread out over a number of databases (such as: Entrez Gene , RefSeq, backed by the NCBI http://www.ncbi.nlm.nih.gov/, UniProt,  ENSEMBL backed by the EBI http://www.ebi.ac.uk/ to name just a few), specialised on a subset of specific biological entities (for instance, UniProt focuses on proteins while Entrez Gene focuses on genes).
Key identifiers (IDs) in the internal structure of each database uniquely represent biological entities, thus biological entities can be identified by homogeneous IDs according to the selected database they refer to.
Due to their different origins and specificity, switching from an ID to another is possible but not trivial: there could be either no correspondence among them or many-to-many relations.
For detailed information about IDs, their structures and differences please consult those resources.

The function \Rfunction{converterIdentifiers} allows the user to convert the pathway IDs into different types, to fit the user needs. This mapping process, however, may lead to the loss of some nodes (not all identifiers may be recognized) and has an impact on the topology of the network (one ID may correspond to multiple IDs in another annotation or vice versa). We based the function of ID conversion through the species-specific Bioconductor \Biocpkg{AnnotationDbi}, such as \Biocpkg{org.Hs.eg.db}. Since the version 1.14, all the conversion supported in the annotation packages can be used. \Rfunction{converterIdentifiers} needs a list of pathways or a single pathway and a string describing the type of the identifier as provided by an Annotation package (for example,‘"ENTREZID"’), while the values ‘"entrez"’, ‘"symbol"’ remains for backward compatibility.

<<ident1>>=
pSymbol <- convertIdentifiers(p, "SYMBOL")
pSymbol
head(nodes(pSymbol))
@

<<ident2>>=
reactomeSymbol <- convertIdentifiers(humanReactome[1:5], "SYMBOL")
@

Since the introduction of metabolites in \Biocpkg{graphite} pathways (version 1.24), also the metabolite ID conversion is possible.
The metabolite conversion is performed for the following identifiers:''PUBCHEM'', ''KEGGLYCAN'', ''KEGGDRUG'', ''KEGGCOMP'', ''CHEBI'', ''CAS''.

\clearpage
\section{Cytoscape Plot}

Several pathways have a huge number of nodes and edges, thus there is the need of an efficient system of visualization. To this end \Biocpkg{graphite} uses the \Biocpkg{Rcy3} package to export the network to Cytoscape 3, through the function \Rfunction{cytoscapePlot}. Cytoscape is a Java based software specifically built to manage biological network complexity and for this reason it is widely used by the biological community.
Since version 1.24, using the option {\it which} we can access the pathway with proteins and metabolites ({\it which = "mixed"}) or the pathway with only metabolites and edges propagated through proteins ({\it which} = "metabolites").

\begin{Schunk}
\begin{Sinput}
> cytoscapePlot(convertIdentifiers(reactome$`Unwinding of DNA`, "symbol"), which =  "mixed")
\end{Sinput}
\end{Schunk}
\begin{center}
  \includegraphics[width=10cm, height=9.12cm]{Cytoscape.png}
\end{center}

\section{Topological pathway analysis}
\Biocpkg{graphite} gives access to three types of topological pathway analyses. For more details on the results obtained by these analyses see the corresponding R packages. Following developper instructions, all the methods with the exception of \Biocpkg{clipper} are available only for pathways with proteins and with edges propagated through metabolites. \Biocpkg{clipper} is the only analysis that can be used to study metabolomics data.

Note that, since version 1.24, given the introduction of nodes with mixed types, all the ID in the pathway have been prefixed with the type of identifier (e.g. ENTREZID:7157 or SYMBOL:TP53). Thus, also the gene expression or metabolite data, in order to match with the pathway nodes, should be in the same format (e.g. ENTREZID:7157 or SYMBOL:TP53).

\subsection{SPIA}

The analysis with \Biocpkg{SPIA} requires the conversion of gene-gene networks in a suitable format. This conversion is performed by the function \Rfunction{prepareSPIA} that must be executed before the analysis command \Rfunction{runSPIA}. The \Biocpkg{SPIA} data will be saved in the current working directory; every time you change it, you should also re-run \Rfunction{prepareSPIA}.
Edges not included in SPIA have been coerced into the admitted SPIA types.
Metabolite mediated interactions (edges of propagation through metabolites) annotated in graphite with the "indirect" type are mapped into the SPIA edge type "indirect effect".
For more details see the \Biocpkg{SPIA} package \cite{Tarca2009,Adi2009,Draghici2007}.

<<spia1>>=
library(SPIA)
data(colorectalcancer)

library(hgu133plus2.db)
top$ENTREZ <- mapIds(hgu133plus2.db, top$ID, "ENTREZID", "PROBEID", multiVals = "first")
top <- top[!is.na(top$ENTREZ) & !duplicated(top$ENTREZ), ]
top$ENTREZ <- paste("ENTREZID", top$ENTREZ, sep = ":")
tg1 <- top[top$adj.P.Val < 0.05, ]

DE_Colorectal = tg1$logFC
names(DE_Colorectal) <- tg1$ENTREZ
ALL_Colorectal <- top$ENTREZ

biocarta <- pathways("hsapiens", "biocarta")[1:10]
biocarta <- convertIdentifiers(biocarta, "ENTREZID")
prepareSPIA(biocarta, "biocartaEx")
res <- runSPIA(de = DE_Colorectal, all = ALL_Colorectal, "biocartaEx")
res[1:5,]
@

\subsection{topologyGSA}

\Biocpkg{topologyGSA} uses graphical models to test the pathway components and to highlight those involved in its deregulation.

In \Biocpkg{graphite}, \Biocpkg{topologyGSA} has a dedicated function, \Rfunction{runTopologyGSA}, which performs the analysis on a single pathway or on a pathway list.

<<tg1>>=
library(topologyGSA)
data(examples)
colnames(y1) <- paste("SYMBOL", colnames(y1), sep = ":")
colnames(y2) <- paste("SYMBOL", colnames(y2), sep = ":")

kegg <- pathways("hsapiens", "kegg")
p <- convertIdentifiers(kegg[["Fc epsilon RI signaling pathway"]], "SYMBOL")
runTopologyGSA(p, "var", y1, y2, 0.05)
@

The function \Rfunction{runTopologyGSA}, which easily performs the analysis on the entire pathway database, provides as result a list of two elements: a list with the results of the pathway analyses and the list of generated errors.

For more details see the \Biocpkg{topologyGSA} package \cite{Massa2010}.

\subsection{clipper}

\Biocpkg{clipper} is a package for topological analysis. It implements a two-step empirical approach based on the exploitation of graph decomposition into a junction tree to reconstruct the most relevant signal path. In the first step clipper selects significant pathways according to statistical tests on the means and the concentration matrices of the graphs derived from pathway topologies. Then, it "clips" the whole pathway identifying the signal paths having the greatest association with a specific phenotype.

In \Biocpkg{graphite}, \Biocpkg{clipper} has a dedicated function, \Rfunction{runClipper}, which performs the analysis on a single pathway or on a pathway list.

<<tg2>>=
library(ALL)
library(a4Preproc)
library(clipper)

data(ALL)
pheno <- as(phenoData(ALL), "data.frame")
samples <- unlist(lapply(c("NEG", "BCR/ABL"), function(t) {
  which(grepl("^B\\d*", pheno$BT) & (pheno$mol.biol == t))[1:10]
}))
classes <- c(rep(1,10), rep(2,10))

expr <- exprs(ALL)[,samples]
rownames(expr) <- paste("ENTREZID",
                        featureData(addGeneInfo(ALL))$ENTREZID,
                        sep = ":")

k <- as.list(pathways("hsapiens", "kegg"))
selected <- k[c("Chronic myeloid leukemia", "Bladder cancer", "Cytosolic DNA-sensing pathway")]
clipped <- runClipper(selected, expr, classes, "mean", pathThr = 0.1)
resClip <- do.call(rbind, clipped$results)
resClip[, c("startIdx", "endIdx", "maxIdx", "lenght",
           "maxScore", "aScore", "involvedGenes")]
@

The function \Rfunction{runClipper}, which easily performs the analysis on the entire pathway database, provides as result a list of two elements: the list with the results of the pathway analyses and the list of eventually generated errors.

Since version 1.24, using the option {\it which} we can access the pathway with proteins and metabolites ({\it which = "mixed"}) or the pathway with only metabolites and edges propagated through proteins ({\it which} = "metabolites").

For more details see the \Biocpkg{clipper} package \cite{Martini2013}.

section{Build pathway}
In \Biocpkg{graphite}, it is also possible build a pathway object using \Rfunction{buildPathway}. This function creates a new object of type \Rclass{Pathway} given a data frame describing its edges. The edges should be divided in three dataframes containing edges between proteins, edges between proteins and metabolites, and edges between metabolites, and the should be included in the new pathway using {\it proteinEdges}, {\it mixedEdges} and {\it metaboliteEdges} respectively. This practice will guarantee the compatibility with \Rfunction{convertIdentifiers}, this only works with the types of identifiers that are provided in the Annotation package (for example using the string,‘"ENTREZID"’).

<<bldp>>=
edges <- data.frame(src_type = "ENTREZID", src="672",
                    dest_type = "ENTREZID", dest="7157",
                    direction="undirected", type="binding")
pathway <- buildPathway("#1", "example", "hsapiens", "database",
                        proteinEdges = edges)
@

<<bldp2>>=
edges <- data.frame(src_type = "ENTREZID", src="672",
                    dest_type = "ENTREZID", dest="7157",
                    direction="undirected", type="binding")
edgemix <- data.frame(src_type = "CHEBI", src="77750",
                    dest_type = "ENTREZID", dest="7157",
                    direction="undirected", type="biochemicalReaction")
edgemet <- data.frame(src_type = "CHEBI", src="15351",
                    dest_type = "CHEBI", dest="77750",
                    direction="undirected", type="biochemicalReaction")
pathway <- buildPathway("#1", "example", "hsapiens", "database",
                        proteinEdges = edges,
                        mixedEdges = edgemix,
                        metaboliteEdges = edgemet)
@

\begin{thebibliography}{9}

\bibitem{KEGG}
  Ogata H, Goto S, Sato K, Fujibuchi W, Bono H, Kanehisa M.
  KEGG: Kyoto Encyclopedia of Genes and Genomes.
  Nucleic Acids Res. 1999 Jan 1;27(1):29-34.

\bibitem{Reactome}
  Matthews L, Gopinath G, Gillespie M, Caudy M, Croft D, de Bono B, Garapati P, Hemish J, Hermjakob H, Jassal B, Kanapin A, Lewis S, Mahajan S, May B, Schmidt E, Vastrik I, Wu G, Birney E, Stein L, D'Eustachio P.
  Reactome knowledgebase of human biological pathways and processes.
  Nucleic Acids Res. 2009 Jan;37(Database issue):D619-22. Epub 2008 Nov 3.

\bibitem{NCI}
  Schaefer CF, Anthony K, Krupa S, Buchoff J, Day M, Hannay T, Buetow KH.
  PID: the Pathway Interaction Database.
  Nucleic Acids Res. 2009 Jan;37(Database issue):D674-9. Epub 2008 Oct 2.

\bibitem{Draghici2007}
  Draghici, S., Khatri, P., Tarca, A.L., Amin, K., Done, A., Voichita, C., Georgescu, C., Romero, R.
  A systems biology approach for pathway level analysis.
  Genome Research, 17, 2007.

\bibitem{Tarca2009}
  Tarca AL, Draghici S, Khatri P, Hassan SS, Mittal P, Kim JS, Kim CJ, Kusanovic JP, Romero R.
  A novel signaling pathway impact analysis.
  Bioinformatics. 2009 Jan 1;25(1):75-82.

\bibitem{Adi2009}
  Adi L. Tarca, Sorin Draghici, Purvesh Khatri, et. al.
  A Signaling Pathway Impact Analysis for Microarray Experiments.
  Bioinformatics, 2009, 25(1):75-82.

\bibitem{Massa2010}
  Massa MS, Chiogna M, Romualdi C. Gene set analysis exploiting the topology of a pathway.
  BMC System Biol. 2010 Sep 1;4:121.

\bibitem{Martini2013}
  Martini P, Sales G, Massa MS, Chiogna M, Romualdi C.
  Along signal paths: an empirical gene set approach exploiting pathway topology.
  Nucleic Acids Res. 2013 Jan 7;41(1):e19. doi: 10.1093/nar/gks866. Epub 2012 Sep 21.

\bibitem{humancyc}
  Caspi R, Altman T, Dale JM, Dreher K, Fulcher CA, Gilham F, Kaipa P, Karthikeyan AS, Kothari A, Krummenacker M, Latendresse M, Mueller LA, Paley S, Popescu L, Pujar A, Shearer AG, Zhang P, Karp PD.
  The MetaCyc database of metabolic pathways and enzymes and the BioCyc collection of pathway/genome databases.
  Nucleic Acids Research 38:D473-9 2010.

\bibitem{panther}
  PANTHER in 2013: modeling the evolution of gene function, and other gene attributes, in the context of phylogenetic trees.
  Huaiyu Mi, Anushya Muruganujan and Paul D. Thomas
  Nucl. Acids Res. (2012) doi: 10.1093/nar/gks1118

\bibitem{pharmgkb}
  Whirl-Carrillo M, McDonagh EM, Hebert JM, Gong L, Sangkuhl K, Thorn CF, Altman RB, Klein TE.
  Pharmacogenomics knowledge for personalized medicine.
  Clin Pharmacol Ther. 2012 Oct;92(4):414-7. doi: 10.1038/clpt.2012.96. Review. PubMed

\bibitem{smpdb}
  Jewison T, Su Y, Disfany FM, Liang Y, Knox C, Maciejewski A, Poelzer J, Huynh J, Zhou Y, Arndt D, Djoumbou Y, Liu Y, Deng L, Guo AC, Han B, Pon A, Wilson M, Rafatnia S, Liu P, Wishart DS.
  SMPDB 2.0: big improvements to the Small Molecule
  Pathway Database. Nucleic Acids Res.
  2014 Jan;42(Database issue):D478-84. doi:10.1093/nar/gkt1067. Epub 2013 Nov 6.

\end{thebibliography}

\end{document}
