Introduction to gep2pep

Francesco Napolitano

About gep2pep

Pathway Expression Profiles (PEPs) are based on the expression of all the pathways (or generic gene sets) belonging to a collection under a given experimental condition, as opposed to individual genes. gep2pep supports the conversion of gene expression profiles (GEPs) to PEPs and performs enrichment analysis of both pathways and conditions.

gep2pep creates a local repository of gene sets, which can also be imported from the MSigDB database [1]. The local repository is in the repo format. When a GEP, defined as a ranked list of genes, is passed to buildPEPs, the stored database of pathways is used to convert the GEP to a PEP and permanently store the latter.

One type of analysis that can be performed on PEPs and that is directly supported by gep2pep is the Drug-Set Enrichment Analysis (DSEA, see reference below). It finds pathways that are consistently dysregulated by a set of drugs, as opposed to a background of other drugs. Of course PEPs may refer to non-pharmacological conditions (genetic perturbations, disease states, etc.) for analogous analyses. See the CondSEA function.

A complementary approach is that of finding conditions under which a set of pathways is consistently UP- or DOWN-regulated. This is the pathway-based version of the Gene Set Enrichment Analysis (GSEA). As an application example, this approach can be used to find drugs mimicking the dysregulation of a gene by looking for drugs dysregulating the pathways involving the gene (this has been published as the gene2drug tool [3]). See the PathSEA function.

Toy and real-world examples

This vignette uses toy data, as real data can be computationally expensive. Connectivity Map data [4] (drug induced gene expression profiles) pre-converted to PEPs can be downloaded from http://dsea.tigem.it in the gep2pep format. At the end of this vignette, a precomputed example is reported in which that data is used.

Creating a repository of pathways

In order to use the package, it must be loaded as follows (the GSEABase package will also be used in this vignette to access gene set data):

library(gep2pep)
suppressMessages(library(GSEABase))

The MSigDB is a curated database of gene set collections. The entire database can be downloaded as a single XML file and used by gep2pep. The following commented code would import the database once downloaded (gep2pep uses a slight variation of the BroadCollection type used by MSigDB, named CategorizedCollection, thus a conversion is necessary):

## db <- importMSigDB.xml("msigdb_v6.1.xml")
## db <- as.CategorizedCollection(db)

However, for this vignette a small excerpt will be used.

db <- loadSamplePWS()

The database is in GSEABase::GeneSetCollection format and includes 30 pathways, each of which is included in one of 3 different collections. Following MSigDB conventions, each collection is identified by a “category” and “subCategory” fields. But the CategorizedCollection type allows them to be arbitrary strings, as opposed to MSigDB categories. This allows for the creation of custom collection with categories. gep2pep puts together into a single collection identifier using makeCollectionIDs.

colltypes <- sapply(db, collectionType)
cats <- sapply(colltypes, attr, "category")
subcats <- sapply(colltypes, attr, "subCategory")
print(cats)
##  [1] "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3" "c3"
## [15] "c3" "c3" "c3" "c3" "c3" "c3" "c4" "c4" "c4" "c4" "c4" "c4" "c4" "c4"
## [29] "c4" "c4"
print(subcats)
##  [1] "TFT" "TFT" "TFT" "TFT" "TFT" "TFT" "TFT" "TFT" "TFT" "TFT" "MIR"
## [12] "MIR" "MIR" "MIR" "MIR" "MIR" "MIR" "MIR" "MIR" "MIR" "CGN" "CGN"
## [23] "CGN" "CGN" "CGN" "CGN" "CGN" "CGN" "CGN" "CGN"
makeCollectionIDs(db)
##  [1] "c3_TFT" "c3_TFT" "c3_TFT" "c3_TFT" "c3_TFT" "c3_TFT" "c3_TFT"
##  [8] "c3_TFT" "c3_TFT" "c3_TFT" "c3_MIR" "c3_MIR" "c3_MIR" "c3_MIR"
## [15] "c3_MIR" "c3_MIR" "c3_MIR" "c3_MIR" "c3_MIR" "c3_MIR" "c4_CGN"
## [22] "c4_CGN" "c4_CGN" "c4_CGN" "c4_CGN" "c4_CGN" "c4_CGN" "c4_CGN"
## [29] "c4_CGN" "c4_CGN"

