_____  _                 _            
                   |  __ \(_)               | |           
                   | |__) |_ _ __ __ _ _ __ | |__   __ _  
                   |  ___/| | '__/ _` | '_ \| '_ \ / _` | 
                   | |    | | | | (_| | | | | | | | (_| | 
                   |_|    |_|_|  \__,_|_| |_|_| |_|\__,_|
                   **************************************
                   *               V1.2.1               *
                   ************************************** 
                                        

*********************************
Copyright and License Information
*******************************************************************************
Copyright (C) 2012
University of Southern California,
Philip J. Uren, Andrew D. Smith
  
Authors: Philip J. Uren, Emad Bahrami-Samani, Andrew D. Smith
  
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
  
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
  
You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

This software package contains Google Test and BAMTools -- see their 
respective directories for copyright and license information for those 
packages. 


*****************
Table of contents
*******************************************************************************
1. Building and Installing Piranha 
2. Basic usage of Piranha 
3. Command-line options of Piranha 
4. Input and output formats of Piranha
5. Simulation of input data for Piranha
6. Contacts and bug reports


**********************************
1. Building and Installing Piranha
*******************************************************************************
Piranha has been designed to operate in a UNIX-like environment.
It has been tested on MacOS X Snow Leopard, USCLinux, Ubuntu and SUSE. We've
made every effort to ensure it's compatible with a wide range of systems, but
we can't test on all possible platforms and configurations. If you find an
incompatibility when building or using it, please let us know!

Step 0 -- dependencies and requirements
---------------------------------------
  64-bit machine and GCC version > 4.1 (to support TR1). 
  
  Piranha additionally requires a functioning installation of the GNU 
  Scientific Library (GSL). If you don't already have this installed, you will
  need to download and install it from http://www.gnu.org/software/gsl/
  This release has been tested with GSL version 1.14
  Your installation of GSL must be built for a 64 bit architecture.
  
  [OPTIONAL] Tests
    The regression tests (which you don't need to run, but can to test that 
    Piranha was built correctly) require Python. You can download Python 
    from http://www.python.org/
    This release has been tested with Python 2.6.1 
  
  [OPTIONAL] BAM support
    If you want BAM support, you must download and build BAMTools.
    If Piranha cannot find the BAMTools development headers and library,
    it will be compiled without support for BAM. See below for details on
    how to specify the location of BAMTools during the build process. 
    BAMTools is available from https://github.com/pezmaster31/bamtools
    This release has been tested with BAMTools version 2.1.1   

Step 1 -- configuring
---------------------
  First configure the installation. To do this, where '>' is your prompt and 
  the CWD is the root of the distribution, type:
  
  > ./configure 
  
  [OPTIONAL] BAM support
    configure will warn you if BAM support is not available. If you don't want 
    BAM support, this is fine. If you do want it however, and the configure 
    script did not find BAMTools, you will have to specify where the BAMTools 
    development headers and libraries are located. You can do that as follows
  
    > ./configure --with-bam_tools_headers="/some/path/BAMTools/include/" \
      --with-bam_tools_library="/some/path/BAMTools/lib/"
  
    the command is split into two lines here for aesthetic reasons, but it 
    need not be so. There are a few caveats:
      * If you subsequently move the BAMTools library, Piranha will not work.
        (this should be obvious really).
      * The BAMTools installer currently doesn't update the linker info 
        after installation. That means you might install it, but Piranha will
        still not find it when running ./configure -- in this case, I suggest
        manually specifying the location as shown above.

Step 2 -- building
------------------
  
  To build the binaries, type the following, where '>' is your prompt and the
  CWD is the root of the distribution  
  
  > make all 
  
Step 3 -- installing
--------------------
  To install the binaries, type the following, where '>' is your prompt and the
  CWD is the root of the distribution
  
  > make install
  
  This will place the binaries in the bin directory under the package root.
  They can be used directly from there without any additional steps. You can
  add that directory to your PATH environment variable to avoid having to 
  specify their full paths, or you can copy the binaries to another directory
  of your choice in your PATH.
  
Step 4 -- testing [OPTIONAL]
----------------------------
  You can verify that Piranha was built correctly by running the included
  unit and regression tests. At the command prompt (assuming your prompt is 
  '>') type the following:
  
  > make test 
  
  
*************************
2. Basic usage of Piranha 
*******************************************************************************
Piranha has two main modes of operation. In the first, a single regular 
distribution is fit to the input data and each region is assigned a p-value
based on this distribution. The default distribution is the zero-truncated 
negative binomial. To run Piranha in this way, use the following, where > is 
your prompt  

> ./Piranha input.bed

The second mode of operation fits a regression model relating counts to 
covariates. The default is a zero-truncated negative binomial regression. To
run Piranha in this way, do the following, where > is your prompt 

> ./Piranha input.bed covariate1.bed covariate2.bed

Note that the first file is always assumed to be the counts, and the remaining
files are assumed to be covariates. 

For further options, run Piranha without any arguments, or see the section 
'Command Line Options' below.


**********************************
3. Command-line options of Piranha 
*******************************************************************************
Usage: Piranha [OPTIONS] *.bed

Options:
  -o, -output             Name of output file, STDOUT if omitted 
  -s, -sort               indicates that input is unsorted and Piranha should 
                          sort it for you
  -p, -p_threshold        significance threshold for sites 
  -a, -background_thresh  indicates that this proportion of the lowest scores 
                          should be considered the background. Default is 0.99
  -b, -bin_size           indicates that input is raw reads and should be binned 
                          into bins of this size 
  -i, -bin_size_covars    indicates that the covariates (all except first 
                          file) are raw reads and should be binned into bins of 
                          this size 
  -z, -bin_size_both      synonymous with -b x -i x for any x 
  -u, -cluster_dist       merge significant bins within this distance. 
                          Setting to 0 disables merging, default is 1 (merge 
                          adjacent) 
  -r, -suppress_covars    don't print covariate values in output
  -f, -fit                Fit only, output model to file 
  -d, -dist               Distribution type. Currently supports Poisson, 
                          NegativeBinomial, ZeroTruncatedPoisson, 
                          ZeroTruncatedNegativeBinomial, 
                          PoissonRegression, NegativeBinomialRegression, 
                          ZeroTruncatedPoissonRegression, 
                          ZeroTruncatedNegativeBinomialRegression 
  -t, -fitMethod          component fitting method 
  -m, -model              Use the specified model file instead of fitting to 
                          input data 
  -v, -VERBOSE            output additional messages about run to stderr if set 
  -x, -unstranded         Don't preserve strand (puts all the peaks in positive 
                          strand) 
  -n, -no_normalisation   don't normalise covariates 
  -l, -log_covars         convert covariates to log scale 

Help options:
  -?, -help               print this help message 
      -about              print about message 
 


**************************************
4. Input and output formats of Piranha
*******************************************************************************
    NOTE: BAM support is only available if Piranha was linked with BAMTools
    =======================================================================
 
Piranha takes three possible inputs:
  1.) The response file   (BED or BAM format) [REQUIRED]
  2.) The covariate files (BED format)        [OPTIONAL]      
  3.) The model file      (XML format)        [OPTIONAL]
  
