USAGE:

'perl $program -h'    for this message
'perl $program -r'    for this message + the detailed README.txt file

FOR A SINGLE FILE:
  perl $program -f contigs_fasta_file [-m n]

FOR MULTIPLE FILES:
 Full report:
  perl $program -i input_dir [-s subDir1__subDir2_..] [-K n_m_l] -p filename_pattern
               [-c -g (k/s) -m INT -altK STRING -o]
 
 Single-stat, csv-formatted report for Excel:
  perl $program -i input_dir [-s subDir1__subDir2_..] [-K n_m_l] -p filename_pattern
                -v stat_name [-m INT -altK STRING -o]

OPTIONS:
-m INT               : Min length for Contig to be included. Default = 200.
-p filename_pattern  : the pattern of assembly filename in the directory. The 'K' cha-
                       racter (if it's in it) is replaced by K-mer lengths listed in
											 -K. See README.txt for examples
-s subDir1__subDir2..: the sub-directories within the main input directory, joined by '__'
-K n_m_l_..          : n_m_l are INTEGER K-mer lengths. They replace the 'K' character in
                       filename_pattern by default. NOTE THAT they are joined by a SINGLE
			           '_' character, while subDirs are joined by 
					   TWO '_' characters.
-c                   : print output in csv format
-g (k/s)             : group assembly files by (k)mer length or (s)ubdir. Default is s 
-altK STRING         : specify an alternative pattern of character(s) to K in case your
                       normal filename pattern has K. See README.txt for examples
-o                   : over-write previously created individual reports (see README.txt).
-v stat_name         : single_stat name (see below). 

-v: ALLOWED STAT NAMES 
----------------------
	n25, n50, n50p, n75, n90, median, mean, min, max, total, n, gc_c, gc_p
	
	n50p    : N50(perc_contigs_before, perc_contigs_after)
	median  : median contig length
	mean    : mean contig length
	min     : min contig length
	max     : max contig length
	total   : total contig length
	n       : number of contigs
	gc_c    : GC count
	gc_p    : GC%

------------------------------------------------------------------------------------------
What this script does:
------------------------------------------------------------------------------------------
 Essentially, this script takes a fasta-formatted file (of contigs or scaffolds) and prints 
out its basic contig statistics. However, this script can do more than that. This script can
examine multiple contig files, located at different subdirectories within one input directory
and assembled at different K-mer lengths (for De Bruijn graph assemblers like Velvet and SOAP-
denovo), and print a summary of stats for all these files, grouped by the Kmer size (for files
assembled using DBG assemblers) or by the subdirectories containing them. 

 Another feature of this program is "cumulative reporting," i.e., the program tries not to parse
a contigs file that it has parsed before and will instead give you the results of last time's 
report. This is useful for big assembly projects where not all files in the specified input_Dirs
are finished every time your run assembly_summary.pl.The way this is done is that every time you
run assembly_Summary.pl on a group of files, it creates an individual report for each file at its
directory. When assembly_summary.pl is called again on the same file, it looks for that individual
report and it returns its values instantly instead of taking time to parse the file again. Of course
you can turn this feature off by adding "-o" to the commandline.
 
  The default output is tab-delimited. Comma-delimited (csv-formatted) output, which is readable 
by Excel or any similar application, can be created by adding the -c option.

 I assume that the contigs filenames (of all assemblies) share some filename pattern,
which usually differs based on the K-mer length. For example, Velvet's multiple-K option
(velveth 21,29,4) creates the following sub-directories:
_21/, _25/, _29/, and each of them contains contigs.fa. So, the filename pattern here is
_K/contigs.fa

Example 1: You have one dataset,foo, that's assembled at K (hash) = 21, 31, 41, 51 as follows
/path/foo/
  /velvet-21/contigs.fa
  /velvet-31/contigs.fa
  /velvet-41/contigs.fa
  /velvet-51/contigs.fa

To get a contig_stats summary for all the files in /path/Experiments, use the following commandline:
 perl assembly_Summary.pl -i path/foo -K 21_25_29 -p velvet-K/contigs.fa
  

Example 2: You have different experiments (differently-trimmed versions of a dataset), that are
saved as suDirectories within one main Directory. Each of these experiments have the same number
of assembly directories, like this:

/path/Experiments/
                  /Exp_1
                	_21/contigs.fa	
                	_25/contigs.fa
                	_29/contigs.fa
                		
                  /Exp_2
                	_21/contigs.fa	
                	_25/contigs.fa
                	_29/contigs.fa
                	
To get a contig_stats summary for all the files in /path/Experiments, use the following commandlines:

  grouped by k: perl assembly_Summary.pl -i path/Experiments -s Exp_1__Exp_2 -K 21_25_29 -p _K/contigs.fa -g k
  grouped by s: perl assembly_Summary.pl -i path/Experiments -s Exp_1__Exp_2 -K 21_25_29 -p _K/contigs.fa -g s
  
Example 3: deeper subDirs. Let's say you have

/path/Experiments/
                  /Exp_1
                	_21/contigs.fa	
                	_25/contigs.fa
                	_29/contigs.fa
                		
                  /Exp_2
                     /Exp_2-1
	                	_21/contigs.fa	
	                	_25/contigs.fa
	                	_29/contigs.fa
	                /Exp_2-2
	                	_21/contigs.fa	
	                	_25/contigs.fa
	                	_29/contigs.fa

To get a contig_stats summary for all the files in /path/Experiments, use the following commandlines:
(Note that you had to add Exp_2/ to the path of both subDirs /Exp_2-1 and /Exp_2-2)

  grouped by k: perl assembly_Summary.pl -i path/Experiments -s Exp_1__Exp_2/Exp_2-1__Exp_2/Exp_2-2 -K 21_25_29 -p _K/contigs.fa -g k
  grouped by s: perl assembly_Summary.pl -i path/Experiments -s Exp_1__Exp_2/Exp_2-1__Exp_2/Exp_2-2 -K 21_25_29 -p _K/contigs.fa -g s	                



If your filename pattern has a 'K' character in it and you don't want it to be substituted, you can specify an
alternative character(s) that the program will replace with K-mer lengths, like W. For example:

/path/Experiments/
                  /Exp_1
                	Kmer-21/contigs.fa	
                	Kmer-25/contigs.fa
                	Kmer-29/contigs.fa

You can use: perl assembly_Summary.pl -i path/Experiments -s Exp_1 -K 20_28_34 -p Kmer-W/contigs.fa -g k -altK W 



SINGLE-STAT:
 Prints a table of Exp-K values for a specific statistic. This table is formatted in csv format so that you
can copy-paste this result into some file, foo.csv, open it using Excel and simply select the table and create
a column/bar chart. The chart will be in column-cluster format, grouped by K-mer length.

Sample single_stat output:
------------------------------
perl assembly_Summary.pl -i path/Experiments -s Exp_1__Exp_2 -K 31_51_61_71 -p _K/contigs.fa -v n50

Experiments,K-mer sizes (bp)
,_31,_51,_61,_71
Exp_1,10139,17060,25703,25703
Exp_2,5201,17242,26011,25703

