## page was renamed from Software/EnrichmentMap/GSEATutorial
#acl All:read
{{attachment:Software/EnrichmentMap/UserManual/enrichmentmap_logo3.png|Enrichment Map Logo|align="right"}}<<BR>> 
= Enrichment Map GSEA Tutorial =
<<TableOfContents(3)>>

== Outline ==

This quick tutorial will guide you through the generation of an Enrichment Map for an analysis performed using [[http://www.broadinstitute.org/gsea/| GSEA Gene Set Enrichment Analysis]].  

== To run this tutorial ==

    * You need to have Cytoscape installed : minimally 2.6.3 must be installed but preferable to have the latest version of Cytoscape  (e.g. version 3.1)
    * Install the Enrichment Map plugin from the Cytoscape plugin manager. If you install it manually (e.g. if you need to install a new version that doesn't happen to be in the plugin manager yet), then it must be in the Cytoscape-[Version#]/plugins folder --> For Cytoscape 2.8
    * Install the Enrichment Map App from the Cytoscape App manager in cytoscape 3.
    * You need to download the test data: [[attachment:GSEATutorial.zip]]

== Description of the tutorial files contained in the GSEATutorial folder ==
    * ES_NT.cls : phenotype definition for expression file required by GSEA. 
    * MCF_ExpMX_v2_names.gct : Expression File - Estrogen treatment, Official Gene Name as key. - Data for 12hr,24hr and 48hr.
    * Human_GO_AllPathways_no_GO_iea_April_15_2013_symbol.gmt: Gene set definition file.

== Instructions ==
=== Step 1: Generate GSEA output files ===
{{attachment:GSEA_tutorial.png|Screenshot GSEA Input Panel|align="right"}}
  1. GO to GSEA website - [[http://www.broadinstitute.org/gsea/]]
  1. Click on Downloads in the page header. 
    * From the '''javaGSEA Desktop Application''' right click on ''Launch with 1 Gb memory''. 
    * Click on “Save Target as…” and save shortcut to your desktop or your folder of choice so you can launch GSEA for your analysis without having to navigate to it through your web browser.
  1. Double click on GSEA icon you created.
  1. Click on ''Load data'' in left panel.
  1. Click on ''Browse for files…'' in newly opened '''Load data''' panel.
  1. Navigate to directory where you stored tutorial test set files. Select raw expression (.gct) file, sample class file(.cls) and gene set (.gmt) file. Click on ''Open''.
  1. Wait until confirmation box appears indicating that all files loaded successfully. Click on ''Ok''.
  1. Click on ''Run GSEA'' in left panel.
  1. Select the ''Expression dataset:''
     * Click on the arrow next to the ''Expression dataset'' text box.  
     * Select the expression set you wish to run the analysis on (MCF7_ExprMx_v2_names.gct).

  1. Select the ''Gene Set Database'':
    * Click on ''…'' next to the text box of ''Gene Set Database.''   
    * Click on ''Gene Matrix (local gmx/gmt)'' tab.
    * Select gmt file Human_GO_AllPathways_no_GO_iea_April_15_2013_symbo.gmt and click on ''Ok''.

  1. Select the ''Phenotype labels'' file
    * Click on ''…'' next to the text box of ''Phenotype labels''.
    * Make sure ''Select source file'' is set to ES_NT.cls.
    * Select ''ES12_versus_NT12'' and click on ''Ok''.

  1. Click on the down arrow next to the text box for ''Collapse dataset to gene symbols.'' Select '''false'''.
  1. Click on the down arrow next to the text box for ''Permutation type''. Select '''gene_set'''.
  1. Click on ''Show'' next to ''Basic fields''.
  1. Click in text box next to ''Analysis name'' and rename (example:estrogen_treatment_12hr_gsea_enrichment_results).
  1. Click on ''…'' next to “''Save results in this folder'' text box. Navigate to the folder where you wish to save the results (preferably the same directory where all the input files have been saved).
  1. Click on ''Run'' in the bottom right corner.

'''Note''': repeat steps for the 24hrs time-point but use ES24_versus_NT24 phenotype labels in step 11 instead and in step 15 change the Analysis name (example:estrogen_treatment_24hr_gsea_enrichment_results)..

<<BR>>
<<BR>>
=== Step 2: Generate Enrichment Map with GSEA Output ===
 * Folder containing the GSEA results: [[attachment:EM_EstrogenMCF7_GSEAresults.zip]]
{{attachment:GSEA_inputpanel.png|Screenshot David Input Panel|align="right"}}
   1. Open Cytoscape
   1. Locate the Apps tab and select --> EnrichmentMap --> Create Enrichment Map
   1. Make sure the Analysis Type is set to GSEA

   1. '''OPTION 1 - Manually load all files''' Please select the following files by clicking on the respective (...) button and selecting the file in the Dialog:
      * Gene Sets / GMT : `Human_GO_AllPathways_no_GO_iea_April_15_2013_symbol.gmt` (can be found in directory where you extracted the files downloaded in GSEATutorial.zip) 
      * Dataset 1 / Expression: `MCF7_ExprMx_v2_names.gct` (can be found in directory where you extracted the files downloaded in GSEATutorial.zip) 
      * Dataset 1 / Enrichments 1: `gsea_report_for_ES12_#############.xls` (can be found in directory where you put the GSEA results specified in Part 1, step 15)
      * Dataset 1 / Enrichments 2: `gsea_report_for_NT12_#############.xls` (can be found in directory where you put the GSEA results specified in Part 1, step 15)
      * Click on "''Advanced {{attachment:arrow_collapsed.gif}}''" to expand the panel
      * Dataset 1 / Ranks: `MCF7_ExprMx_v2_names_ExprMx_v2_names.ES_NT.cls_ES12_versus_NT12.rnk` (OPTIONAL) (can be found in directory where you put the GSEA results specified in Part 1, step 15)
      * Dataset 1 / Phenotypes 1: `ES12` VS `NT12` (OPTIONAL)

   1. '''OPTION 2 - Populate all fields using GSEA rpt file'''
     * Dataset 1 / Expression : `ES12vsNT12.Gsea.#############.rpt` (can be found in directory where you put the GSEA results specified in Part 1, step 15)
     * NOTE: If you are populating the fields using a rpt file and any of the file names appear in red font then the file EM needs was not found.  This can happen if you move your GSEA results folders around after they have been created.  For the missing file follow step 5 and re-populate the effected fields. 

   1. Tune Parameters
      * P-value cut-off `0.001`
      * Q-value cut-off `0.05`
      * Check Overlap Coefficient
         * Overlap coefficient cut-off `0.5`
   1. Build Enrichment Map
   1. Go to View, and activate Show Graphics Details 


<<BR>>


=== Step 3: Examining Results ===
  * Example EM session - Estrogen treatment vs no treatment at 12hr [[attachment:ES12_EM_example.cys]]

{{attachment:GSEA_EM.png|GSEA EM Result}}<<BR>>
'''Legend''':
  1. Node (inner circle) size corresponds to the number of genes in dataset 1 within the geneset
  1. Colour of the node (inner circle) corresponds to the significance of the geneset for dataset 1.
  1. Edge size corresponds to the number of genes that overlap between the two connected genesets.  Green edges correspond to both datasets when it is the only colour edge.  When there are two different edge colours, green corresponds to dataset 1 and blue corresponds to dataset 2.

'''GSEA Leading Edge Information''':
  1. Click on a node (gene set) in the Enrichment map.
  1. In the Data Panel, expression profile of all genes included in the selected gene-set should appear in the '''Heat Map (nodes)''' viewer tab
  1. Change the Normalization to your desired metric.
  1. Change the Sorting method to ''GSEARanking''.
  1. Genes part of the leading edge are highlighted in yellow.
<<BR>>
{{attachment:GSEA_leadingedge.png|GSEA EM leading edge}} 
 *'''Note''': Leading edge information is currently only available when looking at a single gene set
== For more detailed tutorials check out: ==
    * [[http://www.ncbi.nlm.nih.gov/pubmed/21877285|Visualizing gene-set enrichment results using the Cytoscape plug-in enrichment map. Merico D, Isserlin R, Bader GD. Methods Mol Biol. 2011;781:257-77. doi: 10.1007/978-1-61779-276-2_12.]]
    * [[http://www.ncbi.nlm.nih.gov/pubmed/23606248|Global proteomic profiling and enrichment maps of dilated cardiomyopathy.  Isserlin R, Merico D, Emili A. Methods Mol Biol. 2013;1005:53-66. doi: 10.1007/978-1-62703-386-2_5.]]