In order to build a local gep2pep repository containing pathway data, createRepository is used:

repoRoot <- file.path(tempdir(), "gep2pep_data")
rp <- createRepository(repoRoot, db)
## Repo root created.
## Repo created.
## [22:48:46] Storing pathway data for collection: c3_TFT
## [22:48:47] Storing pathway data for collection: c3_MIR
## [22:48:47] Storing pathway data for collection: c4_CGN

The repository is in repo format (see later in this document how to access the repository directly). However, knowing repo is not necessary to use gep2pep. The following lists the contents of the repository, loads the GeneSetCollection object containing all the TFT database gene sets and finally shows the description of the pathway “E47_01”:

rp
##                  ID Dims     Size
##  gep2pep repository    2  25.6 kB
##         c3_TFT_sets   10 18.83 kB
##         c3_MIR_sets   10 17.88 kB
##         c4_CGN_sets   10  7.42 kB
##          conditions    1     49 B
TFTsets <- loadCollection(rp, "c3_TFT")
TFTsets
## GeneSetCollection
##   names: AAANWWTGC_UNKNOWN, AAAYRNCTG_UNKNOWN, ..., SP1_01 (10 total)
##   unique identifiers: MEF2C, ATP1B1, ..., MEX3B (3156 total)
##   types in collection:
##     geneIdType: SymbolIdentifier (1 total)
##     collectionType: CategorizedCollection (1 total)
description(TFTsets[["E47_01"]])
## [1] "Genes having at least one occurence of the transcription factor binding site V$E47_01 (v7.4 TRANSFAC) in the regions spanning up to 4 kb around their transcription starting sites."

rp$get is a repo command, see later in this vignette.

Creating Pathway Expression Profiles

Pathway Expression Profiles (PEPs) are created from Gene Expression Profiles (GEPs) using pathway information from the repository. GEPs must be provided as a matrix with rows corresponding to genes and columns corresponding to conditions (conditions). Genes and conditions must be specified through row and column names respectively. The values must be ranks: for each condition, the genes must be ranked from that being most UP-regulated (rank 1) to that being most DOWN-regulated (rank equal to the number of rows of the matrix).

One well known database that can be obtained in this format is for example the Connectivty Map. A small excerpt (after further processing) is included with the gep2pep. The excerpt must be considered as a dummy example, as it only includes 500 genes for 5 conditions. It can be loaded as follows:

geps <- loadSampleGEP()
dim(geps)
## [1] 485   5
geps[1:5, 1:3]
##            (+)_chelidonine (+)_isoprenaline (+/_)_catechin
## AKT3                    87              115            404
## MED6                   347              398             33
## NR2E3                  373              119            440
## NAALAD2                227              317            377
## CDKN2B-AS1             216               79             21

The GEPs can be converted to PEPs using the buildPEPs function. They are stored as repository items by the names “category_subcategory”.

buildPEPs(rp, geps)
## [22:48:47] Working on collection: c3_TFT (1/3)
## ===========================================================================
## [22:48:47] Storing PEPs to the repository...
## [22:48:47] Storing condition information...
## [22:48:47] Done.
## [22:48:47] Working on collection: c3_MIR (2/3)
## ===========================================================================
## [22:48:47] Storing PEPs to the repository...
## [22:48:47] Storing condition information...
## [22:48:47] Done.
## [22:48:47] Working on collection: c4_CGN (3/3)
## ===========================================================================
## [22:48:47] Storing PEPs to the repository...
## [22:48:47] Storing condition information...
## [22:48:47] Done.

Each PEP is composed of an Enrichment Score (ES) – p-value (PV) pair associated to each pathway. ESs and PVs are stored in two separated matrices. For each condition, the p-value reports wether a pathway is significantly dysregulated and the sign of the corresponding ES indicates the direction (UP- or DOWN-regulation).

