#acl RuthIsserlin:read,write,delete,revert All:
{{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
    * 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
    * 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.

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.]]

== 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 Taget 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''' pane.
  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. Click on the arrow next to the ''Expression dataset'' text box.  Select the expression set you wish to run the analysis on.
  1. Click on ''…'' next to the text box of ''Gene Set Database.''
  1. Click on ''Gene Matrix (local gmx/gmt)'' tab.
  1. Select gmt file Human_GO_AllPathways_no_GO_iea_April_15_2013_symbo.gmt and click on ''Ok''.
  1. Click on ''…'' next to the text box of ''Phenotype labels''.
  1. Make sure ''Select source file'' is set to ES_NT.cls.
  1. 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 14 - 21 for the 24hrs time-point but use ES24_versus_NT24 phenotype labels in step 14 instead and in step 20 change the Analysis name (example:estrogen_treatment_24hr_gsea_enrichment_results)..

=== Stpe 2: Generate Enrichment Map with GSEA Output ===
{{attachment:GSEA_inputpanel.png|Screenshot David Input Panel|align="right"}}
   1. Open Cytoscape
   1. Click on Plugins / Enrichment Maps / Load Enrichment Results
   1. Make sure the Analysis Type is set to GSEA
   1. '''OPTION 1 - 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 20)
   1. '''OPTION 2 - 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 20)
      * 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 20)
      * Click on "''Advanced {{attachment:arrow_collapsed.gif}}''" to expand the panel
      * Dataset 1 / Ranks: `ranked_gene_list_ES12_versus_NT12_1367261038781.xls` (OPTIONAL) (can be found in directory where you put the GSEA results specified in Part 1, step 20)
      * Dataset 1 / Phenotypes 1: `ES12` VW `NT12` (OPTIONAL)
   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 
    * '''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. 
<<BR>><<BR>><<BR>><<BR>><<BR>><<BR>><<BR>><<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.