Introduction
============
PeakRanger is a multi-purporse software suite for analyzing next-generation sequencing (NGS) data. 
The suite contains the following tools:

1. `nr` noise rate estimator. Estimates signal to noise ratio which is an indicator for ChIP enrichment
2. `lc` library complexity calculator. Calculates the ratio of unique reads over total reads. Only accepts bam files.
3. `wig` coverage file generator. Generates variable step format wiggle file
4. `wigpe` coverage file generator. Generates bedGraph format wiggle file and supports spliced alignments and thus only supports bam files
5. `ranger` ChIP-Seq peak caller. It is able to identify enriched genomic regions while at the same time discover summits within these regions.
6. `ccat` ChIP-Seq peak caller. Tuned for the discovery of broad peaks

Both `ranger` and `ccat` supports generating HTML-based annotation reports.

`wigpe` can also generate coverage files for bam files containing spliced reads, such as those from RNA-Seq experiments.

If you use PeakRanger in your research, please cite:

Feng X, Grossman R, Stein L: PeakRanger:A cloud-enabled peak caller for ChIP-seq data.BMC Bioinformatics 2011, 12(1):139.(http://www.biomedcentral.com/1471-2105/12/139/)

if you use the `ccat` tool, please also cite:

Xu, H., L. Handoko, et al. (2010).A signal-noise model for significance analysis of ChIP-seq with negative control.Bioinformatics 26(9): 1199-1204.(http://bioinformatics.oxfordjournals.org/content/26/9/1199)

System Requirement
===================
1. The ranger and ccat tool depends on the R programming environment to generate HTML reports. But they can run without it, even with `--report` and `--gene_annot_file` set.
2. When the number of peaks called by ranger or ccat is huge, it takes a while for user's browser to parse the generated HTML file.
3. The lc tool needs about 1.7G ram per 10 million aligned reads.

Obtaining PeakRanger
=================
PeakRanger can be downloded from sourceforge.

Compiling PeakRanger from source codes
======================================

Compiling in Ubuntu
------------------

Required libraries before compiling:

1. The Boost library v1.47 or newer

2. Pthread

3. g++

Once all the libraries are installed, go to the root path of the unzipped package and type:

`make`

This will generate `bin/peakranger`. Compilation in other Linux distributions is similar.

Compiling in Mac OSX
------------------

Required libraries before compiling:

1. Xcode developer tool kit from Apple

2. The Boost library v1.47 or newer

The Xcode kit can be installed using the OSX installation disk. The Boost library can be 
installed by following the instructions on its website. If you do not have root access,
change the variable in the make file:

BOOST_LIB_PATH =  -L/path/to/your/boost/library 

BOOST_HEADER_PATH = -I/path/to/your/boost/header 

If you also want to build tests in `boost_tests`, the makefile located in that folder must also be changed

Once all the libraries are installed, go to the root path of the unzipped package and type:

`make` 

If the compilation failed, double check the path variable is correctly set.
The resulting binaries require dynamic boost library files, to make sure `peakranger` can find
these files, type :

`export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/path/to/your/boost/library`

please change the `path` accordingly.

Compiling in Windows
------------------
Not supported but should be possible.

HTML support
------------------

R is required for HTML report generation.

Synopsis
===================
peakranger lc sample.bam 

peakranger nr --format bam sample.bam control.bam

peakranger wig --format bam sample.bam sample.bam_coverage

peakranger wig --format bed sample.bed sample.bed_coverage

peakranger wigpe sample.bam sample.bam_coverage 

peakranger wigpe sample.bam sample.bam_coverage_splitted -s

peakranger wigpe sample.bam sample.bam_coverage_splitted_by_strand -sx

peakranger wigpe sample.bam sample.bam_coverage_gzipped -z

peakranger wigpe sample.bam sample.bam_coverage_splitted_by_strand_gzip -sxz

peakranger wigpe sample.bam sample.bam_coverage_read_extend_to_200 -l 200

peakranger ranger --format bam sample.bam control.bam ranger_result 

peakranger ranger --format bam sample.bam control.bam ranger_result_threaded_faster -t 3

peakranger ccat --format bam sample.bam contro.bam ccat_result

peakranger ccat --format bam sample.bam contro.bam ccat_result_with_HTML_report \
                --report --gene_annot_file hg19refGene.txt \
                
peakranger ccat --format bam sample.bam contro.bam ccat_result_with_HTML_report_5kb_region \
                --report --gene_annot_file hg19refGene.txt \
                --plot_region 10000

Command line options
===================
## nr
  input

  `-d,--data`
  
data file.

  `-c,--control`	
  
control file. 
  
  `--format`
  	
the format of the data file, can be one of : bowtie, sam, bam and bed.

  Qualities

  `-l,--ext_length`   

read extension length

  Other 

  `-h,--help`   
  
  show the usage

  `--verbose`  
  
  show progress

  `--version`  
  
  output the version number

## lc
  input

  `-d,--data`
  
data file.

  Other 

  `-h,--help`   
  
  show the usage

  `--verbose`  
  
  show progress

  `--version`  
  
  output the version number

## wig
  input

  `-d,--data`
  
data file.

  `--format`
  	
the format of the data file, can be one of : bowtie, sam, bam and bed.

  Output

  `-o,--output`  
  
  the output location

  `-s,--split`
        
 generate one wig file per chromosome
  
  `-z,--gzip`
        
 compress the output
  
  `-x,--strand`
        
 generate one wig file per strand
  
  Qualities

  `-l,--ext_length`   

read extension length

  Other 

  `-h,--help`   
  
  show the usage

  `--verbose`  
  
  show progress

  `--version`  
  
  output the version number

## wigpe
  input

  `-d,--data`
  
data file.

  Output

  `-o,--output`  
  
  the output location

  `-s,--split`
        
 generate one wig file per chromosome
  
  `-z,--gzip`
        
 compress the output
  
  `-x,--strand`
        
 generate one wig file per strand
  
  Qualities

  `-l,--ext_length`   

read extension length

  Other 

  `-h,--help`   
  
  show the usage

  `--verbose`  
  
  show progress

  `--version`  
  
  output the version number

## ranger
  input

  `-d,--data`
  
data file.

  `-c,--control`	
  
control file. 
  
  `--format`
  	
the format of the data file, can be one of : bowtie, sam, bam and bed.

  Output

  `-o,--output`  
  
  the output location

  `--report`
        
 generate html reports
  
  `--plot_region`
        
 the length of the snapshort regions in the HTML report. It also controls the search span for nearby genes.
  
  `--gene_annot_file`
        
 the gene annotation file
  
  Qualities

  `-p,--pval`   
    
p value cut off

  `-q,--FDR`   
    
FDR cut off

  `-l,--ext_length`   

read extension length

  `-r,--delta`   

sensitivity of the summit detector

  `-b,--bandwidth`    
  
smoothing bandwidth.

  `--pad`    

pad read coverage to avoid false positive summits

  Running modes

  `-t`  
      
number of threads.(default: 1)
  
  Other 

  `-h,--help`   
  
  show the usage

  `--verbose`  
  
  show progress

  `--version`  
  
  output the version number

## ccat
  input

  `-d,--data`
  
data file.

  `-c,--control`	
  
control file. 
  
  `--format`
  	
the format of the data file, can be one of : bowtie, sam, bam and bed.

  Output

  `-o,--output`  
  
  the output location

  `--report`
        
 generate html reports
  
  `--plot_region`
        
 the length of the snapshort regions in the HTML report. It also controls the search span for nearby genes.
  
  `--gene_annot_file`
        
 the gene annotation file
  
  Qualities

  `-q,--FDR`   
    
FDR cut off

  `--win_size`   

 sliding window size

  `--win_step`   

window moving step

  `--min_count`    
  
 minimum window reads count

  `--min_score`    

 minimum window reads fold change

  `-l,--ext_length`   

read extension length

  Other 

  `-h,--help`   
  
  show the usage

  `--verbose`  
  
  show progress

  `--version`  
  
  output the version number

Using the gene annotation module
===============================
for ranger and ccat, users can generate HTML reports for called peaks by using:

`--report --gene_annot_file sample_data/gene_annotation_files/dm3refGene.txt`

in the `sample_data` folder, we provide annotation files for hg19, dm3 and mm9. Users
can download annotations of other species from UCSC' genome browsers.

Output files
===============
  lc 
lc does not generate any files

  nr
nr does not generate any files

  wig
wig generates a single file by default. When -x or -s is specified, it generates multiple files depending on the datasets.

  wigpe
similar to wig

  ranger 
Three files will be geneated:

`_summit.bed`

`_region.bed`

`_details`

The first two bed files can be visualized in IGV. `_summit.bed` file contains
the locations of summits ranked by their FDR. `_regions.bed` file contains the locations
of regions ranked by their FDR. Each summit or region is annotated by the 4th column.

`_details` file contains both summits and regions as well
as the regions's FDR and p values. 

When `--report` is enabled, this file will also contain nearby genes of called peaks.

`--report` enables HTML reporting that generates a folder named using the data file's name. The folder
contains a single `index.html` visualizable in most browsers.

  ccat 
Similar to ranger

PeakRanger: http://ranger.sourceforge.net
modENCODE: http://www.modencode.org
PeakSeq: http://info.gersteinlab.org/PeakSeq
sourceforge: http://ranger.sourceforge.net
ChIP-Seq: http://en.wikipedia.org/wiki/Chip-Sequencing
GNU Scientific Library (GSL): http://www.gnu.org/software/gsl/
Ubuntu: http://www.ubuntu.com
confuse option file parser: http://www.nongnu.org/confuse/
Bowtie: http://bowtie-bio.sourceforge.net
Hadoop: http://hadoop.apache.org/
Boost: http://www.boost.org/
IGV: http://www.broadinstitute.org/igv/
Hadoop Streaming: http://hadoop.apache.org/common/docs/r0.15.2/streaming.html
NGS: http://en.wikipedia.org/wiki/DNA_sequencing
