PROGRAM OVERVIEW
----------------

A program to analyze the disease-associated variants reported by GWAS
  
  The PGA program analyzes a list of input SNPs and produces a list of 
  candidate genes likely affected by a SNP in the input list. These candidate genes are 
  scored based upon the strength of their relationship to the disease on which the GWAS
  that produced the list of input SNPs was conducted.
  
SYSTEM REQUIREMENTS
-------------------  
	
	HARDWARE REQUIREMENTS
    ---------------------
  	    
  	    - Disk Space: Requires approximately 300 MB of available disk space.

  	    - RAM: RAM usage depends on the size of the gene
  	      network/GO term data and the support value determined at runtime. Large datasets (> 50 MB) with low support values may require > 4 GB RAM, while smaller data sets (~20 MB) may require < 2 GB.   

	SOFTWARE REQUIREMENTS
    ---------------------
  		
  		- Java 7 or later 

  		- VCFtools v0.1.13 or later

  		- tabix

  		- Perl Modules: List::Util, LWP::Simple, File::Spec::Functions


  	The program also requires a working internet connection.



RUNNING THE PROGRAM
-------------------
- The program must be run from the PGA directory (so must use java -cp. e.g. java -cp src edu.yu.einstein.zdzlab.pga.GWASAnalyzer)

- The package name is edu.yu.einstein.zdzlab.pga

- The main method is GWASAnalyzer.java

- If program throws an "out of memory error" run program with increased heapspace with the -Xmx option (e.g. java -Xmx4g -cp src package.GWASAnalyzer)

	ARGUMENTS
	---------

		- The user must submit a 3-letter disease code (SCZ, ALZ, etc.) as the first command line argument.
  
		- The user must submit a 3-letter 1KG reference panel population code (e.g EUR, AFR, etc.) as the second command line argument. 

  		- The user may submit the "--t" flag followed by a filepath to a list of user-defined training genes. If this argument is not submitted, a default list of training genes will be used. 
  		
  		- The user may submit the "--f" flag to indicate that predictive features for the disease in question have already been generated in a previous execution with the same
  		training genes and need not be computed again.

  		- The user may submit the "--kg" flag to indicate that candidate gene generation has already been completed in a previous execution with the same input SNPs and need not be repeated.

  		- The user may submit the "--c" flag followed by a score-cutoff (a positive number) to indicate that the user would like to incorporate custom annotation data in the process of identifying distal candidate genes. Only those regulatory elements with a score >= score-cutoff will be incorporated. The location of the custom annotation data file is described in the INPUT section.

  
