#-------------------------------------------------------------------------------#
# Co-factor motifs identification script using the MOODS motif search algorithm 
# By Keunsoo Kang (kangk2@niddk.nih.gov)
# There is no warranty for this script.
#-------------------------------------------------------------------------------#

1. REQUIREMENTs (Linux)

	a. Perl (installed if you are a linux user)
	b. matrix_list.txt (non_redundant and vertebrates from JASPAR [1])
		In case of using non_redundant-vertebrates matrix files
		(a) Download a matrix file from http://jaspar.genereg.net/html/DOWNLOAD/jaspar_CORE/non_redundant/by_tax_group/vertebrates/matrix_only
		(b) Move the file to the main directory where the perl code is located (/)

	c. matrix (PFM file(s) for non_redundant and vertebrates from JASPAR)
		In case of using non_redundant-vertebrates matrix files
		!IMPORTANT - FILE EXTENSION MUST BE ".pfm"
		(a) Download matrix file(s) from http://jaspar.genereg.net/html/DOWNLOAD/jaspar_CORE/non_redundant/by_tax_group/vertebrates/FlatFileDir/
		(b) Move all the pfm files to /JASPAR

	d. chromosome files (.fa files)
		(a) Download chromosome files (.fa) from the UCSC genome browser. For example, if you want to find motifs in the mouse genome (mm9)..
			go to http://hgdownload.cse.ucsc.edu/goldenPath/mm9/bigZips/
			click and download chromFa.tar.gz
			extract the file into /CHR_FILES

	e. chromosome size file (e.g. mm9.chrom.sizes)
		(a) Download (save as fetchChromSizes.py) the 'fetchChromSizes' python script from http://hgdownload.cse.ucsc.edu/admin/exe/linux.x86_64/
		(b) Move the file to the main directory (/) and run it at the main directory.
			ex) fetchChromSizes.py mm9 > mm9.chrom.sizes

	f. Input bed file (ChIP-seq peak file(s) - it is better to use peak centered position)
		You can get this file from various peak-calling program such as MACS and HOMER...
		!IMPORTANT - FILE EXTENSION MUST BE ".bed"
		(a) File should be formatted (only use the first three columns / it uses peak center);
			CHROMOSOME\tSTART_POS\tEND_POS
		
			ex) chr7	13388238	13389683
			    chr7	13550782	13552107
		(b) Move all input bed files to /INPUT_BED

	g. Bioperl should be installed (http://www.bioperl.org/wiki/Installing_BioPerl_on_Unix)

	h. MOODS package [2] should be installed (http://www.cs.helsinki.fi/group/pssmfind/)


2. INSTALLATION
	No further processing is required.

3. HOW TO USE
	perl co-factor_search.pl MATRIX_LIST_FILE CHR_SIZE_FILE MOTIF_THRES(P-val) RANGE(bp, one-side)
	ex) perl co-factor_search matrix_list.txt mm9.chrom.sizes 0.001 100

	How it works...
	(a) Extract all DNA sequences according to the input bed file(s)
	(b) Generate a background set which contains the same number of sequences as input
	(c) Search multiple motifs on each input sequence
	(d) Search multiple motifs on the background sets
	(e) Calculate background normalized values and generate final output.

4. OUTPUT
	"Co-factor_output_(MOTIF_THRES)_(RANGE).txt"
	The output file contains two main columns for each motif (matrix)
	a. Average of normalized motif enrichment score
	b. Normalized motif-covered site

5. CITE
	Please cite the following paper
	Kang K., Gertraud W.R. and Lothar H.
	Comprehensive meta-analysis of Signal Transducers and Activators of Transcription (STATs) genomic binding patterns discerns cell-specific cis-regulatory modules.
	BMC genomics (2012? / 2013?)
	
6. VERSION
	1.0.0 released - 2013-01-04

7. REFERENCES

	[1]	Bryne JC, Valen E, Tang MH, Marstrand T, Winther O, da Piedade I, Krogh A, Lenhard B and Sandelin A.
		JASPAR, the open access database of transcription factor-binding profiles: new content and tools in the 2008 update.
		Nucleic Acids Res. 2008 36(Database issue):D102-6.

	[2]	J. Korhonen, P. Martinmäki, C. Pizzi, P. Rastas and E. Ukkonen. 
		MOODS: fast search for position weight matrix matches in DNA sequences.
		Bioinformatics 2009 25(23):3181-3182.
