ChIA-PET Analysis Software

Citation

Phanstiel DH, Boyle AP, Heidari N, Snyder MP. Mango: a bias-correcting ChIA-PET analysis pipeline. Bioinformatics. 2015 Oct 1;31(19):3092-8. doi:10.1093/bioinformatics/btv336. Epub 2015 Jun 1. PubMed PMID: 26034063; PubMed Central PMCID: PMC4592333.

Mango Installation

1. Mango depends on the following R packages.

a) hash b) Rcpp c) optparse d) readr

They can be installed throug CRAN. For example to install the package 'hash' open R and type the following

::

install.packages('hash') install.packages('Rcpp') install.packages('optparse') install.packages('readr')

2. Mango depends on the following software pacakges which should be installed and included in the system PATH prior to using Mango.

a) Bowtie (http://bowtie-bio.sourceforge.net) b) Bedtools >= 2.20.0 (https://github.com/arq5x/bedtools2) c) MACS2 (https://github.com/taoliu/MACS)

3. Once dependencies are installed Mango can be installed from the command line using the following command.

::

git clone https://github.com/dphansti/mango.git R CMD INSTALL --no-multiarch --with-keep.source mango

If installing on cluster where you have limited permissions you may need to setup a local library. An example is shown below.

::

git clone https://github.com/dphansti/mango.git mkdir /R mkdir /R/library export R_LIBS=$R_LIBS:/R/library R CMD INSTALL --no-multiarch --with-keep.source mango --library=/R/library

We recommend adding the $R_LIBS:~/R/library command to your bash_profile as well.

Features

Mango uses fastq files generated by illumina sequencers to call peaks and interactions from ChIA-PET experiments. Arguments can be passed to Mango either by a configuration file, through the command line, or a combination of both. In cases where arguments at supplied both through the command line and a configuration file the values passed via command line arguments will take precidence.

Usage of Mango

::

Rscript mango.R [-options]

Example for regular interactions calling ::

Rscript Mango.R --fastq1 samplename_1.fastq --fastq2 samplename_1.fastq --prefix samplename --argsfile argsfile.txt --chromexclude chrM,chrY --stages 1:5

Example of a argsfile ::

bowtieref = /path/to/hg19 bedtoolsgenome = /path/to/human.hg19.genome

!! Note if using tagmentation-generated libraries !!

If the libraries were generated using tagmentation instead of MmeI digestions and adapter ligation we recommend the following settings: ::

--keepempty TRUE --shortreads FALSE --maxlength 1000

Parameters

ALL STAGES

``argsfile``
 The full path to a file containing any of the following parameters.  See above for example.

``stages``
 stages of the pipeline to execute.  stage can be either a single stage (e.g 1 or a range of stagnes e.g 1:5). default = 1:5

``prefix``
 prefix for all output files. default = mango
 
``outdir``
 The output direcoroy. default = NULL

``bowtieref``
 genome reference file for bowtie
 
``bedtoolsgenome``
 bedtools genome file

``chrominclude``
 comma separated list of chromosomes to use (e.g. chr1,chr2,chr3,...).  Only these chromosomes will be processed.  If NULL all chromosomes with be processed. default = NULL
 
``chromexclude``
 comma separated list of chromosomes to exclude (e.g. chrM,chrY).  If NULL all chromosomes with be processed. !!chrM should always be excluded due to its extremely short length!! default = NULL

``bedtoolspath``
 full path to bedtools (only required if not found in system PATH). default = NULL

``macs2path``
 full path to macs2 (only required if not found in system PATH). default = NULL

``bowtiepath``
 full path to bowtie (only required if not found in system PATH). default = NULL


STAGE 1 PARAMETERS

linkerA linker sequence to look for. default = GTTGGATAAG

linkerB linker sequence to look for. default = GTTGGAATGT

singlelinker Was only a single linker used? If TRUE Mango will only look for linkerA. LinkerB will be ignored. default = FALSE

minlength min length of reads after linker trimming. default = 15

maxlength max length of reads after linker trimming. If libraries were generated via tagmentation this should be set to a value greater than the read length (i.e. 1000). default = 25

keepempty Should reads with no linker be kept (TRUE or FALSE). If libraries were generated via tagmentation this should be set to TRUE. default = FALSE

STAGE 2 PARAMETERS

``shortreads``
 should bowtie alignments be done using paramter for very short reads (~20 bp).  If libraries were generated via tagmentation this should be set to FALSE. default = TRUE
 
``threads``
 number of threads to be used for bowtie alignment. default = 1 (!! This option is currently disabled to due to errors.  We are working on a solution !!)
 

STAGE 2 PARAMETERS

npets4dist the number of PETS to use to plot PET distance distribution. default = 1000000 (use -1 for all PETS).

STAGE 4 PARAMETERS

``MACS_qvalue``
 pvalue cutoff for peak calling in MACS2. default = 0.05

``MACS_shiftsize``
 MACS shiftize.  NULL allows MACS to determine it

``peakslop``
 Number of basespairs to extend peaks on both sides. default = 500

``peakinput``
 Name of user supplied peaks file.  If NULL Mango will use peaks determined from MACS2 analysis. default = NULL

``blacklist``
 BED file of regions to remove from MACS peaks

``gzize``
 mappable genome size or effective genome size for MACS2.default = 'hs'
 
STAGE 5 PARAMETERS

distcutrangemin When Mango determines the self-ligation cutoff this is the minimum distance it will consider. Changing this setting is not recommended. default = 1000

distcutrangemax When Mango determines the self-ligation cutoff this is the maximum distance it will consider. Changing this setting is not recommended. default = 100000

biascut Mango exlcudes very short distance PETS since they tend to arise from self-ligation of a single DNA framgent as opposed to interligation of two interacting fragments. To determine this distnce cutoff Mango determines the fraction of PETs at each distance that come from self-ligation and sets the cutoff at the point where the fraction is less than or equal to BIASCUT. default = 0.05

FDR FDR cutoff for significant interactions. default = 0.05

numofbins number of bins to use for binomial p-value calculations. default = 50

corrMethod Method to use for correction of mulitply hypothesis testing. See (http://stat.ethz.ch/R-manual/R-devel/library/stats/html/p.adjust.html) for more details. default = BH

maxinteractingdist The maximum disance (in basepairs) considered for interaction. Optimum sensitivity is generally acheived at values of 1000000-2000000. default = 1000000

extendreads how many bp to extend reads towards peak. default = 120

minPETS The minimum number of PETs required for an interaction (applied after FDR filtering). default = 2

reportallpairs Should all pairs be reported or just significant pairs (TRUE or FALSE). default = FALSE

Intermediate Files

...same.fastq

These files contain fastq formated sequences after linkers have been detected and removed. Only pairs of reads with the same linker sequences on both ends of the PET are reported in these files. These are the only reads used for subsequent steps.

...chim.fastq

These files contain fastq formated sequences after linkers have been detected and removed. Only pairs of reads with the different linker sequences on both ends of the PET are reported in these files. These reads are NOT used for subsequent steps.

...bedpe

This file desribes all aligned PETs. The columns are (chromosome1, start1, end1, chromosome2, start2, end2, readname, score, strand1, strand2)

...rmdup.bedpe

This file desribes all aligned PETs after removal of duplicate PETs. The columns are (chromosome1, start1, end1, chromosome2, start2, end2, readname, score, strand1, strand2)

...tagAlign

This file desribes all reads (PETs are split into two lines in this file) in standard tagAlign format. The columns are (chromosome, start, end, readname, score, strand)

...slopPeak

This file desribes peaks after peak calling, addition of a user defined number of basepairs (peakslop), and merging of overlapping peaks. The columns are (chromosome, start, end, peakname).

Output Files

...interactions.fdr.mango

This files contains all significant interactions. The columns are (chromosome1, start1, end1, chromosome2, start2, end2, PETs supporting the interaction, the adjusted P-value of the interaction)*

...interactions.all.mango

This files contains all tested interactions and is only generated if 'reportallpairs' is TRUE. The columns are the same as those for the file above.

*More columns with column headers will be output if 'verboseoutput' is TRUE.