Enrichment Map User Guide

Overview

The Enrichment Map Cytoscape Plugin allows you to visualize the results of gene-set enrichment as a network. It will operate on any generic enrichment results as well as specifically on Gene Set Enrichment Analysis (GSEA) results. Nodes represent gene-sets and edges represent mutual overlap; in this way, highly redundant gene-sets are grouped together as clusters, dramatically improving the capability to navigate and interpret enrichment results.

Gene-set enrichment is a data analysis technique taking as input

1. a (ranked) gene list, from a genomic experiment
   

2. gene-sets, grouping genes on the basis of a-priori knowledge (e.g. Gene Ontology) or experimental data (e.g. co-expression modules)

and generating as output the list of enriched gene-sets, i.e. best sets that summarizing the gene-list. It is common to refer to gene-set enrichment as functional enrichment because functional categories (e.g. Gene Ontology) are commonly used as gene-sets.

Installation

The Enrichment Map Plugin requires Cytoscape Version 2.6.x. If you don't have Cytoscape or an older Version (2.5 or older), please download the latest Release from http://www.cytoscape.org/ and install it on your computer.

• Download the Enrichment Map plugin from Software/EnrichmentMap and manually place the file EnrichmentMap.jar in the Cytoscape/plugins folder.

Quick Start Guide

Creating an Enrichment Map

You have a few different options:

• Load GSEA Results
• Load Generic Results
• Load David Results
• Load Bingo Results

The only difference between the above modes is the structure of the enrichment table(s). In either case, to use the plugin you will need the following files:

• file.gmt: gene-set to gene ID
• file.txt or .gct: expression matrix [OPTIONAL]
• file.txt or .xls (*): enrichment table(s)

(*) GSEA saves the enrichment table as a .xls file; however, these are not true Excel files, they are tab-separated text files with a modified extension; Enrichment Map does not work with "true" Excel .xls files.

If your enrichment results were generated from GSEA, you will just have to pick the right files from your results folder. If you have generated the enrichment results using another method, you will have to go to the Full User Guide, File Format section, and make sure that the file format complies with Enrichment Map requirements.

You can use the parameter defaults. For a more careful choice of the parameter settings, please go to the Full User Guide, Tips on Parameter Choice.

Graphical Mapping of Enrichment

• Nodes represent gene-sets.
• Edges represent mutual overlap.
• Enrichment significance (p-value) is conveyed as node colour intensity.

• The enriched phenotype is conveyed by node colour hue.
  

  • Note: In standard two-class designs, where two phenotypes are compared (e.g. treated vs untreated) the colour hue conveys the enriched phenotype; this is equivalent to mapping enrichment in up- and down-regulated genes, if one of the two phenotypes is assumed as reference (e.g. untreated), and the other phenotype is the one of interest; in such a case, enriched in the phenotype of interest means up, and enrichment in the reference phenotype means down.

• Node size represents how many genes are in the gene-set.

Exploring the Enrichment Map

• The "Parameters" tab in the "Results Panel" on the right side of the window contains a legend mapping the colours to the phenotypes and displaying the parameters used to create the map (cut-off values and data files).
• The "Network" tab in the "Control Panel" on the left lists all available networks in the current session and at the bottom has a overview of the current network which allows to easily navigate in a network even at higher zoom levels by dragging the blue rectangle (the current view) over the network.
• Clicking on a node (the circle that represents a gene set) will open the "EM Geneset Expression Viewer" tab in the "Data Panel" showing a heatmap of the expression values of all genes in the selected gene set.
• Clicking on an edge (the line between two nodes) will open the "EM Overlap Expression Viewer" tab in the "Data Panel" showing a heatmap of the expression values of all genes both gene sets that are connected by this edge have in common.
• If several nodes and edges are selected (e.g. by dragging a selection box around the desired gene sets) the "EM Geneset Expression Viewer" will show the union of all genes in the selected gene sets and the "EM Overlap Expression Viewer" will show only those genes that all selected gene sets have in common.

Advanced tips

• With large networks and low zoom-levels Cytoscape automatically reduces the details (such as hiding the node labels and not showing the node borders). To override this mechanism click on "View / Show Graphics Details"

• The VizMapper and the Node- and Edge Attribute Browser open up a lot more visualization options like linking the label size to Enrichment Scores or p-values. Refer to the Cytoscape manual at www.cytoscape.org for more information.