INPUT
-----
	CANDIDATE GENE IDENTIFICATION
	-----------------------------
		- A BED file containing a list of input SNPs. Conventional BED format should be used
		  i.e. chromosome number, start position, end position,
		  and SNP ID. There should be no header line. 
		  LOCATION:
		  The file must be named: "query_vars.bed" and located in PGA/gwascge/input directory
		  
		- (Optional) VCF files from the 1000 Genomes Project for all 24 chromosomes.  The VCF files must contain
		  phased haplotypes (required by VCFtools for LD calculations) and be compressed by bgzip
		  (required due to space considerations). Thus, the file extensions should be .vcf.gz.
		  Each file must be named: "chr#.vcf.gz" where the # symbol should be replaced by the appropriate chromosome number (or X/Y)
		  Reference panels for different populations will be made available at (http://zdzlab.einstein.yu.edu/1/pga/download/XXX_phase3.tar), where XXX is the population code.Phase 1 files are alos available for download.
		  Different reference panels should be used depending on the population on which the GWAS was conducted. At this point, only
		  EUR, EAS, and AFR are supported.

		  IF the user chooses not to download these VCF files, the program will instead access the 1KG data available on our webserver (for the given population). This allows the user to avoid downloading large VCF files, and speeds up the portion of the program that requires this data (~15s per SNP instead of ~90s per SNP). 

		  LOCATION: 
		  The files must be located in PGA/gwascge/input/1KG/XXX, where XXX is the population code and the name of the directory when downloaded.
		  
		- (Provided) A text file containing a list of protein coding
		  genes and their chromosomal positions.
		  There should be eight tab-delimited columns: GeneSymbol, EntrezID, EnsembleID, Chr#, 
		  Start position, End position, Band, Strand, and a header row.
		  LOCATION: 
		  The file must be named:
		  "Protein_coding_genes.txt" and located in PGA/gwascge/input/VAR_process
		  
		- (Provided) A text file containing TRE data curated from the ENCODE, FANTOM5, and GTEx databases.
		  
		  
		- (Provided) A text file containing eQTL data curated from the GTEx, ENCODE, and FANTOM5 databases.

		- (Optional) A BED file containing custom annotation data. Conventional BED format should be used i.e. chromosome number, start position, end position, gene symbol, and score. There should be no header line.
		LOCATION:
		The file must be named "custom_annotate.bed" and located in PGA/gwascge/input/VAR_process

		- (Optional) Candidate disease genes and risk regions generated from a set of input SNPs so that they do not need to be recomputed.

		LOCATIONS: The file "candidate_gene_lists.txt" must be located in PGA/gwascge/output.
		The files "output_proximal_genes_id.txt", "output_distal_genes_id.txt", "output_range_after_merging.txt" must be located in PGA/gwascge/output/VAR_process.

	
	CANDIDATE GENE SCORING
    ----------------------
		- (Provided) A text file containing a list of gene IDs of known disease genes; one gene ID per line.
		  The file must be named: "XXX_training_genes.txt", where XXX represents the disease-code (e.g. SCZ, ALZ, etc.). This training gene file should have > 30 genes to ensure effective candidate gene scoring, and a training gene set containing > 50 genes is recommended.
		  
		  LOCATION:
		  The file must be located in PGA/gwascge/input.
		  
		  Alternatively, the user may submit the filepath of the training gene text file as a command line argument. The user may alter the default training gene files used by replacing the default file in the appropriate location with their own. 

		  NOTE: If the user submits a list of gene symbols instead of IDs, the file will be overwritten with equivalent gene IDs (where they exist) and a new file "training_gene_file_Sym" will be created with the original file content, where "training_gene_file" is the original name of the input file. Hybrid files (some symbols and some IDs) will NOT work.
		  
		- (Provided) A text file representing a gene
		  network for all genes. The first column
		  should represent the gene ID connected to all of its neighbors listed in succeeding tab-delimited columns. The gene IDs MUST be sorted in ascending order.

		  LOCATION:
		  The file must be located in 
		  PGA/gwascge/input/Score_process/FN and named:
		  "*active*.txt" where "*" represents any number of characters.
		  The keyword active distinguishes between input datasets the
		  user might choose to alternate between.
		  
		- (Provided) A text file containing a list of GO terms
		  associated with each known gene. The first
		  column should represent the gene ID to which the GO terms listed in succeeding tab-delimited
		  columns are associated. The GO terms MUST be sorted in
		  ascending order.

		  LOCATION:
		  The file must be located in 
		  PGA/gwascge/input/Score_process/GO and named:
		  "*active*.txt" where "*" represents any number of characters.
		  The keyword active distinguishes between input datasets the
		  user might choose to alternate between.

		- (Provided) A text file containing a list of GO term ancsetors
		  associated with each GO term. The first
		  column should represent the GO term to which the GO terms
		  ancestors listed in succeeding tab-delimited
		  columns are associated. The GO term ancestors MUST be sorted in
		  ascending order.

		  LOCATION:
		  The file must be located in 
		  PGA/gwascge/input/Score_process/GO and named:
		  "GO_myAncestors_isonly.txt".

		- (Optional) Predictive feature sets extracted from the training
		  gene set being used so that they do not need to be recomputed. 
		  
		  LOCATION:
		  Files must be located in 
		  PGA/gwascge/output/Score_process/FN (or GO). 
		  The following files must be included and appropriately named, otherwise program will not function properly:
		  "FN_background_linkedlist.txt", "FN_linkedlist.txt", "FN_set_1.txt", "FN_set_2.txt", "FN_set_3.txt", "FN_set_all.txt", "FN_background_set_all.txt",
		  "GO_expanded_background_linkedlist.txt", "GO_expanded_linkedlist.txt", "GO_set_1.txt", "GO_set_2.txt", "GO_set_3.txt", "GO_set_all.txt", "GO_background_set_all.txt".
		  
OUTPUT
------
- A large number of intermediate output files are produced within the
  PGA directory. The primary output files of interest are:
  "candidate_gene_scores_timestamp.txt", and "PGA_results_timestamp.txt" and they can be found in the gwascge directory. The timestamp format is: hour.min.sec_month-day-year.

	"candidate_gene_scores_timestamp.txt" contains candidate risk gene symbols and their scores. A gene without a symbol is not listed. Genes for which no score could be produced based on the given network/GO data are marked with "--" in the score column. At the end of the file the mean high scoring cutoff is listed, indicating the score cutoff for which every gene with a score greater than this number should be considered high scoring. The standard deviation and 95% confidence interval range are also listed. The method of obtaining this threshold is explained in the program's application note.		

	"PGA_results_timestamp.txt" contains risk regions, associated SNPs,
	and gene symbols (score). Additionally, each gene symbol may be preceded by a '*', indicating a distal gene. At the end of the file the mean high scoring cutoff is listed, indicating the score cutoff for which every gene with a score greater than this number should be considered high scoring. The standard deviation and 95% confidence interval range are also listed. The method of obtaining this threshold is explained in the program's application note.
	This file relies on the "candidate_gene_scores_timestamp.txt" file produced within the
	same hour of the same day of the same year. This could have unexpected results if multiple versions of this file were produced on the same day in the same hour and are left in the default directory for the file. Additionally, if no file within the same hour is found (possible at turn of the hour), this file uses any "candidate_gene_scores" file in the directory. Therefore, it is RECOMMENDED NOT TO LEAVE ANY "CANDIDATE_GENE_SCORES_TIMESTAMP.TXT" FILES IN THE GWASCGE DIRECTORY BETWEEN RUNS OF THE PROGRAM.

	The high scoring cutoff information for both of these files is written to a 
	"PGA_results"/"candidate_gene_scores" file produced on the SAME DAY.
	This could have unexpected results if multiple versions of these files produced on the same day are in the same directory. Additionally, if no file within the same day is found (possible at turn of the day), this file uses any "candidate_gene_scores"/"PGA_results" file in the directory. Therefore, it is RECOMMENDED NOT TO LEAVE ANY "CANDIDATE_GENE_SCORES_TIMESTAMP.TXT"/"PGA_RESULTS_TIMESTAMP.txt" FILES IN THE GWASCGE DIRECTORY BETWEEN RUNS OF THE PROGRAM.

- Intermediate files of interest for identifying candidate genes from GWAS SNPs can be found in "gwascge/output/VAR_process". The files used to identify the distal genes 
  associated with GWAS SNPs are "candidate_genes(ID)_eQTL.txt" and "TRE_candidate_genes(_id).txt" and possibly "custom_candidate_genes(_id).txt". 
  	"candidate_genes(ID)_eQTL.txt" is a tab-delimited text file with four columns: SNP_ID (AKA Variant), Chromosome number, Locus (position of SNP on chr), and GeneSymbol/ID. SNP_ID is the ID of the query variant (user-input GWAS SNP) that either appears at the same locus as an eQTL linked to GeneSymbol/ID, or is in strong LD with a variant that appears at the same locus as an eQTL linked to GeneSymbol/ID. Thus, a single SNP_ID can be associated with multiple GeneSymbol/IDs linked through different eQTL at different loci. That is to say, the Variant column only lists the SNP_ID of a user-input GWAS SNP, even if the eQTL appears at the same position as a SNP in strong LD with the variant and not the same position as the listed variant itself.

  	"TRE_candidate_genes(_id).txt" is a tab-delimited text file with five columns: SNP_IDs (Variants associated with the risk region), SNP_Locus (position of individual SNP overlapping with TRE), TRE_Locus (position of TRE overlapping with individual SNP), GeneSymbol/ID (that is affected by TRE), Annotation (database source from which TRE data was curated). 

  	"custom_candidate_genes(_id).txt" has the same output format as the TRE file.

- Another intermediate file of interest is "gwascge/output/qualified_training_genes.txt" which contains a list of gene symbols and IDs for each input training gene that was "qualified" — i.e. the training gene of interest could be found in the used (active) gene network and GO term list, and, if the training gene file used gene symbols, we were able to map the gene symbol to its gene ID. Note that the suggested number of input training genes discussed above really means qualified input training genes.

 - Before candidate gene scoring takes place, the user can look at the intermediate file "gwascge/output/candidate_gene_list.txt" to see the list of unscored candidate genes produced by the first portion of the PGA program.




  -Jhih-Rong Lin, Daniel Jaroslawicz