The response file (always the first argument, and required) may contain:
  1.) Binned read counts. In this case the input can be provided in BED 
      format, but not BAM format. The Score field of the BED format file will 
      be treated as the count of the number of reads mapping into that bin. 
      This is the default and is what is expected if no contrary options are 
      specified.
  2.) Raw read locations, in which case Piranha will bin the reads for you. 
      If you provide your input like this, you MUST set the bin size option, 
      or Piranha will treat your input as being already binned. If Piranha is 
      creating bins from raw reads, it will always start at the first index of 
      each chromosome (i.e. index 1) and move at a step size equal to the bin 
      size. Bins with no reads in them will not be retained. 
The file format will be determined by looking at the file extension (.bam or 
.bed). Case is not important; unknown extensions are treated as .bed files. 

The covariates files are optional. You can provide one or more of them.
If none are provided, the program fits a regular distribution (zero-truncated 
negative binomial by default) to the read counts. If covariates are provided,
the program performs regression (zero truncated negative binomial regression
by default) using the provided covariates. Covariates must be provided in
BED format, where the score field (the fifth) is taken as value of the 
covariate for the genomic region defined by the other fields. Every covariate
file must contain genomic loci that match the response file.

Piranha has a special option for handling the case where a single covariate
is present and this covariate is the number of reads from another sequencing
run (for example, a control IP in the case of RIP or an RNA-seq experiment
in the case of CLIP). In this case, the covariate can be provided as a BED
file that contains the raw read locations; the -i option should be used to
indicate that the covariate file is raw reads -- Piranha will then bin these
reads into bins that match the response.