loadESmatrix(rp, "c3_TFT")[1:3, 1:3]
##        (+)_chelidonine (+)_isoprenaline (+/_)_catechin
## M3128       -0.3732815        0.4763897      0.2029289
## M11607       0.3762838        0.2299253      0.2882820
## M12599       0.4585062        0.2365145     -0.2372061
loadPVmatrix(rp, "c3_TFT")[1:3, 1:3]
##        (+)_chelidonine (+)_isoprenaline (+/_)_catechin
## M3128        0.2267728       0.05876085      0.8885505
## M11607       0.1248594       0.65717027      0.3809141
## M12599       0.4407217       0.98408373      0.9836051

Performing Analysis

Performing Condition-Set Enrichment Analysis (CondSEA).

Suppose the stored PEPs correspond to pharmacological perturbations. Then gep2pep can perform Drug-Set Enrichment Analysis (DSEA, see Napolitano et al., 2016, Bioinformatics). It finds pathways that are consistently dysregulated by a set of drugs, as opposed to a background of other drugs. Of course PEPs may refer to non-pharmacological conditions (genetic perturbations, disease states, etc.) for analogous analyses (Condition-Set Enrichment Analysis, CondSEA). Given a set pgset of drugs of interest, CondSEA (which in this case is a DSEA) is performed as follows:

The result is a list of of 2 elements, named “CondSEA” and “details”, the most important of which is the former. Per-collection results can be accessed as follows:

In this dummy example the statistical background is made of only 3 GEPs (we added 5 in total), thus, as expected, there are no significant p-values. For the c3_MIR collection, the pathway most UP-regulated by the chosen set of two drugs is M5012, while the most DOWN-regulated is M18759. They are respectively described as:

The analysis can be exported in XLS format as follows:

Performing CondSEA using Pathway Expression Profiles derived from drug-induced gene expression profiles yields Drug Set Enrichment Analysis (DSEA [2]).

Performing Pathway-Set Enrichment Analysis (PathSEA)

A complementary approach to CondSEA is Pathway-Set Enrichment Analysis (PathSEA). PathSEA searches for conditions that consistently dysregulate a set of pathways. It can be seen as a pathway-based version of the popular Gene Set Enrichment Analysis (GSEA). The PathSEA is run independently in each pathway collection.

PathSEA results are analogous to those of CondSEA, but condition-wise. A set of pathways con also be obtained starting from a gene of interest, for example:

Using a gene to obtain the pathways and performing PathSEA with drug-induced Pathway Expression Profiles yields “gene2drug” analysis, see the following reference:

A real-world example

Precomputed Pathway Expression Profiles of the Connectivity Map data in the gep2pep format can be downloaded, unpacked and opened as follows:

download.file("http://dsea.tigem.it/data/Cmap_MSigDB_v6.1_PEPs.tar.gz",
  "Cmap_MSigDB_v6.1_PEPs.tar.gz")

untar("Cmap_MSigDB_v6.1_PEPs.tar.gz")

rpBig <- openRepository("Cmap_MSigDB_v6.1_PEPs")

Using these data, two kinds of analysis can be performed:

  1. Drug Set Enrichment Analysis, which looks for commond pathways shared by a set of drugs.

  2. Gene2drug analysis, which looks for drugs dysregulating a gene of interest.

The analyses below are not built at runtime with this document and could become outdated.

Drug Set Enrichment Analysis (DSEA)

Drug Set Enrichment Analysis for a set of HDAC inhibitors using the Gene Ontology collections can be performed as follows:

The following code retrieves information about the top 10 pathways ranked by CondSEA in GO-MF.

Note that 2 main effects of HDAC inhibitors have been correctly identified: regulation of transcription, and alteration of the acetylation/deacetylation homeostasis. The full analysis can be exported to the Excel format with:

Gene2drug analysis

A Gene2drug analysis can be performed starting by a gene of interest, for example the TFEB gene. Pathways including the gene are found as follows:

The following code runs the PathSEA analysis on the pathways involving TFEB. Also in this case the analysis is performed on Gene Ontology collections. Note that a warning is thrown as the GO-CC category has no annotation for TFEB (this is ok).

Thus the top 10 drugs causing (or mimicking) TFEB upregulation are:

Note that the top drug, loperamide, has been demonstrated to induce TFEB translocation at very low concentrations [3]. As before, the full analysis can be exported to the Excel format with:

Advanced access to the repository

