GO-elite ReadMe File

Section 1) Introduction

Description
GO-Elite is a software tool designed to identify a minimal non-redundant set of Gene Ontology (GO) biological terms or pathways to describe a particular set of genes.  Originally designed to work with pre-built GO and pathway output results from the programs GenMAPP and MAPPFinder (http://www.genmapp.org), GO-Elite is now able to generate results from user gene lists independent of any other software. GO-Elite version 1 Beta is currently provided as a stand-alone application which is run using a Windows executable file (GO-Elite.exe) or as cross-platform source code in python.  To download the program and to get documentation, go to: http://www.genmapp.org/go_elite/.

The two most common use cases for GO-Elite are:

1)	Identifying biological processes to describe transcripts/peptides regulated from a microarray/proteomic experiment 
2)	Look for common pathways corresponding to families of genes or gene targets (e.g. over-representation of pathways for transcription factor or microRNA targets).  

More information and updated documentation, including bug fixes can be found at our Google Groups page at: http://groups.google.com/group/go-elite

Installation
Extract the compress zip archive to any desired directory on your computer.

Requirements
Included in the supplied zip archive are an executable program, source code and a white paper describing the methodology.  The executable program will run on any Windows machine, however, to run on different operating systems you will need to have python installed, which is typically pre-installed with Linux or an later Mac operating systems.

Updating GeneOntology Files (OBO)
The GeneOntology tree structure can be easily updated by the user by downloading files from http://www.geneontology.org.  These files can be found at: http://www.geneontology.org/GO.downloads.ontology.shtml. To update, go to this URL and download the files GO format files process, function and component to the OBO directory in the GO-Elite folder.  Replace, move or delete the previous files with the same name. To update gene information manually, see the file How_to_Make_New_Species_Databases.rtf.

Section 2) Preparing data

GO-Elite Input Files
The user is only required to provide two files: (A) input gene lists and (B) denominator list (containing all genes examined, including all input genes). Alternatively, you can supply an existing MAPPFinder file, such as a GenMAPP results file but is no longer recommended, since GO-Elite has databases that are more current or often are more up-to-date than GenMAPP.  This option also works with recently generated GO-Elite mappfinder results.

Preparing Gene Lists
When building GO and pathway associations from scratch, you need to provide an input gene list and denominator list.  The input list is a subset of the denominator list which consists of gene IDs or probesets that are highlighted from a user analysis (e.g. up and downregulated genes).  Both input and denominator lists consist of a column of gene IDs (column 1), system code for each ID (column 2 - look up in the folder Databases/source_data.txt) and any other data you may wish to summarize at the pathway level (e.g. fold change), for desired number of additional columns. Currently, GO-Elite will use only one system code per file. If the system code column is not present (only the first column is absolutely required), GO-Elite may be able to guess what type of ID system it is, but this is typically not recommended.  For the denominator file, only the first two columns are used (gene IDs and system code).

Once these files are generated:
1)	Move or copy your gene list(s) (Ensembl, EntrezGene or Affymetrix IDs) to the folder named input>GenesToQuery>species, under the appropriate species directory in the folder named input.  If you have more than one type of denominator (e.g. two types of Affymetrix arrays) place a unique number before the name of each input file (e.g. genelistA.txt -> 1.genelistA.txt) and denominator file that matches it.  This will instruct GO-Elite on how to match up your gene input set to which proper denominator set.
2)	In the same directory you uploaded your gene input list(s), there is a folder named DenominatorGenes. For GO-Elite to calculate MAPPFinder GO-results, you will need to supply a list of all genes or probe sets from the microarray the data was collected from (or equivalent master list).  All of the genes in your gene list to query should be a subset of this list.  GO-Elite will complain when running if identifiers found in your input gene list don’t match to your denominator and ask you to fix the problem before proceeding.

Section 3) Running GO-Elite

Using GO-Elite on Different Operating Systems
To run GO elite, follow the appropriate instructions depending on if you are starting with gene lists or existing GO or pathway results.  

o	PC – Installation of python is not required, simply double click on the only exe file, named “GO-elite.exe”. This will open a command line window, requiring the user to enter the option number desired.
o	Mac – Installation of python is required, but is typically present with OS X or greater. To run, open a terminal window (e.g. Applications/Utilities/Terminal) and change directories to the GO-Elite extracted folder. Once in this directory typing “python GO-elite.py” in the terminal window will begin to run GO-Elite (you will see the below prompt).
o	Linux – Installation of python is required, but is typically present with most Linux installations or can be installed via Yum update. To run, open a terminal window and go to the GO-Elite main folder (e.g. cd GO-Elite_118beta). Once in this directory typing “python GO-elite.py” in the terminal window will begin to run GO-Elite (you will see the below prompt).

Analysis Options

Although GO-elite is a command line application, it is intended to be run by novices and experts alike. When opened the user is presented with three options:

1) Run GO-Elite on pre-run MAPPFinder results
2) Calculate MAPPFinder results from input gene lists prior to GO-Elite
3) Build new gene-association files (must replace existing files when finished)