Piranha's output is a tab delimited file with the input regions from the 
response (in BED format) and a single additional column giving the p-value 
for each bin. If covariates were provided, additional columns are added
containing the value of each of the covariates for the given locus.

If the -f option is specified, Piranha will output the model instead of the
scored bins. Models are given in XML format, and can be loaded back into
the program later for scoring a new (or the same) input using the -m option. 


***************************************
5. Simulation of input data for Piranha
*******************************************************************************
We've also included a program for simulating input data - Simulate. After 
building and installing, it can be found in the bin directory. This program 
can produce simulated data from a range of distributions, both regular and 
regression based. Run it without any arguments to see its command line 
options. As an example, to generate 1000 simulated regions where the response 
is dependent on two covariates from a Zero-truncated negative binomial 
regression distribution, you would execute the program as follows, where > is
your prompt (here the command is split over two lines for formatting reasons,
but this need not be the case). 

> ./Simulate -d ZeroTruncatedNegativeBinomialRegression -n 1000 \
> -r response.bed -c "cov1.bed cov2.bed" 


*****************************
6. Frequently asked questions
*******************************************************************************

Q. I get the error: "Failed to split responses, smallest response accounts for 
   more than 99% of all responses. Try increasing the threshold". What does
   this mean? How do I fix it?
A. Piranha assumes most bins in your input are background noise. The program
   models this background and then tests each read count to see if it 
   significantly exceeds the background. This doesn't work if all or most of
   your bins contain the same number of reads though. That is what this 
   message is telling you: more than 99% of the bins in your input contain
   the same number of reads as the smallest read count (usually 1 read, but 
   not neccessarily). Most often this is because you forgot to use the -b
   option to bin your reads and so Piranha thinks each read is its own bin.
   
Q. I am running Piranha with one or more covariates and I got the following
   error (or similiar): "ERROR: evaluating zero-truncated negative binomial 
   regression log-likelihood function with response 1 and distribution 
   parameters beta: 6000,  --- alpha: 100 failed. Reason: result was 
   non-finite"
A. The model fitting algorithm failed to converge. This often happens when
   the covariate(s) contain large values, which is most often the case when
   you provide sequencing data like RIP control IP or RNA-seq data as a
   covariate. Try running the program again with the -l option, which
   converts the read counts from your covariate into log-space; this 
   generally solves the problem.

***************************
7. Contacts and bug reports
*******************************************************************************
Philip J. Uren
uren@usc.edu

Andrew D. Smith
andrewds@usc.edu

If you found a bug in Piranha, we'd like to know about it. Before contacting us
though, please check the following list:

  1.) Are you using the latest version? The bug you found may already have 
      been fixed.
  2.) Check that your input is in the correct format and you have selected
      the correct options.
  3.) Please reduce your input to the smallest possible size that still 
      produces the bug; we will need your input data to reproduce the 
      problem.