gep2pep users don’t need to understand how to interact with a gep2pep repository, however it can be useful in some cases. gep2pep repositories are in the repo format (see the repo package), so they can be accessed as any other repo repository. However item tags should not be changed, as they are used by gep2pep to identify data types. Each gep2pep repository always contains a special project item including repository and session information, which can be shown as follows:

rp$info("gep2pep repository")
## Project name: gep2pep repository 
## Description: This repository contains pathway information and possibly Pathway Expression Profiles created with the gep2pep package. 
## Resources: c3_TFT_sets
##  c3_MIR_sets
##  c4_CGN_sets
##  conditions
##  c3_TFT
##  c3_MIR
##  c4_CGN 
## Platform: x86_64-pc-linux-gnu (64-bit) 
## OS: Ubuntu 18.04.3 LTS 
## R version: 3.6.1 (2019-07-05) 
## Packages: GSEABase 1.48.0
##  graph 1.64.0
##  annotate 1.64.0
##  XML 3.98.1.20
##  AnnotationDbi 1.48.0
##  IRanges 2.20.0
##  S4Vectors 0.24.0
##  Biobase 2.46.0
##  BiocGenerics 0.32.0
##  gep2pep 1.6.0
##  knitr 1.25

Poject name and description can be provided when creating the repository (createRepository), or edited with rp$set("gep2pep repository", newname="my project name", description="my project description"). The repository will also contain an item for each pathway collection, and possibly an item for each corresponding PEP collection, as in this example:

rp
##                  ID Dims     Size
##  gep2pep repository    2  25.6 kB
##         c3_TFT_sets   10 18.83 kB
##         c3_MIR_sets   10 17.88 kB
##         c4_CGN_sets   10  7.42 kB
##          conditions    4    173 B
##              c3_TFT    2   1021 B
##              c3_MIR    2    974 B
##              c4_CGN    2     1 kB

In order to look at the space that the repository is using, the following command can be used:

rp$info()
## Root:            /tmp/Rtmphpto99/gep2pep_data 
## Number of items: 8 
## Total size:      72.85 kB

put, set and other repo commands can be used to alter repository contents directly, however this could leave the repository in an inconsistent state. The following code checks a repository for possible problems:

checkRepository(rp)
## [22:48:48] Checking repository consistency...
## Checking: gep2pep repository... ok.
## Checking: c3_TFT_sets... ok.
## Checking: c3_MIR_sets... ok.
## Checking: c4_CGN_sets... ok.
## Checking: conditions... ok.
## Checking: c3_TFT... ok.
## Checking: c3_MIR... ok.
## Checking: c4_CGN... ok.
## 
## Checking for extraneous files in repo root... ok.
## 
## [22:48:48] Cheching for gep2pep data consistency...
## 
## [22:48:48] Checking conditions list...
## [22:48:48] Ok.
## [22:48:48] Checking PEPs...
## [22:48:48] Checking collection: c3_TFT...
## [22:48:48] ok.
## [22:48:48] Checking collection: c3_MIR...
## [22:48:48] ok.
## [22:48:48] Checking collection: c4_CGN...
## [22:48:48] ok.
## [22:48:48] Checking wether different PEP collections include the same conditions...
## [22:48:48] All PEP collections have the same conditions

The last check (summary of commond conditions) ensures that the same conditions have been computed for all the pathway collections, which is however not mandatory.

Further documentation

Additional methodological help can be found at:

  1. http://dsea.tigem.it
  2. http://gene2drug.tigem.it
  3. Open access papers [2] and [3].

References

[1] Subramanian A. et al. Gene set enrichment analysis: A knowledge-based approach for interpreting genome-wide expression profiles. PNAS 102, 15545-15550 (2005).

[2] Napolitano F. et al, Drug-set enrichment analysis: a novel tool to investigate drug mode of action. Bioinformatics 32, 235-241 (2016).

[3] Napolitano F. et al, gene2drug: a Computational Tool for Pathway-based Rational Drug Repositioning, bioRxiv (2017) 192005; doi: https://doi.org/10.1101/192005

[4] Lamb, J. et al. The Connectivity Map: Using Gene-Expression Signatures to Connect Small Molecules, Genes, and Disease. Science 313, 1929-1935 (2006).

Built with gep2pep version 1.6.0