Option 2 is used when starting with an input and denominator gene list, whereas option 1 is only necessary when starting with existing GO or pathway results (see GO-Elite white paper or manuscript), which can include previously GO-Elite outputs. Option 3 is used if you have a currently unsupported species and wish to quickly build new databases. This option can be very easy, when dealing with a species that has available Affymetrix array annotation files or is a species with GO information at NCBI (see How_to_Make_New_Species_Databases.rtf for details).

Beginning with a Gene List (de novo mappfinder analysis)

1.	By selecting option 2, GO-Elite will first perform an over-representation analysis (ORA) on your data using the mappfinder module of the program, which performs a similar statistical analysis to the MAPPFinder program in GenMAPP, with typically very fast run-times (one or a few minutes) and Benjamini-Hochberg false discovery rate p-values. 
2.	After selecting this option, the user will be prompted to “Choose a Primary Relational Gene Database.” This option tells GO-Elite which gene ID system to use when linking GO terms and pathways. If starting with gene IDs from Ensembl or EntrezGene, simply select the appropriate option, but if working with other gene IDs (such as Affymetrix), you have an option. Typically, EntrezGene has more genes per GO term and pathways associated and can produced slightly different results from Ensembl, but if running for the first time it is recommended you try both in separate runs.
3.	GO-Elite has further options for pruning mappfinder results (this is the Elite step), consisting of default and custom parameters. For most users, default is recommended, however, if custom is selected, the user must choose the z-score cutoffs (>1.96 roughly corresponds to a p-value<0.05), permutation p-value cutoffs (if not present this threshold is ignored and defaults to z-score only) and the type of statistical prioritization method desired. Three statistical prioritization methods are available within GO-elite; Z-score, Gene Number or Combination.  See the GO-Elite methods paper to see the description for each of these options (combination additionally weights z-score results based on the number of genes changed for each term). The user is encouraged to try different methods and compare these.
4.	Once selected, you will be prompted to select an available species.  This directs GO-Elite to a species input folder. If your species is not listed, you must follow the directions for making GO-Elite compatible with a new species (How_to_Make_New_Species_Databases.rtf). 
5.	Finally, indicate the number of permutations you want to run with mappfinder. With increased permutations, you have more statistical confidence but also much longer run-times. The default of 2000 is recommended for most analyses. 
6.	Once these options are selected GO-Elite will generate ORA statistics similar to those build by GenMAPP.  These are saved directly to the folder input/MAPPFinder into a sub-folder with the most recent time-stamp. This data is immediately and automatically used to also create pruned result files to the folder “output”, including two GO-Elite result files for each input list corresponding to GO and local associations (local is typically composed of GenMAPP pathways, but can include other pathways associations, such as Panther Pathways for mouse). A third file is a combination of all GO-Elite results built or analyzed in a single run (can include multiple input files run at once). These sets of files can include gene symbols associated with each GO term or pathway and even summarized gene expression values present with the input gene IDs.  In addition, there are gene level annotation files saved to the folder Gene_Associations in the output directory, useful for seeing which genes and input IDs are linked to each GO term along with gene annotations.  The gene ranking file provides a means to see which genes are most highly represented in which GO term or pathways.

Beginning with Existing Results
1)	Move or copy your MAPPFinder result files to the folder named input>MAPPFinder in the GO-Elite directory. If you want to run GO-Elite pruning on results not produced form GenMAPP or GO-Elite, you must reformat your data to look like MAPPFinder outut (see examples in input/MAPPFinder/ examples-move-to-MAPPFinder-dir). If from a prior GO-Elite run, these should be saved into a time-stamped folder in this directory.
2)	Open the file named GO-elite.exe (windows users) or GO-elite.py (requires installation of python). 
3)	Select option 1 at the first prompt.
4)	Select default or custom options for identifying the minimal set of GO-elite terms. If custom is selected, the user must choose the z-score cutoffs (>1.96 roughly corresponds to a p-value<0.05), permutation p-value cutoffs (if not present this threshold is ignored and defaults to z-score only) and the type of statistical prioritization method desired. Three statistical prioritization methods are available within GO-elite; Z-score, Gene Number or Combination.  See the GO-Elite methods paper to see the description for each of these options (combination additionally weights z-score results based on the number of genes changed for each term). The user is encouraged to try different methods and compare these.
5)	Once these options are selected GO-Elite will save pruned results files to the folder “output”, including two GO-Elite result files for each input list corresponding to GO and local associations (local is typically composed of GenMAPP pathways, but can include other pathways associations, such as Panther Pathways for mouse). A third file is a combination of all GO-Elite results built or analyzed in a single run (can include multiple input files run at once). These sets of files can include gene symbols associated with each GO term or pathway and even summarized gene expression values present with the input gene lists with the same prefix filename as the ORA input file in the MAPPFinder directory (e.g. genelistA-GO.txt. and genelistA.txt).  In addition, there are gene level annotation files saved to the folder Gene_Associations in the output directory, useful for seeing which genes and input IDs are linked to each GO term along with gene annotations.  The gene ranking file provides a means to see which genes are most highly represented in which GO term or pathways.