Difference between revisions of "FAQ"

From GeneSetEnrichmentAnalysisWiki
Jump to navigation Jump to search
m
(Added commentary on non-finite errors in plotting)
 
(61 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<a href="http://www.broadinstitute.org/gsea/">GSEA Home</a> |  
+
[http://www.broadinstitute.org/gsea GSEA Home] |  
<a href="http://www.broadinstitute.org/gsea/downloads.jsp">Downloads</a> |  
+
[http://www.broadinstitute.org/gsea/downloads.jsp Downloads] |  
<a href="http://www.broadinstitute.org/gsea/msigdb/">Molecular Signatures Database</a> |  
+
[http://www.broadinstitute.org/gsea/msigdb Molecular Signatures Database] |  
 
[[Main_Page|Documentation]] |  
 
[[Main_Page|Documentation]] |  
<a href="http://www.broadinstitute.org/gsea/contact.jsp">Contact</a>
+
[http://www.broadinstitute.org/gsea/contact.jsp Contact]
 
<br>
 
<br>
 
<br>
 
<br>
Line 36: Line 36:
  
 
<h4>Can I use GSEA to analyze SNP, SAGE, ChIP-Seq or RNA-Seq data?</h4>
 
<h4>Can I use GSEA to analyze SNP, SAGE, ChIP-Seq or RNA-Seq data?</h4>
<p>We are happy to announce that [http://www.broadinstitute.org/cancer/software/genepattern GenePattern] now offers a [http://www.broadinstitute.org/cancer/software/genepattern/modules/RNA-seq/ suite of tools to support a wide variety of RNA-seq analyses], including short-read mapping, identification of splice junctions, transcript and isoform detection, quantitation, and differential expression. In particular, GenePattern has developed the <strong>ExprToGct</strong> module to convert RNA-Seq data to the gene expression matrix in the GCT format that can serve as an input for GSEA. For further details, please contact the [mailto:gp-help@broadinstitute.org GenePattern team].</p>
+
<p>For detailed information on using RNA-seq data sets with GSEA, [[Using_RNA-seq_Datasets_with_GSEA|please see this help page.]]</p>
<p>Alternatively, one can analyze the data with some extra work. For this, you will have to come up with a ranked list of unique human gene symbols based on your SNP, SAGE, ChIP-Seq or RNA-Seq data. Then you can analyze the ranked list using [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideTEXT.htm#_GSEAPreranked_Page GSEAPreranked] tool.</p>
+
<p>For other data types, it is generally recommended to use GSEA-Preranked, where the features being analyzed have been quantitatively ranked in order of most (largest value) to least (smallest value) "of interest"</p>
 +
<p>If the exact magnitude of the rank metric is not directly biologically meaningful select "classic" for your enrichment score (thus, not weighting each gene's contribution to the enrichment score by the value of its ranking metric).</p>
 +
<p>Please note that if you choose to use any of the gene sets available from MSigDB in your analysis, you need to make sure that the features listed in your RNK file are genes, and the genes are identified by their HUGO gene symbols. All gene symbols listed in the RNK file must be unique, and we recommend the values of the ranking metrics be unique.</p>
  
 
<h1>GSEA Data Files</h1>
 
<h1>GSEA Data Files</h1>
Line 85: Line 87:
 
</p>
 
</p>
 
<h4>What array platforms and organism species does GSEA support? </h4>
 
<h4>What array platforms and organism species does GSEA support? </h4>
<p>GSEA works on any data, as long as the gene identifiers in your expression data (the GCT file) match those in the gene sets (the GMT file), or if you have a CHIP file that provides the mapping between gene identifiers in your expression data and gene identifiers in the gene sets. All gene sets in MSigDB use human gene symbols regardless of the original organism. Consequently, our CHIP files provide the mappings from different platforms (e.g., mouse Affymetrix probe set IDs, human Affymetrix probe set IDs, etc.) to human gene symbols.</p>
+
<p>GSEA works on <strong>any</strong> data, as long as the gene identifiers in your [[Data_formats#Expression_Data_Formats|expression data]] match those in the [[Data_formats#Gene_Set_Database_Formats|gene sets file]].</p>
<p>To see what platforms (CHIP files) are available: start GSEA desktop application and click  [...] at "Chip platform(s)" on "Run GSEA" page.</p>
+
<p>Typically, GSEA uses gene sets from MSigDB. All gene sets in MSigDB consist of human gene symbols. GSEA has build-in tools for conversion between a variety of other gene identifiers to human gene symbols by means of specially formatted [[Data_formats#Microarray_Chip_Annotation_Formats|CHIP files]]. The CHIP files provide the mapping between gene identifiers in your expression data and gene identifiers in the gene sets. Specifically, our CHIP files provide the mappings from all kinds of different platforms (e.g., mouse Affymetrix probe set IDs, human Affymetrix probe set IDs, etc.) to human gene symbols.</p>
 +
<p>If your data was generated from non-human samples, then you need to decide whether using MSigDB meets your needs. The options are:</p>
 +
<ol>
 +
<li>The non-human species serves as a model to study conditions relevant for human biology. In this case, you want gene sets that are conserved between humans and your model organism. MSigDB is then the right choice and you will only need to provide the appropriate CHIP file for the analysis.</li>
 +
<li>The non-human species is the subject of your research, and you have no plans to compare it to human gene sets. In this case, you can still use MSigDB is your organism is among the sources of some of MSigDB gene sets (e.g., mouse or rat) and you will only need to provide the appropriate CHIP file for the analysis.</li>
 +
<li>The non-human species is the subject of your research and you don't want to use MSigDB gene sets for other reasons. In this case, you have to provide your own database of gene sets as a GMT or GMX file. The file formats are described [[Data_formats#Gene_Set_Database_Formats|here]]. Of course, you still have to make sure that the gene identifiers in your your data match those in your gene sets database. If the identifiers don't match each other, then you have to also provide a CHIP file with the appropriate mappings. The CHIP file format is described [[Data_formats#Microarray_Chip_Annotation_Formats|here]].
 +
</ol>
 +
<p>To see what CHIP files are available in our distribution (note: our CHIP files provide mappings to human gene symbols only): start GSEA desktop application and click  [...] at "Chip platform(s)" on "Run GSEA" page.</p>
 
<p>If your platform is not in this list, you have the following options:</p>
 
<p>If your platform is not in this list, you have the following options:</p>
 
<ol>
 
<ol>
     <li>Create your own CHIP file to map your platform specific gene identifiers to human gene symbols and then use your CHIP file to collapse dataset in GSEA. The CHIP file format is described here: [http://www.broadinstitute.org/cancer/software/gsea/wiki/index.php/Data_formats#CHIP:_Chip_file_format_.28.2A.chip.29 CHIP file format].</li>
+
     <li>Create your own CHIP file to map your platform specific gene identifiers to human gene symbols and then use your CHIP file to collapse dataset in GSEA. The CHIP file format is described [[Data_formats#Microarray_Chip_Annotation_Formats|here]].</li>
     <li>Convert your platform identifiers to human gene symbols outside GSEA, then run GSEA with 'Collapse dataset' = FALSE </li>
+
     <li>Convert your platform identifiers to human gene symbols outside GSEA, then run GSEA with 'Collapse dataset' = FALSE.
 +
<p>Make sure that gene symbols in the collapsed dataset appear only once. Simply replacing the identifiers with human gene symbols usually is not sufficient because some of the identifiers can correspond to the same human gene symbols, resulting in duplicate rows with different expression values. In this case, GSEA will arbitrarily pick one of the rows with the same gene symbols for the analysis, which we do not recommend.</p>
 +
</li>
 
</ol>
 
</ol>
  
 
<h4>Can GSEA analyze miRNA expression data?</h4>
 
<h4>Can GSEA analyze miRNA expression data?</h4>
<p class="MsoListContinue">The only way for GSEA to analyze expression data with miRNA identifiers is to provide gene sets made of matching miRNA identifiers. This is not possible with MSigDB gene sets, which are made exclusively of protein coding genes in the form of human gene symbols.</p>
+
<p class="MsoListContinue">The only way for GSEA to analyze expression data with miRNA identifiers is to provide gene sets made of matching miRNA identifiers. This is not possible with MSigDB gene sets, which consist predominantly of protein coding genes in the form of human gene symbols.</p>
  
 
<h1>GSEA Results</h1>
 
<h1>GSEA Results</h1>
Line 109: Line 120:
 
<p>By default, the GSEA analysis report generates a Details link, which provides summary plots and detailed analysis results, for the top 20 gene sets in each phenotype. To  generate the Details link for additional gene sets, modify the <em><span style="font-family: Arial;">Plot graphs for the top sets of each phenotype</span></em>  parameter on the [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Run_GSEA_Page Run GSEA Page]. </p>
 
<p>By default, the GSEA analysis report generates a Details link, which provides summary plots and detailed analysis results, for the top 20 gene sets in each phenotype. To  generate the Details link for additional gene sets, modify the <em><span style="font-family: Arial;">Plot graphs for the top sets of each phenotype</span></em>  parameter on the [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Run_GSEA_Page Run GSEA Page]. </p>
 
<h4>What should I do if I have no significant gene sets or too many significant gene sets?</h4>
 
<h4>What should I do if I have no significant gene sets or too many significant gene sets?</h4>
<p class="MsoNormal">The number of enriched gene sets depends on the structure of the data and the problem space. In general, one would expect to see at least a few gene sets enriched for a typical morphological or tissue-specific phenotype. If no enriched gene sets or a very large number of enriched gene sets pass the FDR threshold, first check that your gene sets and expression dataset use the same array format (see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Consistent_Feature_Identifiers Consistent Feature Identifiers Across Data Files])&nbsp; and that you have used the appropriate permutation type and number of permutations (see the [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Run_GSEA_Page Run GSEA Page]). If you find no issues, consider the following:</p>
+
<p>The number of enriched gene sets depends on the structure of the data and the problem space. In general, one would expect to see at least a few gene sets enriched for a typical morphological or tissue-specific phenotype. If no enriched gene sets or a very large number of enriched gene sets pass the FDR threshold, first check that your gene sets and expression dataset use the same array format (see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Consistent_Feature_Identifiers Consistent Feature Identifiers Across Data Files])&nbsp; and that you have used the appropriate permutation type and number of permutations (see the [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Run_GSEA_Page Run GSEA Page]). If you find no issues, consider the following:</p>
 
<ul>
 
<ul>
     <li><span style="font-family: &quot;Times New Roman&quot;;">No enriched gene sets of significance may indicate that, in fact, no gene sets are enriched. It may also be that you are analyzing too few samples, the biological signal in question is subtle, or the gene sets that you are analyzing do not represent the biology in question very well. You may still want to look at the top ranked gene sets, keeping in mind that these results provide weak evidence for potentially interesting hypotheses. You might also want to consider analyzing other gene sets or, if possible, additional samples. </span></li>
+
     <li>No enriched gene sets of significance may indicate that, in fact, no gene sets are enriched. It may also be that you are analyzing too few samples, the biological signal in question is subtle, or the gene sets that you are analyzing do not represent the biology in question very well. You may still want to look at the top ranked gene sets, keeping in mind that these results provide weak evidence for potentially interesting hypotheses. You might also want to consider analyzing other gene sets or, if possible, additional samples.</li>
     <li><span style="font-family: &quot;Times New Roman&quot;;">Too many enriched gene sets of significance may indicate that, in fact, many gene sets are enriched between phenotypes. Perhaps the gene sets represent the same biological signal. You can check for this by looking for overlap in the leading-edge subsets within the gene sets [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Running_a_Leading Running a Leading Edge Analysis]). Or, you might be seeing significant differences between the phenotypes due to technical artifacts, such as samples being run in different labs, by different operators, or against different arrays. As with too few enriched gene sets, you may still want to look at the top ranked gene sets, keeping in mind that these results provide potentially biased evidence for interesting hypotheses. You might also want to consider analyzing other gene sets or, if possible, additional samples. </span></li>
+
     <li>Too many enriched gene sets of significance may indicate that, in fact, many gene sets are enriched between phenotypes. Perhaps the gene sets represent the same biological signal. You can check for this by looking for overlap in the leading-edge subsets within the gene sets [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Running_a_Leading Running a Leading Edge Analysis]). Or, you might be seeing significant differences between the phenotypes due to technical artifacts, such as samples being run in different labs, by different operators, or against different arrays. As with too few enriched gene sets, you may still want to look at the top ranked gene sets, keeping in mind that these results provide potentially biased evidence for interesting hypotheses. You might also want to consider analyzing other gene sets or, if possible, additional samples. </li>
 
</ul>
 
</ul>
<p class="MsoListContinue">For more information, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Interpreting_GSEA Interpreting GSEA] in the <em style="">GSEA User Guide</em>.<br />
+
<p class="MsoListContinue">For more information, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Interpreting_GSEA Interpreting GSEA] in the <em style="">GSEA User Guide</em>.</p>
</p>
+
 
 
<h4>What does it mean for a&nbsp; gene set to have a nominal p value of zero?</h4>
 
<h4>What does it mean for a&nbsp; gene set to have a nominal p value of zero?</h4>
 
<p class="MsoListContinue">A reported p value of zero (0.0) indicates an actual p-value of less than 1/number-of-permutations. For a more accurate p value, increase the number of permutations performed by the analysis. For more information about gene set enrichment analysis results, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Interpreting_GSEA Interpreting GSEA] in the <em style="">GSEA User Guide</em>.</p>
 
<p class="MsoListContinue">A reported p value of zero (0.0) indicates an actual p-value of less than 1/number-of-permutations. For a more accurate p value, increase the number of permutations performed by the analysis. For more information about gene set enrichment analysis results, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Interpreting_GSEA Interpreting GSEA] in the <em style="">GSEA User Guide</em>.</p>
Line 129: Line 140:
 
</p>
 
</p>
 
<h4>Why do some of the example datasets contain negative expression values? </h4>
 
<h4>Why do some of the example datasets contain negative expression values? </h4>
<p class="MsoListContinue">Because in older releases of Affymetrix gene chips expression values were trimmed averages over match and mismatched probes. If the mismatch probes were higher a negative number results.</p>
+
<p>Because in older releases of Affymetrix gene chips expression values were trimmed averages over match and mismatched probes. If the mismatch probes were higher a negative number results.</p>
<p class="MsoListContinue"><br />
+
 
 
<h4>Why comparing phenotypes A vs B gives different results from B vs A? </h4>
 
<h4>Why comparing phenotypes A vs B gives different results from B vs A? </h4>
 
<p> This is because these two comparisons produce different ranked lists of genes. You might expect similar results only if the ranked lists would be perfectly symmetrical, and this usually does not happen. </p>
 
<p> This is because these two comparisons produce different ranked lists of genes. You might expect similar results only if the ranked lists would be perfectly symmetrical, and this usually does not happen. </p>
  
<h1>MSIGDB Gene Sets</h1>
+
<h4>What does it mean for a gene set to have NES and nominal p-values of NaN (also shown as blanks)?</h4>
 +
<p>When adjusting for variation in gene set size, we normalize permuted ES(S, pi) and the observed ES(S) for a given S, separately rescaling the positive and negative scores by dividing by the mean of the ES(S, pi) to yield NES(S, pi) and NES(S). However, when the scores of the corresponding sign are absent, the mean ES(S, pi) = 0, and the division by zero will result in NaN values both for the NES(S, pi) and NES(S) as well as for the nominal p-values that follow from these calculations. The easiest way to overcome this issue would be to increase number of permutations. If this does not help, we recommend further exploring reasons for this bias. For example, it could be caused by a large difference in the number of samples of each phenotype class. For further details, please consult the GSEA PNAS 2005 paper, sections "Multiple Hypothesis Testing" in the "Mathematical Description of Methods" and the "Supporting Text" Appendix.</p>
 +
 
 +
<h4>Why didn't my gene set display an enrichment plot even though it is in the top hits?</h4>
 +
<p>Sometimes when running GSEA with metrics other than signal-to-noise, or t-test, some plots may fail to render resulting in a Java error message being printed in red text in the place of the plot on the results page. This error is typically caused by GSEA encountering a divide-by-zero in the internal ranking metric computation, or an overflow where the result of the calculation between phenotypes returns an "infinity". The presence of infinite values in the resulting internal ranked list can be confirmed by navigating to the GSEA results directory for the given run, opening the "edb" folder, and then inspecting the .rnk file in this directory for "Inf", "NaN" or similar strings. It might be possible to resolve these issues by adding a small pseudocount to the dataset. It should be noted that any such selected value here is arbitrary and we do not advise the selection of any specific value, consult your local bioinformaticians for specific guidance. This error may also occur in GSEA Preranked mode, in which case these non-finite values would have been present in the supplied preranked list and should be resolved though the original quantification pipeline.</p>
 +
 
 +
<h1>MSigDB Gene Sets</h1>
 
<h4>What is MSigDB?</h4>
 
<h4>What is MSigDB?</h4>
<p class="MsoListContinue">[http://www.broadinstitute.org/gsea/msigdb/ MSigDB], the Molecular Signature Database, contains curated gene sets for use with the gene set enrichment analysis. The GSEA team has begun the critical work of populating the MSigDb with curated gene sets. Increasing the number of gene sets increases the value of this resource; therefore, the GSEA team appreciates gene set contributions and encourages users to submit their gene sets to mailto:genesets@broadinstitute.org. For information about exporting gene sets from the MSigDB, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Gene_Sets Gene Sets] in the <em style="">GSEA User Guide</em>.</p>
+
<p>[http://www.broadinstitute.org/gsea/msigdb/ MSigDB], the Molecular Signature Database, contains curated gene sets for use with the gene set enrichment analysis. The GSEA team has begun the critical work of populating the MSigDb with curated gene sets. Increasing the number of gene sets increases the value of this resource; therefore, the GSEA team appreciates gene set contributions and encourages users to submit their gene sets to [mailto:genesets@broadinstitute.org genesets@broadinstitute.org]. For information about exporting gene sets from the MSigDB, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Gene_Sets Gene Sets] in the <em style="">GSEA User Guide</em>.</p>
 +
 
 
<h4>What is the difference between gene sets in MSigDB and GO/BioCarta/GenMAPP?</h4>
 
<h4>What is the difference between gene sets in MSigDB and GO/BioCarta/GenMAPP?</h4>
 
<p class="MsoListContinue" style="text-align: left;">[http://www.broadinstitute.org/gsea/msigdb/ MSigDB] contains gene sets formatted for use with GSEA. MSigDB places emphasis on a genomic, unbiased approach to the definition of gene sets; therefore, an important component of MSigDB is the collection of gene sets from published expression profiles. Unlike gene sets curated from prior knowledge (such as, GO, BioCarta, and so on), experimental sets provide an unbiased readout of a biological state; experimental sets from microarray experiments reflect purely transcriptional events.<br />
 
<p class="MsoListContinue" style="text-align: left;">[http://www.broadinstitute.org/gsea/msigdb/ MSigDB] contains gene sets formatted for use with GSEA. MSigDB places emphasis on a genomic, unbiased approach to the definition of gene sets; therefore, an important component of MSigDB is the collection of gene sets from published expression profiles. Unlike gene sets curated from prior knowledge (such as, GO, BioCarta, and so on), experimental sets provide an unbiased readout of a biological state; experimental sets from microarray experiments reflect purely transcriptional events.<br />
Line 161: Line 179:
 
<h4>Can I use the MSigDB gene sets without using GSEA?</h4>
 
<h4>Can I use the MSigDB gene sets without using GSEA?</h4>
 
Yes. You can view and download the gene sets from the [http://www.broadinstitute.org/gsea/msigdb/msigdb_index.html MSigDB page].
 
Yes. You can view and download the gene sets from the [http://www.broadinstitute.org/gsea/msigdb/msigdb_index.html MSigDB page].
<h4>Can I access the MSigDB gene sets using a web service?</h4>
 
<p class="MsoListContinue">You can use one of two URLs to display the XML representation of a gene  set (replace AKTPATHWAY with any gene set name): <br />
 
<br />
 
http://www.broadinstitute.org/gsea/msigdb/cards/BIOCARTA_AKT_PATHWAY.xml <br />
 
http://www.broadinstitute.org/gsea/msigdb/geneset_page.jsp?geneSetName=BIOCARTA_AKT_PATHWAY&amp;format=xml <br />
 
</p>
 
<p class="MsoListContinue"> The [http://www.broadinstitute.org/gsea/software/software_index.html Downloads] page provides an XML file that contains all MSigDB gene  sets and the content of their gene set pages. The [http://www.broadinstitute.org/gsea/msigdb/ MSigDB] page provides  online access to the gene sets. </p>
 
  
<h4>What does /// in a gene symbol mean?</h4>
+
 
<p class="MsoListContinue">This symbol indicates ambiguous mapping according to the Affymentrix conventions and serves as a field separator when a probe set id corresponds to several gene symbols.  /// may appear in some gene sets curated form Affymetrix (NetAffx) annotation data. GSEA ignores such genes.</p>
+
<h4>What does <tt>///</tt> in a gene symbol mean?</h4>
<h4>How can I view/access gene sets from the v2.5 release of MSigDB?</h4>
+
<p class="MsoListContinue">This symbol indicates ambiguous mapping according to the Affymentrix conventions and serves as a field separator when a probe set id corresponds to several gene symbols.  <tt>///</tt> may appear in some gene sets curated form Affymetrix (NetAffx) annotation data. GSEA ignores such genes.</p>
<p class="MsoListContinue">The MSigDB v2.5 files are archived and are still available for download  on the <a href="../../../../../../gsea/downloads.jsp">Downloads</a>  page. Scroll down to the bottom of the page to the 'Archived releases' section. &nbsp; You can also view these archived sets using the MSigDB Browser in the GSEA desktop application (refer to the [[GSEA_v2.0.7_Release_Notes|GSEA 2.0.7 Release Notes]] <a href="http://www.broadinstitute.org/gsea/doc/GSEAUserGuideTEXT.htm#_Browse_MSigDB_Page"></a>for further instructions). You can also check [[Msigdb_mapping_v2.5_to_v3|here]] to see which gene sets have been deprecated or renamed.<br />
+
 
</p>
+
<h4>How can I view/access gene sets from the v2.5 or v3.0 release of MSigDB?</h4>
 +
<p>The MSigDB v2.5 files are archived and are still available for download  on the [http://www.broadinstitute.org/gsea/downloads.jsp Downloadspage. Scroll down to the bottom of the page to the 'Archived releases' section.</p>
 +
<p>You can also view these archived sets using the MSigDB Browser in the GSEA desktop application (refer to the [[GSEA_v2.08._Release_Notes | GSEA 2.0.8 Release Notes]] or the  [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideTEXT.htm#_Browse_MSigDB_Page User Guide] for further instructions).</p>
 +
 
 
<h4>Should I run GSEA on one or multiple MSigDB collections?</h4>
 
<h4>Should I run GSEA on one or multiple MSigDB collections?</h4>
 
<p>We recommend running GSEA in individual collections, or even sub-collections of gene sets rather that on the entire MSigDB.
 
<p>We recommend running GSEA in individual collections, or even sub-collections of gene sets rather that on the entire MSigDB.
Line 179: Line 193:
  
 
<h1>GSEA Software</h1>
 
<h1>GSEA Software</h1>
 +
 +
<h4>What is the difference between GSEA, GSEA-P, and GSEA-R?</h4>
 +
<p class="MsoListContinue">GSEA refers to either the gene set enrichment analysis or the GSEA software. GSEA-P refers to the GSEA Java desktop software. GSEA-R refers to the R implementation of the software.<br /></p>
 +
<p class="MsoListContinue">We strongly recommend using the Java desktop GSEA software for standard analysis of microarray data. The Java implementation of  GSEA  does not require any programming experience, includes many additional features not present in GSEA-R, and comes with tutorial and extended documentation.</p>
 +
<p class="MsoListContinue">The R implementation of GSEA is closer to a working prototype than a finished software product. We make it available for users who want to tweak the GSEA algorithm rather than run routine GSEA analysis.
 +
We assume that such users not only have a very good command of R but are also familiar with GSEA algorithm. Also consistent with this view, the R implementation offers minimal features, leaving it up to the user to add them.</p>
 +
 
<h4>How do I increase the amount of memory available to GSEA?</h4>
 
<h4>How do I increase the amount of memory available to GSEA?</h4>
From the GSEA web site, you can launch the GSEA desktop application with 512 Mb or 1 Gb of memory. To change the amount of memory available to GSEA, download the .jar file and then start the application using a direct call to the jar file. On the command line, use the -Xmx flag to increase the amount of memory available to Java:<br />
+
From the GSEA website, the GSEA desktop application can be launched with 1, 2, 4, or 8 GB of memory. Use the dropdown menu above the launch button to specify the amount. Note that 32-bit Java will not support greater than 2 GB.
<code><span style="font-size: 10pt;">java -Xmx1024m -jar gsea2-2.05.jar<br />
+
<p>
</span></code>
+
When running GSEA from one of our downloadable bundles, you can increase the memory specification by editing the launcher file.  This is <tt>gsea.bat</tt> on Windows, <tt>gsea.sh</tt> or <tt>gsea-hidpi.sh</tt> on Linux, or <tt>gsea.command</tt> on Mac.  Modify the <tt>-Xmx</tt> setting as desired; for example, to use an 8 GB memory configuration this could be set to <tt>-Xmx8g</tt>.
<p><code><span style="font-size: 10pt;"> </span></code></p>
+
</p>
<code style="font-family: arial;"> </code>
+
<p>The same is true of the <tt>gsea-cli.sh</tt> and <tt>gsea-cli.bat</tt> scripts for command-line usage.  Note that it's also possible to edit the JNLP files in a similar way to create an even larger Java Web Start memory configuration.</p>
<p>Please note the following:</p>
+
 
<ul>
+
<p>For users of the Mac.app it is not easily possible to modify the memory configuration at this time. This is a known issue that we will aim to address in a future release.  If a higher memory configuration is absolutely required, we suggest using the command-line bundle with your own (separate) Java 11 installation.  The <tt>gsea.command</tt> script is still available for launching the GUI from this bundle.<br />
    <li>Check that you are using the correct .jar file: for GSEA 2.0.4, use gsea2.jar; for GSEA 2.0.5, use gsea2-2.05.jar.<br />
+
</p>
    </li>
 
    <li>Be sure to run the Java command from the folder that contains the .jar file or specify the full path to the .jar file.&nbsp; <br />
 
    </li>
 
    <li>For 32-bit machines, <span style="font-family: arial;">-Xmx1800</span>m appears to be the maximum allowed by Java. It is likely&nbsp; higher on 64-bit machines, but has not yet been tested. <br />
 
    </li>
 
    <li>For more information about using GSEA from the command line, see the GSEA User Guide:<br />
 
    http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?_Running_GSEA_from_the%20Command%20Line</li>
 
</ul>
 
  
 
<h4>How do I run GSEA from the command line?</h4>
 
<h4>How do I run GSEA from the command line?</h4>
<p>See [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Running_Command_Line Running GSEA from the Command Line] in the <em style="">GSEA User Guide</em>.<br />
+
<p>As of GSEA 4.0.0, there is a dedicated bundle available from our Downloads page for command-line usage; please refer to the included README file for an explanation of the command-line launcher script.  Note that a separate Java 11 installation is required.</p>
 +
 
 +
<p>See the <em>Command</em> feature of the various GSEA Desktop GUI screens for example constructions of command-lines. This is by far the easiest way to understand the various flags and options.</p>
 +
 
 +
<p>The Linux bundle contains exactly the same launcher script and README along with an embedded OpenJDK 11 JVM, so there's no need for a separate download for users on that platform.<br />
 +
</p>
 +
<h4>What version of Java do I need for the GSEA desktop software?</h4>
 +
<p>
 +
As of GSEA 4.0.0, the various platform-specific bundles (for Windows, Mac, and Linux) include an embedded OpenJDK 11 JVM, meaning a separate Java installation is no longer required for most users.
 +
</p>
 +
<p>
 +
Java 8 is required for use of the Java Web Start JNLP launchers (OpenJDK 8 is fine).<br />
 
</p>
 
</p>
<h4>What version of Java do I need for GSEA software?</h4>
+
 
<p class="MsoListContinue"><strong>Java 1.6</strong>: GSEA 2.0.6 requires Java 1.6. Click the Launch button on the [http://www.broadinstitute.org/gsea/downloads.jsp Downloads] page to run GSEA 2.0.6. If you do not have the correct version of Java installed when you start GSEA, an error message appears referring to an &quot;unsupported class version.&quot;</p>
+
<h4>I can't launch GSEA from the website on Windows.  This used to work; did something change?</h4>
<p class="MsoListContinue"><strong>Java 1.5</strong>: If you cannot upgrade to Java 1.6 you can use GSEA 2.0.4, which runs under Java 1.5. The GSEA method is the same in versions 2.0.4 and 2.0.6However, GSEA 2.0.4 cannot access the MSigDB gene sets directly from the Broad site. To use an MSigDB collection with GSEA 2.0.4, first download the collection from our [http://www.broadinstitute.org/gsea/downloads.jsp Downloads] page, and then direct GSEA to use this local copy. To run GSEA 2.0.4:<br />
+
<p class="MsoListContinue">Yes. This is likely due to recent updates by Oracle, Microsoft, and browser vendors changing the version of Java on your computer. See [[Windows_Launching_Issues|Windows Launching Issues]] for some possible solutions.</p>
 +
 
 +
<h4>GSEA gives me an error message that it is unable to access CHIP or GMT files on the Broad site. How can I fix this?</h4>
 +
<p class="MsoListContinue">Many IT organizations block the use of FTP of their networks, making it impossible to reach these filesWe recommend downloading the files from our website (available either individually or as full ZIP bundles) and then bringing them into GSEA via the Load Data screen.  Note that you will need to look for the local file options in the Run GSEA file choosers.
 
</p>
 
</p>
<ol>
 
    <li>Download the GSEA 2.0.4 gsea2.jar file: [http://www.broadinstitute.org/gsea/msigdb/download_file.jsp?filePath=/software/gsea2.jar gsea2.jar]<br />
 
    </li>
 
    <li>Use the following command line to run GSEA:<br />
 
    java -Xmx512m -jar gsea2.jar</li>
 
</ol>
 
<p class="MsoListContinue">Be sure to run the Java command from the folder that contains the gsea2.jar file or specify the full path to the .jar file.</p>
 
  
<h4>What version of R do I need for GSEA software?</h4>
 
<p class="MsoListContinue"><span style="">&nbsp;</span>Version 1.9 or later.</p>
 
 
<h4>How do I add GSEA to my microarray analysis pipeline?</h4>
 
<h4>How do I add GSEA to my microarray analysis pipeline?</h4>
 
<p>If you are using GenePattern pipelines ([http://www.GenePattern.org/ http://www.GenePattern.org/]), GSEA is available as a GenePattern analysis module.<br />
 
<p>If you are using GenePattern pipelines ([http://www.GenePattern.org/ http://www.GenePattern.org/]), GSEA is available as a GenePattern analysis module.<br />
 
</p>
 
</p>
<p>If you are implementing your own microarray analysis pipeline, GSEA can be run from the command line. Use full file specifications and the <span style="font-family: courier new;">-Dhome</span> parameter to ensure that you are reading data from and writing data to the desired locations. For more information, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Running_Command_Line Running GSEA from the Command Line] in the <span style="font-style: italic;">GSEA User Guide</span>.</p>
+
<p>If you are implementing your own microarray analysis pipeline, GSEA can be run from the command line. Use full file specifications to ensure that you are reading data from and writing data to the desired locations. For more information, see [http://software.broadinstitute.org/cancer/software/gsea/wiki/index.php/FAQ#How_do_I_run_GSEA_from_the_command_line.3F the FAQ item above].</p>
 
<h4>Do I have to be connected to the internet to run GSEA software?</h4>
 
<h4>Do I have to be connected to the internet to run GSEA software?</h4>
<p class="MsoListBullet">No. If you download the .jar file, you can use most functions in GSEA without being connected to the internet; for example, you can load files, run analyses, and review analysis results. However:<br />
+
<p class="MsoListBullet">No. If you download the GSEA desktop application .jar file, you can use most functions in GSEA without being connected to the internet; for example, you can load files, run analyses, and review analysis results. However:<br />
 
</p>
 
</p>
 
<ul>
 
<ul>
Line 227: Line 245:
 
</ul>
 
</ul>
 
<p class="MsoListBullet">When working offline, clear the menu item <span style="font-style: italic;">Option&gt;Connect over the internet.&nbsp; </span>By default, this item is selected and the <em>Chip platform(s)</em> and <em><span style="font-family: Arial;">Gene sets database</span></em> parameters display data files available from the Broad ftp site. Clearing the menu item disables this feature and avoids any time-consuming attempt to connect to the internet.</p>
 
<p class="MsoListBullet">When working offline, clear the menu item <span style="font-style: italic;">Option&gt;Connect over the internet.&nbsp; </span>By default, this item is selected and the <em>Chip platform(s)</em> and <em><span style="font-family: Arial;">Gene sets database</span></em> parameters display data files available from the Broad ftp site. Clearing the menu item disables this feature and avoids any time-consuming attempt to connect to the internet.</p>
<h4>What is the difference between GSEA, GSEA-P, and GSEA-R?</h4>
 
<p class="MsoListContinue">GSEA refers to either the gene set enrichment analysis or the GSEA software. GSEA-P refers to the GSEA Java desktop software. GSEA-R refers to the R implementation of the software.<br /></p>
 
<p class="MsoListContinue">We strongly recommend using GSEA-P for standard analysis of microarray data. <br/>The java implementation of  GSEA  does not require any programming experience, includes many additional features not present in GSEA-R, and comes with tutorial and extended documentation.</p>
 
<p class="MsoListContinue">We do not recommend GSEA-R for standard analysis of microarray data.<br/>This is because the R implementation of GSEA is closer to a working prototype than a finished software product. It is intended for users who want to tweak the GSEA algorithm rather than run routine GSEA analysis.
 
We assume that such users not only have a very good command of R but are also familiar with GSEA algorithm to the extent that the code itself is transparent enough, and thus the documentation is minimal. Also consistent with this view, the R  implementation offers minimal features, leaving it up to the user to add them.</p>
 
  
 
<h4>How do I create the input files for GSEA in R?</h4>
 
<h4>How do I create the input files for GSEA in R?</h4>
 
<p class="MsoListContinue">The GSEA R code uses the gct, cls and gmt file formats for input. For more information, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Preparing_Data_Files Preparing Data Files] in the <em style="">GSEA User Guide</em>.</p>
 
<p class="MsoListContinue">The GSEA R code uses the gct, cls and gmt file formats for input. For more information, see [http://www.broadinstitute.org/gsea/doc/GSEAUserGuideFrame.html?Preparing_Data_Files Preparing Data Files] in the <em style="">GSEA User Guide</em>.</p>
<h4>Does GSEA have a programmatic API? What languages are supported?</h4>
 
<p class="MsoListContinue">The Broad Institute provides R and Java APIs on the [http://www.broadinstitute.org/gsea/software/software_index.html Downloads] page.<br />
 
<br />
 
<strong> John Aach </strong>(Department of Genetics, Harvard Medical School) implemented a simplified version of the GSEA algorithm in <strong>MATLAB</strong><br />
 
as part of the paper [http://www.nature.com/msb/journal/v2/n1/synopsis/msb4100087.html Global gene expression of Prochlorococcus ecotypes in response to changes in nitrogen availability]. Aach notes that the MATLAB code supports only that portion of the GSEA algorithm required for the paper: it processes a particular file format, its significance calculations are performed by shuffling genes only and not phenotypes, and it does not include multiple hypothesis corrections for different gene sets. <br />
 
</p>
 
<p class="MsoListContinue">For more information, please visit&nbsp; [http://arep.med.harvard.edu/N-Regulation/Tolonen2006/GSEA/index.html John Aach'sGSEA ] webapge<br />
 
</p>
 

Latest revision as of 19:05, 12 November 2021

GSEA Home | Downloads | Molecular Signatures Database | Documentation | Contact

Contents

GSEA Algorithm

What is the difference between GSEA and an overlap statistic (hypergeometric) analysis tool?

An overlap statistic analysis tool typically uses a threshold to define genes as members at the top or bottom of a ranked list of genes.  In contrast GSEA uses the list rank information without using a threshold. The introduction to the GSEA 2005 PNAS paper discusses the limitations of the former approach and how GSEA addresses them.

Why does GSEA use the Kolmogorov-Smirnov statistic rather than the Mann-Whitney test?

The Kolmogorov-Smirnov statistic is slightly more suitable for less coherent data because it takes relatively fewer significant items to score well. The GSEA 2005 PNAS paper discusses the use of this statistic in detail (see the section titled Adjusting for Variation in Gene Set Size in the supplemental information).

How does GSEA rank the genes in my dataset?

By default, GSEA uses the signal-to-noise metric to rank the genes. Optionally, use the Metric for ranking genes parameter to select the ranking metric that you want GSEA to use.  For more information, see the Metric for ranking genes parameter on the Run GSEA Page in the GSEA User Guide.

Can I use GSEA to analyze my own ranked list of genes?

Yes. Use the GseaPreranked analysis to run the gene set enrichment analysis against your own ranked list of genes. For more information, see GSEAPreranked Page in the GSEA User Guide.

Can I use GSEA to compare two datasets?

Yes. Create a gene set that contains the top genes from the first dataset and use GSEA to analyze that gene set against the second dataset. Similarly, create a gene set that contains the top genes from the second dataset and use GSEA to analyze that gene set against the first dataset. For example, you might analyze the top 100 genes from each dataset.

Can I use GSEA to analyze a dataset that contains a single sample?

Yes.  However, GSEA has no way of ranking the genes in such a dataset. Therefore, you must rank the genes and then use GSEA to analyze the ranked list of genes. For more information, see the GSEA Preranked Page in the GSEA User Guide.

Can I use GSEA to analyze paired samples?

No. GSEA software does not provide paired-sample analysis. If you create a ranked list of genes by running a paired-sample marker analysis outside of GSEA, you can use GSEA to analyze that ranked list of genes. For more information about analyzing your own ranked lists of genes, see the GSEA Preranked Page in the GSEA User Guide.

Can I use GSEA to analyze time series data?

Yes. The phenotype labels (.cls) file defines the experimental phenotypes and associates each sample in your dataset with one of those phenotypes. To analyze time course data, use a continuous phenotype label. For more information, see Phenotype Labels in the GSEA User Guide. When you run the GSEA analysis, select Pearson in the Metric for ranking genes parameter. This is the only metric that can be used with time series data. For more information about the metrics used for ranking genes, see Metrics for Ranking Genes in the GSEA User Guide.

Can I use GSEA to find pathways that correlate to the expression of my favorite gene?

Yes. In your phenotype file, create a continuous phenotype where the expression profile is that of your favorite gene.
You can have GSEA create the necessary phenotype for you: on the Run GSEA page, click the ... button next to the Phenotype labels parameter; when GSEA prompts you to select a phenotype, click the Use a gene as the phenotype button to have GSEA create a continuous phenotype for your gene. For more information, see the Phenotype labels parameter on the Run GSEA Page in the GSEA User Guide.

Can I use GSEA with gene sets that have both up- and down-regulated genes?

The GSEA software does not yet support this, but you can use the enrichment statistic with gene sets that include both up- and down-regulated genes. For one approach, see Lamb, et al 2006.

How do I cite GSEA?

To cite GSEA, please reference Subramanian, Tamayo, et al. 2005 Proc Natl Acad Sci U S A 102(43):15545-50.

To cite your use of the Molecular Signatures Database (MSigDB), please reference Liberzon et al. 2011 Bioinformatics 27(12):1739-40 and also the source for the gene set as listed on the gene set page.

Can I use GSEA to analyze SNP, SAGE, ChIP-Seq or RNA-Seq data?

For detailed information on using RNA-seq data sets with GSEA, please see this help page.

For other data types, it is generally recommended to use GSEA-Preranked, where the features being analyzed have been quantitatively ranked in order of most (largest value) to least (smallest value) "of interest"

If the exact magnitude of the rank metric is not directly biologically meaningful select "classic" for your enrichment score (thus, not weighting each gene's contribution to the enrichment score by the value of its ranking metric).

Please note that if you choose to use any of the gene sets available from MSigDB in your analysis, you need to make sure that the features listed in your RNK file are genes, and the genes are identified by their HUGO gene symbols. All gene symbols listed in the RNK file must be unique, and we recommend the values of the ranking metrics be unique.

GSEA Data Files

How do I create an expression dataset file? What types of expression data can I analyze?

GSEA requires that expression data be in a RES, GCT, PCL, or TXT file. All four file formats are tab-delimited text files. For details of each file format, see Data Formats.

GenePattern provides several modules for converting expression data into gct and/or res files:

  • ExpressionFileCreator converts raw expression data from Affymetrix CEL files.

  • GEOImporter and caArrayImportViewer create a GCT file based on expression data extracted from the GEO or caArray microarray expression data repository, respectively.

  • MAGEImportViewer module converts MAGE-ML format data. MAGE-ML is the standard format for storing both Affymetrix and cDNA microarray data at the ArrayExpress repository.

To use expression data stored in any other format (such as cDNA microarray data), first convert the data into a tab-delimited text file that contains expression measurements with genes as rows and samples as columns and then modify that text file to comply with the gct file format requirements as described in Expression Datasets in the GSEA User Guide

If you are using two-color ratio data, see also cDNA Microarray Data.

Parsing Errors: If you see the following parsing error when you load your data file, check the file extension:
There were errors: ERRORS #:1Parsing trouble…


The file extension of the expression dataset file identifies the format of the file. If a gct, res, or pcl file has a .txt file extension, you will see the parsing error when you load the file into GSEA. Check that the file extension matches the file format. Note that some operating systems (such as Windows), can be configured to hide known file extensions. If your operating system is configured to hide known extensions, a file named test.gct.txt will be listed as test.gct. Look at the file type of the file: it should be GCT (or RES or PCL), not Text Document.

How do I filter or pre-process my dataset for GSEA?

How you filter or pre-process your data depends on your study. Here are a few guidelines to consider:

  • Probe identifiers versus gene identifiers. Typically, your dataset contains the probe identifiers native to your microarray platform DNA chip. GSEA can analyze the probe identifiers or collapse each probe set to a gene vector, where the gene is identified by gene symbol. Collapsing the probe sets prevents multiple probes per gene from inflating the enrichment scores and facilitates the biological interpretation of analysis results.
  • AP call filters.  You can run GSEA on filtered or unfiltered data. Typically, the GSEA team runs the analysis on unfiltered data. One suggested approach is to run  GSEA on the unfiltered data. If the results seem dominated by gene sets will poorly expressed genes, you might gain insight into what thresholds to use for the call filters.
  • Expression values. The GSEA algorithm examines the differences in expression values rather than the values themselves. For example, you might have natural scale data or logged expression levels; you might have Affymetrix data or two-color ratio data.<a name="_Toc120959112"></a> As in most data analysis methodologies, the same expression data represented in different formats may generate different analysis results. The differences are expected. GSEA cannot determine which results are "correct."<a name="_Toc120959112"></a>

For more information, see Preparing Data Files in the GSEA User Guide.

Should I use natural or log scale data for GSEA?

We recommend using natural scale data. We used it when we calibrated the GSEA method and it seems to work well in general cases.

Traditional modeling techniques, such as clustering, often benefit from data preprocessing. For example, one might filter expression data to remove genes that have low variance across the dataset and/or log transform the data to make the distribution more symmetric. The GSEA algorithm does not benefit from such preprocessing of the data.

How many samples do I need for GSEA?

This depends on your specific problem and data characteristics; however, as a rule of thumb, you typically want to analyze at least ten samples.

If you have technical replicates, you generally want to remove them by averaging or some other data reduction technique. For example, assume you have five tumor samples and five control samples each run three times (three replicate columns) for a total of 30 data columns. You would average the three replicate columns for each sample and create a dataset containing 10 data columns (five tumor and five control).

How do I create a phenotype label file? What types of experiments can I analyze?

GSEA can be used to analyze experiments of any type (including time-series, three or more classes, and so on). The phenotype labels (cls) ASCII file defines the experimental phenotypes and associates each sample in your dataset with one of those phenotypes. The cls file is an ASCII tab-delimited file, which you can easily create using a text editor. For more information, see Preparing Data Files in the GSEA User Guide.

What gene sets are available? Can I create my own gene sets?

You can use the gene sets in the Molecular Signature Database (MSigDB) or create your own. For more information about the MSigDB gene sets, see the MSigDB page of this web site. For more information about creating gene sets or using gene sets with GSEA, see Preparing Data Files in the GSEA User Guide.

How many genes should there be in a gene set?

GSEA automatically adjusts the enrichment statistics to account for different gene set sizes, as described in the Supplemental Information for the GSEA 2005 PNAS paper.

Can GSEA analyze a gene set that contains duplicate genes? duplicate gene sets?

Duplicate genes in a gene set and duplicate gene sets both effect GSEA results. GSEA automatically removes duplicate genes from each gene set, but does not check for duplicate gene sets. For more information, see Gene Sets in the GSEA User Guide.

Can GSEA analyze a gene set that contains genes that are not in my expression dataset?

The gene set enrichment analysis automatically restricts the gene sets to the genes in the expression dataset. The analysis report lists the gene sets and the number of genes that were included and excluded from the analysis.

What array platforms and organism species does GSEA support?

GSEA works on any data, as long as the gene identifiers in your expression data match those in the gene sets file.

Typically, GSEA uses gene sets from MSigDB. All gene sets in MSigDB consist of human gene symbols. GSEA has build-in tools for conversion between a variety of other gene identifiers to human gene symbols by means of specially formatted CHIP files. The CHIP files provide the mapping between gene identifiers in your expression data and gene identifiers in the gene sets. Specifically, our CHIP files provide the mappings from all kinds of different platforms (e.g., mouse Affymetrix probe set IDs, human Affymetrix probe set IDs, etc.) to human gene symbols.

If your data was generated from non-human samples, then you need to decide whether using MSigDB meets your needs. The options are:

  1. The non-human species serves as a model to study conditions relevant for human biology. In this case, you want gene sets that are conserved between humans and your model organism. MSigDB is then the right choice and you will only need to provide the appropriate CHIP file for the analysis.
  2. The non-human species is the subject of your research, and you have no plans to compare it to human gene sets. In this case, you can still use MSigDB is your organism is among the sources of some of MSigDB gene sets (e.g., mouse or rat) and you will only need to provide the appropriate CHIP file for the analysis.
  3. The non-human species is the subject of your research and you don't want to use MSigDB gene sets for other reasons. In this case, you have to provide your own database of gene sets as a GMT or GMX file. The file formats are described here. Of course, you still have to make sure that the gene identifiers in your your data match those in your gene sets database. If the identifiers don't match each other, then you have to also provide a CHIP file with the appropriate mappings. The CHIP file format is described here.

To see what CHIP files are available in our distribution (note: our CHIP files provide mappings to human gene symbols only): start GSEA desktop application and click [...] at "Chip platform(s)" on "Run GSEA" page.

If your platform is not in this list, you have the following options:

  1. Create your own CHIP file to map your platform specific gene identifiers to human gene symbols and then use your CHIP file to collapse dataset in GSEA. The CHIP file format is described here.
  2. Convert your platform identifiers to human gene symbols outside GSEA, then run GSEA with 'Collapse dataset' = FALSE.

    Make sure that gene symbols in the collapsed dataset appear only once. Simply replacing the identifiers with human gene symbols usually is not sufficient because some of the identifiers can correspond to the same human gene symbols, resulting in duplicate rows with different expression values. In this case, GSEA will arbitrarily pick one of the rows with the same gene symbols for the analysis, which we do not recommend.

Can GSEA analyze miRNA expression data?

The only way for GSEA to analyze expression data with miRNA identifiers is to provide gene sets made of matching miRNA identifiers. This is not possible with MSigDB gene sets, which consist predominantly of protein coding genes in the form of human gene symbols.

GSEA Results

Where are the GSEA statistics (ES, NES, FDR, FWER, nominal p value) described?

For brief descriptions of the statistics that appear in the GSEA analysis report, see Interpreting GSEA in the GSEA User Guide. The GSEA 2005 PNAS paper also describes each of these statistics:

    for FDR and nominal p value, see the section titled Appendix: Mathematical Description of Methods;
    for FWER, see the section titled FWER in the Supplemental Information.

Why does GSEA use a false discovery rate (FDR) of 0.25 rather than the more classic 0.05?

An FDR of 25% indicates that the result is likely to be valid 3 out of 4 times, which is reasonable in the setting of exploratory discovery where one is interested in finding candidate hypothesis to be further validated as a results of future research. Given the lack of coherence in most expression datasets and the relatively small number of gene sets being analyzed, using a more stringent FDR cutoff may lead you to overlook potentially significant results. For more information about gene set enrichment analysis results, see Interpreting GSEA in the GSEA User Guide.

Why does GSEA give me significant results with gene set (tag) permutation, but not with phenotype permutation?

Phenotype permutation generally provides a more stringent assessment of significance and produces fewer false positives. Which permutation type you should use depends on the number of samples that you are analyzing. For more information, see the description of the Permutation type parameter on the Run GSEA Page in the GSEA User Guide.

How can I display details for more than the top 20 gene sets?

By default, the GSEA analysis report generates a Details link, which provides summary plots and detailed analysis results, for the top 20 gene sets in each phenotype. To generate the Details link for additional gene sets, modify the Plot graphs for the top sets of each phenotype parameter on the Run GSEA Page.

What should I do if I have no significant gene sets or too many significant gene sets?

The number of enriched gene sets depends on the structure of the data and the problem space. In general, one would expect to see at least a few gene sets enriched for a typical morphological or tissue-specific phenotype. If no enriched gene sets or a very large number of enriched gene sets pass the FDR threshold, first check that your gene sets and expression dataset use the same array format (see Consistent Feature Identifiers Across Data Files)  and that you have used the appropriate permutation type and number of permutations (see the Run GSEA Page). If you find no issues, consider the following:

  • No enriched gene sets of significance may indicate that, in fact, no gene sets are enriched. It may also be that you are analyzing too few samples, the biological signal in question is subtle, or the gene sets that you are analyzing do not represent the biology in question very well. You may still want to look at the top ranked gene sets, keeping in mind that these results provide weak evidence for potentially interesting hypotheses. You might also want to consider analyzing other gene sets or, if possible, additional samples.
  • Too many enriched gene sets of significance may indicate that, in fact, many gene sets are enriched between phenotypes. Perhaps the gene sets represent the same biological signal. You can check for this by looking for overlap in the leading-edge subsets within the gene sets Running a Leading Edge Analysis). Or, you might be seeing significant differences between the phenotypes due to technical artifacts, such as samples being run in different labs, by different operators, or against different arrays. As with too few enriched gene sets, you may still want to look at the top ranked gene sets, keeping in mind that these results provide potentially biased evidence for interesting hypotheses. You might also want to consider analyzing other gene sets or, if possible, additional samples.

For more information, see Interpreting GSEA in the GSEA User Guide.

What does it mean for a  gene set to have a nominal p value of zero?

A reported p value of zero (0.0) indicates an actual p-value of less than 1/number-of-permutations. For a more accurate p value, increase the number of permutations performed by the analysis. For more information about gene set enrichment analysis results, see Interpreting GSEA in the GSEA User Guide.

What does it mean for a gene set to have a small nominal p value (p<0.025), but a high FDR value (FDR=1)?

The nominal p value estimates the significance of the observed enrichment score for a single gene set. However, when you are evaluating multiple gene sets, you must correct for multiple hypothesis testing. The FDR is the estimated probability that a gene set with a given enrichment score (normalized for gene set size) represents a false positive finding.

Generally, when your top gene sets have small nominal p values and high FDRs, it is because they are not as significant when compared with other gene sets in the empirical null distribution. This could be because you do not have enough samples, the biological signal is subtle, or the gene sets do not represent the biology in question very well. Also, the FDR is based on all gene sets; if only one of many gene sets is enriched, that gene set is likely to have a high FDR.

For more information, see Interpreting GSEA in the GSEA User Guide.

What is the difference between the weighted statistic and the classic statistic? Which should I use?

See the description of the Enrichment statistic parameter on the Run GSEA Page in the GSEA User Guide.

Why are my results different from yours when I analyze the example datasets using GSEA?

You are using a different random number generator (for sample permutation) and different seeds for that random number generator, so the resulting numbers are different. However, these differences should be VERY SMALL and the IDENTITY of the top (up or down) gene sets should be pretty much the same. The FDRs might be at most a few percent different from run to run. To get exactly the same result from run to run, specify the random number seed (its a parameter in the gsea software).

Why do some of the example datasets contain negative expression values?

Because in older releases of Affymetrix gene chips expression values were trimmed averages over match and mismatched probes. If the mismatch probes were higher a negative number results.

Why comparing phenotypes A vs B gives different results from B vs A?

This is because these two comparisons produce different ranked lists of genes. You might expect similar results only if the ranked lists would be perfectly symmetrical, and this usually does not happen.

What does it mean for a gene set to have NES and nominal p-values of NaN (also shown as blanks)?

When adjusting for variation in gene set size, we normalize permuted ES(S, pi) and the observed ES(S) for a given S, separately rescaling the positive and negative scores by dividing by the mean of the ES(S, pi) to yield NES(S, pi) and NES(S). However, when the scores of the corresponding sign are absent, the mean ES(S, pi) = 0, and the division by zero will result in NaN values both for the NES(S, pi) and NES(S) as well as for the nominal p-values that follow from these calculations. The easiest way to overcome this issue would be to increase number of permutations. If this does not help, we recommend further exploring reasons for this bias. For example, it could be caused by a large difference in the number of samples of each phenotype class. For further details, please consult the GSEA PNAS 2005 paper, sections "Multiple Hypothesis Testing" in the "Mathematical Description of Methods" and the "Supporting Text" Appendix.

Why didn't my gene set display an enrichment plot even though it is in the top hits?

Sometimes when running GSEA with metrics other than signal-to-noise, or t-test, some plots may fail to render resulting in a Java error message being printed in red text in the place of the plot on the results page. This error is typically caused by GSEA encountering a divide-by-zero in the internal ranking metric computation, or an overflow where the result of the calculation between phenotypes returns an "infinity". The presence of infinite values in the resulting internal ranked list can be confirmed by navigating to the GSEA results directory for the given run, opening the "edb" folder, and then inspecting the .rnk file in this directory for "Inf", "NaN" or similar strings. It might be possible to resolve these issues by adding a small pseudocount to the dataset. It should be noted that any such selected value here is arbitrary and we do not advise the selection of any specific value, consult your local bioinformaticians for specific guidance. This error may also occur in GSEA Preranked mode, in which case these non-finite values would have been present in the supplied preranked list and should be resolved though the original quantification pipeline.

MSigDB Gene Sets

What is MSigDB?

MSigDB, the Molecular Signature Database, contains curated gene sets for use with the gene set enrichment analysis. The GSEA team has begun the critical work of populating the MSigDb with curated gene sets. Increasing the number of gene sets increases the value of this resource; therefore, the GSEA team appreciates gene set contributions and encourages users to submit their gene sets to genesets@broadinstitute.org. For information about exporting gene sets from the MSigDB, see Gene Sets in the GSEA User Guide.

What is the difference between gene sets in MSigDB and GO/BioCarta/GenMAPP?

MSigDB contains gene sets formatted for use with GSEA. MSigDB places emphasis on a genomic, unbiased approach to the definition of gene sets; therefore, an important component of MSigDB is the collection of gene sets from published expression profiles. Unlike gene sets curated from prior knowledge (such as, GO, BioCarta, and so on), experimental sets provide an unbiased readout of a biological state; experimental sets from microarray experiments reflect purely transcriptional events.

Does MSigDB include pathway diagrams?

No. However, some gene set pages in canonical pathways include external links to the original sources which can have the diagrams.

Does MSigDB include GO gene sets?

The C5 collection in MSigDB v.2.5 and later is made entirely of GO gene sets. In addition, the C2 (curated) category of gene sets in MSigDB v2.5 or earlier contains 17 GO gene sets. For a complete description of these gene sets, see the  MSigDB page.

Why do some MSigDB gene sets have the same gene represented multiple times?

The gene sets reflect the information in the original source and no attempt to modify the definition of a gene set is done (except for eliminating obvious gene duplications).  The gene sets defined in terms of gene symbols eliminate the duplication produced by multiple probes representing the same gene.

How do I use your gene sets to analyze data from my favorite array platform?

GSEA provides a utility, Chip2Chip, which translates the gene identifiers from gene symbols to the probe identifiers of your array platform. For more information, see Chip2Chip in the GSEA User Guide.

How do I convert your gene sets from HUGO gene symbols to ENTREZ gene identifiers?

Starting with v3.0 MSigDB, there is no need to do this: we provide additional GMT files using Entrez Gene IDs as gene identifiers for all our gene sets.

How do I find out more information about a particular MSigDB gene set?

Each gene set in the MSigDB (Molecular Signature Database) is fully described by a gene set page. From this web site, use the 
MSigDB page to find a gene set. Click the gene set name to display its gene set page. From within the GSEA application, use the Browse MSigDB page to browse gene sets and display gene set pages. Alternatively, a Google search on the gene set name also displays a link to the gene set page.

Can I use the MSigDB gene sets without using GSEA?

Yes. You can view and download the gene sets from the MSigDB page.


What does /// in a gene symbol mean?

This symbol indicates ambiguous mapping according to the Affymentrix conventions and serves as a field separator when a probe set id corresponds to several gene symbols. /// may appear in some gene sets curated form Affymetrix (NetAffx) annotation data. GSEA ignores such genes.

How can I view/access gene sets from the v2.5 or v3.0 release of MSigDB?

The MSigDB v2.5 files are archived and are still available for download on the Downloads page. Scroll down to the bottom of the page to the 'Archived releases' section.

You can also view these archived sets using the MSigDB Browser in the GSEA desktop application (refer to the GSEA 2.0.8 Release Notes or the User Guide for further instructions).

Should I run GSEA on one or multiple MSigDB collections?

We recommend running GSEA in individual collections, or even sub-collections of gene sets rather that on the entire MSigDB. Using individual collections saves time and produces more optimistic FDR q-values because GSEA has fewer gene sets to test. In addition, the results will be easier to interpret as they will focus your attention on particular kind of gene sets. We have grouped gene sets according to their derivation into collections precisely for these reasons, and provide general suggestions for their usage here: MSigDB collections.

GSEA Software

What is the difference between GSEA, GSEA-P, and GSEA-R?

GSEA refers to either the gene set enrichment analysis or the GSEA software. GSEA-P refers to the GSEA Java desktop software. GSEA-R refers to the R implementation of the software.

We strongly recommend using the Java desktop GSEA software for standard analysis of microarray data. The Java implementation of GSEA does not require any programming experience, includes many additional features not present in GSEA-R, and comes with tutorial and extended documentation.

The R implementation of GSEA is closer to a working prototype than a finished software product. We make it available for users who want to tweak the GSEA algorithm rather than run routine GSEA analysis. We assume that such users not only have a very good command of R but are also familiar with GSEA algorithm. Also consistent with this view, the R implementation offers minimal features, leaving it up to the user to add them.

How do I increase the amount of memory available to GSEA?

From the GSEA website, the GSEA desktop application can be launched with 1, 2, 4, or 8 GB of memory. Use the dropdown menu above the launch button to specify the amount. Note that 32-bit Java will not support greater than 2 GB.

When running GSEA from one of our downloadable bundles, you can increase the memory specification by editing the launcher file. This is gsea.bat on Windows, gsea.sh or gsea-hidpi.sh on Linux, or gsea.command on Mac. Modify the -Xmx setting as desired; for example, to use an 8 GB memory configuration this could be set to -Xmx8g.

The same is true of the gsea-cli.sh and gsea-cli.bat scripts for command-line usage. Note that it's also possible to edit the JNLP files in a similar way to create an even larger Java Web Start memory configuration.

For users of the Mac.app it is not easily possible to modify the memory configuration at this time. This is a known issue that we will aim to address in a future release. If a higher memory configuration is absolutely required, we suggest using the command-line bundle with your own (separate) Java 11 installation. The gsea.command script is still available for launching the GUI from this bundle.

How do I run GSEA from the command line?

As of GSEA 4.0.0, there is a dedicated bundle available from our Downloads page for command-line usage; please refer to the included README file for an explanation of the command-line launcher script. Note that a separate Java 11 installation is required.

See the Command feature of the various GSEA Desktop GUI screens for example constructions of command-lines. This is by far the easiest way to understand the various flags and options.

The Linux bundle contains exactly the same launcher script and README along with an embedded OpenJDK 11 JVM, so there's no need for a separate download for users on that platform.

What version of Java do I need for the GSEA desktop software?

As of GSEA 4.0.0, the various platform-specific bundles (for Windows, Mac, and Linux) include an embedded OpenJDK 11 JVM, meaning a separate Java installation is no longer required for most users.

Java 8 is required for use of the Java Web Start JNLP launchers (OpenJDK 8 is fine).

I can't launch GSEA from the website on Windows. This used to work; did something change?

Yes. This is likely due to recent updates by Oracle, Microsoft, and browser vendors changing the version of Java on your computer. See Windows Launching Issues for some possible solutions.

GSEA gives me an error message that it is unable to access CHIP or GMT files on the Broad site. How can I fix this?

Many IT organizations block the use of FTP of their networks, making it impossible to reach these files. We recommend downloading the files from our website (available either individually or as full ZIP bundles) and then bringing them into GSEA via the Load Data screen. Note that you will need to look for the local file options in the Run GSEA file choosers.

How do I add GSEA to my microarray analysis pipeline?

If you are using GenePattern pipelines (http://www.GenePattern.org/), GSEA is available as a GenePattern analysis module.

If you are implementing your own microarray analysis pipeline, GSEA can be run from the command line. Use full file specifications to ensure that you are reading data from and writing data to the desired locations. For more information, see the FAQ item above.

Do I have to be connected to the internet to run GSEA software?

No. If you download the GSEA desktop application .jar file, you can use most functions in GSEA without being connected to the internet; for example, you can load files, run analyses, and review analysis results. However:

  • The Chip platform(s) and Gene sets database parameters (on pages such as Run GSEA) display data files available from the Broad ftp site; these data files are not available when you are working offline. Be sure to download the chip files and gene set files that you need before disconnecting from the internet.
  • The GSEA documentation and help files are on the GSEA web site; they are not available when you are working offline.

When working offline, clear the menu item Option>Connect over the internet.  By default, this item is selected and the Chip platform(s) and Gene sets database parameters display data files available from the Broad ftp site. Clearing the menu item disables this feature and avoids any time-consuming attempt to connect to the internet.

How do I create the input files for GSEA in R?

The GSEA R code uses the gct, cls and gmt file formats for input. For more information, see Preparing Data Files in the GSEA User Guide.