• If you have used Genesets from GSEAs MSigDb, you can access additional informations for each gene set, by adding the a new property:
  

  • (Edit / Preferences / Properties... / Add -> enter property name: nodelinkouturl.MSigDb -> enter property value: http://www.broad.mit.edu/gsea/msigdb/cards/%ID%.html -> [ ] Make Current Cytoscape Properties default -> (OK) ). Now you can right-click on a node and choose LinkOut/MSigDb to open the Database entry of the Geneset represented by that node in your Browser.

• When loading GSEA results there is no need to specify each file. Use the GSEA RPT file to auto-populate all the file fields in the EM interface. Check out: How to use RPT files

Full User Guide

File Formats

Gene sets file (GMT file)

• Each row of the geneset file represents one geneset and consists of:
  • geneset name (--tab--) description (--tab--) a list of tab-delimited genes that are part of that geneset.
• The geneset names must be unique.
• The gene set file describes the genesets used for the analysis. These files can be obtained

  1. directly downloading our monthly updated gene-set collections from Baderlab geneses collections. Description of sources and methods used to create collection can be found here

  2. directly downloading gene-sets collected in the MSigDB
     

  • Note: if you use MSigDB Gene Ontology gene-sets, please consider that they do not include all annotations, as an evidence code filter is applied; if you are interested in achieving maximum coverage, download the original annotations

    1. converting gene annotations / pathways from public databases
       

  • ~-Note: if you are a R user, Bioconductor offers annotation packages such as GO.db, org.Hs.eg.db, KEGG.db

Expression Data file (GCT, TXT or RNK file) [OPTIONAL]

• The expression data can be loaded in three different formats: gct (GSEA file type), rnk (GSEA file type) or txt.
• The expression data serves two purposes:
  • Gene sets are filtered based on the genes present in the expression file. For example, if Geneset X contains genes
• Expression data is not required. In the absence of an expression file Enrichment map will create a dummy expression file to associate with the data set. The dummy expression gives an expression value of 1 for all the genes associated with the enriched genesets in the Enrichment map.

GCT (GSEA file type)

• GCT differs from TXT only because of two additional lines that are required at the top of the file.

• The GCT file contains two additional lines at the top of the file.
  • The first line contains #1.2.
  • The second line contains the number of data rows (tab) the number of data columns.
  • The third line consists of column headings.
    • name (--tab--) description (--tab--) sample1 name (--tab--) sample2 name …
  • Each line of expression file contains a:
    • name (--tab--) description (--tab--) followed by a list of tab delimited expression values.
• NOTE: If the GCT file contains Probeset ID's as primary keys (e.g. as you had GSEA collapse your data file to gene symbols) you need to convert the gct file to use the same primary key as used in the gene sets file (GMT file). You have the following options:
  • Use the GSEA desktop application: GSEA / Tools / Collapse Dataset

  • Run this Python script collapse_ExpressionMatrix.py using the Chip platform file that was used by GSEA.

RNK (GSEA file type)

• RNK file is completely different from the GCT or TXT file. It represents a ranked list of genes containing only gene name and a rank or score.

• The first line contains column headings
  • (For example:) Gene Name (--tab--) Rank Name
• Each line of RNK file contains a:
  • name (--tab--) rank OR score

Additional Information on GSEA File Formats can be found here

TXT

• Basic file representing expression values for an experiment.
• The first line consists of column headings.
  • name (--tab--) description (--tab--) sample1 name (--tab--) sample2 name ...
• Each line of the expression file contains a:
  • name (--tab--) description (--tab--) followed by a list of tab delimited expression values.

Enrichment Results files

GSEA result files

• For each analysis GSEA produces two output files. One representing the enriched genesets in phenotype A and the other representing the enriched genesets in phenotype B.
• These files are usually named "gsea_report_for_phenotypeA.Gsea.########.xls" and "gsea_report_for_phenotypeB.Gsea.########.xls"
• The files should be loaded in as is and require no pre-processing.
• There is no need to worry about which Enrichment Results Text box to put the two files. The phenotype is specified by the sign of the ES score and is computed internally by the program.

Additional Information on GSEA File Formats can be found here

Generic results files

• The generic results file is a tab delimited file with enriched gene-sets and their corresponding p-values (and optionally, FDR corrections)
• The Generic Enrichment Results file needs:
  • gene-set ID (must match the gene-set ID in the GMT file),
  • gene-set name or description,
  • p-value,
  • FDR correction value
  • Phenotype: +1 or -1, to identify enrichment in up- and down-regulation, or, more in general, in either of the two phenotypes being compared in the two-class analysis
    • +1 maps to red
    • -1 maps to blue

Notes:

1. description and FDR columns can have empty or NA values, but the column and the column header must exist
2. if no value is provided under phenotype, Enrichment Map will assume there is only one phenotype, and will map enrichment p-values to red

See here for examples

DAVID Enrichment Result File

• Available only in v1.0 or higher

• When using DAVID as the analysis type there is no requirement to enter either a gmt file or an expression file. Both are options if the user wishes to add them to the analysis.

• The DAVID Enrichment Result File is a file generated by the DAVID Functional Annotation Chart Report and consists of the following fields: Important: Make sure you are using CHART Report and NOT a Clustered Report

  • Category (DAVID category, i.e. Interpro, sp_pir_keywords, ...)
  • Term - Gene set name
  • Count - number of genes associated with this gene set
  • Percentage (gene associated with this gene set/total number of query genes)
  • P-value - modified Fisher Exact P-value
  • Genes - the list of genes from your query set that are annotated to this gene set.
  • List Total - number of genes in your query list mapped to any gene set in this ontology
  • Pop Hits - number of genes annotated to this gene set on the background list
  • Pop Total - number of genes on the background list mapped to any gene set in this ontology.
  • Fold enrichment
  • Bonferroni
  • Benjamini
  • FDR

Notes:

1. The DAVID option expects a file as generated by the DAVID web interface.

2. DISCLAIMER : In the absence of a gmt gene sets are constructed based on the field Genes in the DAVID output. This only considers the genes entered in your query set and not the genes in your background set. This will drastically affect the amount of overlap you see in the resulting Enrichment Map.

See here for tutorial on how to generate David output files for Enrichment maps

BiNGO Enrichment Result File

• Available only in v1.2 or higher

• When using BiNGO as the analysis type there is no requirement to enter either a gmt file or an expression file. Both are options if the user wishes to add them to the analysis.

• The BiNGO Enrichment Result File is a file generated by the BiNGO cytoscape plugin and consists of the following fields: Important: When running BiNGO make sure to check off "Check Box for saving data"

  • The first 20 lines of BiNGO output file list parameters used for the analysis and are ignored by the Enrichment map plugin

  • GO-ID - Gene set name
  • p-value - hypergeometric or binomial Exact P-value
  • corr p-value - corrected p-value
  • x - number of genes in your query list mapped to this gene-set
  • n - number of genes in the background list mapped to this gene-set
  • X - number of genes annotated to this gene set on the background list
  • N - number of genes on the background list mapped to any gene set in this ontology.
  • Description - gene list description
  • Genes - the list of genes from your query set that are annotated to this gene set.

Notes:

1. The BiNGO option expects a file as generated by the BiNGO Cytsocape Plugin.

2. DISCLAIMER : In the absence of a gmt gene sets are constructed based on the field Genes in the BiNGO output. This only considers the genes entered in your query set and not the genes in your background set. This will drastically affect the amount of overlap you see in the resulting Enrichment Map.

See here for tutorial on how to generate Bingo output files for Enrichment maps

RPT files

• A special trick for GSEA results, in any GSEA analysis an rpt file is created that specifies the location of all files (including the gmt, gct, results files, phenotype specification, and rank files).
• Any of the Fields under the dataset tab (Expression, Enrichment Results 1 or Enrichment Results 2) will accept an rpt file and populate GMT, Expression, Enrichment Results 1, Enrichment Results 2, Phenotypes, and Ranks the values for that dataset.
• A second rpt file can be loaded for dataset 2. It will give you a warning if the GMT file specified is different than the one specified in dataset 1. You will have the choice to use the GMT for data set 1, data set 2 or abort the second rpt load.

• An rpt file is a text file with following information (parameters surrounded by "" are those that EM uses):

                '''producer_class'''    xtools.gsea.Gsea
                '''producer_timestamp'''        1367261057110
                param   collapse        false
                param   '''cls'''       WHOLE_PATH_TO_FILE/EM_EstrogenMCF7_TestData/ES_NT.cls#ES24_versus_NT24
                param   plot_top_x      20
                param   norm    meandiv
                param   save_rnd_lists  false
                param   median  false
                param   num     100
                param   scoring_scheme  weighted
                param   make_sets       true
                param   mode    Max_probe
                param   '''gmx'''       WHOLE_PATH_TO_FILE/EM_EstrogenMCF7_TestData/Human_GO_AllPathways_no_GO_iea_April_15_2013_symbol.gmt
                param   gui     false
                param   metric  Signal2Noise
                param   '''rpt_label''' ES24vsNT24
                param   help    false
                param   order   descending
                param   '''out'''       WHOLE_PATH_TO_FILE/EM_EstrogenMCF7_TestData
                param   permute gene_set
                param   rnd_type        no_balance
                param   set_min 15
                param   include_only_symbols    true
                param   sort    real
                param   rnd_seed        timestamp
                param   nperm   1000
                param   zip_report      false
                param   set_max 500
                param   '''res'''       WHOLE_PATH_TO_FILE/EM_EstrogenMCF7_TestData/MCF7_ExprMx_v2_names.gct

                file    WHOLE_PATH_TO_FILE/EM_EstrogenMCF7_TestData/ES24vsNT24.Gsea.1367261057110/index.html

1. producer_class - can be xtools.gsea.Gsea or xtools.gsea.GseaPreranked

   • if xtools.gsea.Gsea:

     • get expression file from res parameter in rpt
     • get phenotype information from cls parameter in rot

   • if xtools.gsea.GseaPreranked:

     • No expression file
     • use rnk as the expression file from rnk parameter in rot
     • set phenotypes to na_pos and na_neg.
     • NOTE: if you want to make using an rpt file easier for GSEAPreranked there are two additional parameters you can add to your rpt file manually that the rpt function will recognize.

To do less manual work while creating Enrichment Maps from pre-ranked GSEA, add the following optional parameters:
        param(--tab--)phenotypes(--tab--){phenotype1}_versus_{phenotype2}
        param(--tab--)expressionMatrix(--tab--){path_to_GCT_or_TXT_formated_expression_matrix}

        enrichment File 1 --> {out}(--File.separator--){rpt_label} + "." + {producer_class} + "." + {producer_timestamp}(--File.separator--) "gsea_report_for_" + phenotype1 + "_" + timestamp + ".xls"
        enrichment File 2 --> {out}(--File.separator--){rpt_label} + "." + {producer_class} + "." + {producer_timestamp}(--File.separator--) "gsea_report_for_" + phenotype2 + "_" + timestamp + ".xls"
        ranks File --> {out}(--File.separator--){rpt_label} + "." + {producer_class} + "." + {producer_timestamp}(--File.separator--) "ranked_gene_list_" + phenotype1 + "_versus_" + phenotype2 +"_" + timestamp + ".xls";

  * NOTE: The gene_sets.gmt file contained in the edb directory is filtered according to the expression file.  If you are doing a two dataset analysis where the expression files are from different platforms or contain different sets of genes the edb gene_sets.gmt file can not be used as genes found in one analysis might be lacking in the other.  In this case use the original gmt file (prior to GSEA filtering) and EM will filter each the gene sets separately according to each dataset.

• For each dataset there are additional parameters that the user can set but are not required.
• The advanced parameters include:

  • Ranks file - file specifying the ranks of the genes in the analysis

    • This file has the format specified in the above section - gene (--tab--) rank or score. Seehere for details.

  • Phenotypes (phenotype1 versus phenotype2)

    • By default the phenotypes are set to Up and Down but in the advanced setting mode the user can change these to any desired text.

• All of these fields are populated when the user loads the input files using the rpt option.

Parameters

                Jaccard Coefficient = [size of (A intersect B)] / [size of (A union B)]

                Overlap Coefficient = [size of (A intersect B)] / [size of (minimum( A , B))]

                Jaccard Coefficient = [size of (A intersect B)] / [size of (A union B)]
                Overlap Coefficient = [size of (A intersect B)] / [size of (minimum( A , B))]
                
                Combined Constant = k

                Combined Coefficient = (k * Overlap) + ((1-k) * Jaccard)

1. Analysis Type

   • There are two distinct types of Enrichment map analyses, GSEA or Generic.

     • GSEA - takes as inputs the output files created in a GSEA analysis. File formats are specific to files created by GSEA. The main difference between this and generic is the number and format of the Enrichment results files. GSEA analysis always has two enrichment results files, one for each of the phenotypes compared.

     • Generic - takes as inputs the same file formats as a GSEA analysis except the Enrichment results file is a different format and there is only one enrichment file. Generic File description

     • DAVID - (implemented in v1.0 and higher) has no gmt or expression file requirement and takes as input enrichment result file as produced by DAVID David Enrichment Result File description

2. Genesets - path to gmt file describing genesets. User can browse hard drive to find file by pressing ... button.

3. Dataset 1 - User can specify expression and enrichment files or alternatively, an rpt file which will populate all the fields in genesets,dataset # and advanced sections.

4. Advanced - Initially collapsed (expand by clicking on arrow head directly next to Advanced), users have the option of modifying the phenotype labels or loading gene rank files.

5. Parameters - User can specify p-value, fdr and overlap/jaccard cutoffs. Choosing Optimal parameter values

6. Actions - The user has three choices, Reset (clears input panel), Close (closes input panel), and Build Enrichment map (takes all parameters in panel and builds an Enrichment map)

The Data Panel

1. Post Analysis Type

   • Currently there is only one Type of Post Analysis available:

   • Signature Hubs - calculates the overlap between genesets of the current Enrichment Map and a number of selected external genesets.

2. Gene Sets

   • The user needs to supply two geneset-files (both in the gmt format):

   • GMT - Enrichment Genesets; the same geneset gmt file as used to create the Enrichment Map (this field will be usually already populated)

   • SigGMT - the gmt file with the Signature-Genesets

3. Load Genesets should be pressed after the file with the Signature-Genesets has been selected. This will populate the list of available Signature Genesets.

4. Available Signature Genesets – Once the genesets are loaded, this box will contain a list of all genesets defined in the SigGMT file. Click to highlight the desired geneset(s).
   

   • To highlight more than one geneset at a time, the user can click while pressing the [SHIFT]-, [COMMAND]- or [CTRL]-keys (depending on the Operating System).

5. Selected Signature Genesets – The Signature Hub analysis will be performed with all genesets in this list. The user can use the down- and up-buttons to move highlighted genesets from one list to the other.

6. Parameters – The User can choose a method and a cutoff for generating an edge between a signature-geneset and an enrichment geneset. The following methods are available:

   • Hypergeometric Test is the probability (p-value) to find an overlap of k or more genes between a signature geneset and an enrichment geneset by chance.
     

     • 
       with:
       k (successes in the sample) : size of the Overlap,
       n (size of the sample) : size of the Signature geneset
       m (total number of successes) : size of the Enrichment Geneset
       N (total number of elements) : size of the union of all Enrichment Genesets

   • Number of common Genes

   • directed Overlap is the fraction of the intersection of both genesets in respect to the Enrichment Geneset.

7. Actions - The user has three choices, Reset (clears input panel), Close (closes input panel), and Run (takes all parameters in panel and performs the Post-Analysis)

The post-analysis p-values can be accessed by: select the following attribute for display: "EM1_Overlap_Hypergeom_pVal" (Data Panel: Edge Attribute Browser tab, attribute selection icon)

Additional Features

"the subset of members that contribute most to the ES. For a positive ES, the leading edge subset is the set of members that appear in the ranked list prior to the peak score. For a negative ES, it is the set of members that appear subsequent to the peak score."

• Q: One of my enrichment map clusters has so much overlapping, I'm having a hard time interpreting it.
  A: Quickest solutions:

  1. Menu: Layout / Scale to expand the sub-network of interest (it will reduce clutter, but may take a lot of space)
  2. Results Panel: reduce the Q-value cutoff (it will make the sub-network less crowded, at the expense of the less relevant gene-sets)
  3. Clone the sub-network into a new network and use organic layout (organic layout has less clutter than force directed)

  4. Use the Software/WordCloudPlugin to summarize the node labels

  5. Make an enrichment map only of that sub-network using the Jaccard coefficient
     • this needs some scripting: you have to restrict the GMT to the gene-sets in the sub-network and make a new enrichment map selecting the Jaccard coefficient (instead of Overlap).
     • Jaccard usually works better with super-connected sub-networks, i.e. the ones arising when you have lots of GO-derived redundancy