WARNING: If you see the following error, then downgrade your
sppto 1.14 or 1.15.x.Error in lwcc(x, y, s, e, return.peaks = return.peaks, bg.x = bg.x, bg.y = bg.y, : INTEGER() can only be applied to a 'integer', not a 'character'
This package computes informative enrichment and quality measures for ChIP-seq/DNase-seq/FAIRE-seq/MNase-seq data. It can also be used to obtain robust estimates of the predominant fragment length or characteristic tag shift values in these assays.
This set of programs operate on mapped Illumina single-end read datasets in tagAlign or BAM format. They can be used to
If you are using the code or results in any formal publication please cite
[1] Landt SG1, Marinov GK, Kundaje A et al. ChIP-seq guidelines and practices of the ENCODE and modENCODE consortia. Genome Res. 2012 Sep;22(9):1813-31. doi: 10.1101/gr.136184.111.
[2] Kharchenko PK, Tolstorukov MY, Park PJ, Design and analysis of ChIP-seq experiments for DNA-binding proteins Nat Biotechnol. 2008 Dec;26(12):1351-9
NOTE: The current package does not run on a MacOS or Windows.
spp_1.14.tar.gz : modified SPP peak-caller package (The original SPP-peak caller package was written by Peter Kharchenko [2], https://github.com/hms-dbmi/spp)run_spp.R : The script to compute the frag length, data quality characteristics based on cross-correlation analysis and/or peak callingFirst make sure that you have installed R (version 3.1 or higher)
Also, you must have the Boost C++ libraries installed. Most linux distributions have these preinstalled.
If not, you can easily get these from your standard package manager for your linux distribution.
e.g synaptic package manager (apt-get) for ubuntu or emerge for gentoo.
Clone the repo.
$ git clone https://github.com/kundajelab/phantompeakqualtoolsInstall the following R packages
$ cd phantompeakqualtools
$ R
(From within R)
> install.packages("snow", repos="http://cran.us.r-project.org")
> install.packages("snowfall", repos="http://cran.us.r-project.org")
> install.packages("bitops", repos="http://cran.us.r-project.org")
> install.packages("caTools", repos="http://cran.us.r-project.org")
> source("http://bioconductor.org/biocLite.R")
> biocLite("Rsamtools",suppressUpdates=TRUE)
> install.packages("./spp_1.14.tar.gz")If your alignment files are BAM, you must have the samtools executable in your path so that the R script run_spp.R can call it using the system() command
You can get samtools from (here)[http://samtools.sourceforge.net/]
You can add the following line to your ~/.bashrc file
export PATH="<path_to_samtools_executable>:${PATH}"Run run_spp.R
Rscript run_spp.R <options>Usage: Rscript run_spp.R <options>
Mandatory arguments
| argument | description |
|---|---|
| -c=\<ChIP_alignFile> | full path and name (or URL) of tagAlign/BAM file (can be gzipped) (FILE EXTENSION MUST BE tagAlign.gz, tagAlign, bam or bam.gz) |
Mandatory arguments for peak calling
| argument | description |
|---|---|
| -i=\<Input_alignFile> | full path and name (or URL) of tagAlign/BAM file (can be gzipped) (FILE EXTENSION MUST BE tagAlign.gz, tagAlign, bam or bam.gz) |
Optional arguments
| argument | description |
|---|---|
| -s=\<min>:\<step>:\<max> | strand shifts at which cross-correlation is evaluated, default=-500:5:1500 |
| -speak=\<strPeak> | user-defined cross-correlation peak strandshift |
| -x=\<min>:\<max> | strand shifts to exclude (This is mainly to avoid region around phantom peak) default=10:(readlen+10) |
| -p=\<nodes> | number of parallel processing nodes, default=0 |
| -fdr=\<falseDisoveryRate> | false discovery rate threshold for peak calling |
| -npeak=\<numPeaks> | threshold on number of peaks to call |
| -tmpdir=\<tempdir> | temporary directory (if not specified R function tempdir() is used) |
| -filtchr=\<chrnamePattern> | pattern to use to remove tags that map to specific chromosomes e.g. will remove all tags that map to chromosomes with in their name |
Output arguments
| argument | description |
|---|---|
| -odir=\<outputDirectory> | name of output directory (If not set same as ChIP file directory is used) |
| -savn=\<narrowpeakfilename> | NarrowPeak file name (fixed width peaks) |
| -savn | |
| -savr=\<regionpeakfilename> | RegionPeak file name (variable width peaks with regions of enrichment around peak summits) |
| -savr | |
| -savd=\<rdatafile> | save Rdata file |
| -savd | |
| -savp=\<plotdatafile> | save cross-correlation plot |
| -savp | |
| -out=\<resultfile> | append peakshift/phantomPeak results to a file |
| -rf | if plot or rdata or narrowPeak file exists replace it. If not used then the run is aborted if the plot or Rdata or narrowPeak file exists |
| -clean | if used it will remove the original chip and control files after reading them in. CAUTION: Use only if the script calling run_spp.R is creating temporary files |
Determine strand cross-correlation peak / predominant fragment length OR print out quality measures. -out=<outFile> will create and/or append to a file named
Rscript run_spp.R -c=<tagAlign/BAMfile> -savp -out=<outFile>The file contains 11 tab delimited columns.
| col. | abbreviation | description |
|---|---|---|
| 1 | Filename | tagAlign/BAM filename |
| 2 | numReads | effective sequencing depth i.e. total number of mapped reads in input file |
| 3 | estFragLen | comma separated strand cross-correlation peak(s) in decreasing order of correlation. |
| 4 | corr_estFragLen | comma separated strand cross-correlation value(s) in decreasing order (COL2 follows the same order) |
| 5 | phantomPeak | Read length/phantom peak strand shift |
| 6 | corr_phantomPeak | Correlation value at phantom peak |
| 7 | argmin_corr | strand shift at which cross-correlation is lowest |
| 8 | min_corr | minimum value of cross-correlation |
| 9 | NSC | Normalized strand cross-correlation coefficient (NSC) = COL4 / COL8 |
| 10 | RSC | Relative strand cross-correlation coefficient (RSC) = (COL4 - COL8) / (COL6 - COL8) |
| 11 | QualityTag | Quality tag based on thresholded RSC (codes= -2:veryLow, -1:Low, 0:Medium, 1:High, 2:veryHigh) |
The top 3 local maxima locations that are within 90% of the maximum cross-correlation value are output. In almost all cases, the top (first) value in the list represents the predominant fragment length. If you want to keep only the top value simply run
sed -r 's/,[^\t]+//g' <outFile> > <newOutFile>You can run the program on multiple datasets in parallel and append all the quality information to the same
NSC values range from a minimum of 1 to larger positive numbers. 1.1 is the critical threshold. Datasets with NSC values much less than 1.1 (< 1.05) tend to have low signal to noise or few peaks (this could be biological eg.a factor that truly binds only a few sites in a particular tissue type OR it could be due to poor quality)
RSC values range from 0 to larger positive values. 1 is the critical threshold. RSC values significantly lower than 1 (< 0.8) tend to have low signal to noise. The low scores can be due to failed and poor quality ChIP, low read sequence quality and hence lots of mismappings, shallow sequencing depth (significantly below saturation) or a combination of these. Like the NSC, datasets with few binding sites (< 200) which is biologically justifiable also show low RSC scores.
Qtag is a thresholded version of RSC.
Peak calling
Rscript run_spp.R -c=<ChIP_tagalign/BAM_file> -i=<control_tagalign/BAM_file> -fdr=<fdr> -odir=<peak_call_output_dir> -savr -savp -savd -rf
Rscript run_spp.R -c=<ChIP_tagalign/BAM_file> -i=<control_tagalign/BAM_file> -npeak=<npeaks> -odir=<peak_call_output_dir> -savr -savp -savd -rfFor IDR analysis you want to call a large number of peaks (relaxed threshold) so that the IDR model has access to a sufficient noise component.
Rscript run_spp.R -c=<ChIP_tagalign/BAM_file> -i=<control_tagalign/BAM_file> -npeak=300000 -odir=<peak_call_output_dir> -savr -savp -rf -out=<resultFile>It is EXTREMELY important to filter out multi-mapping reads from the BAM/tagAlign files. Large number of multimapping reads can severly affect the phantom peak coefficient and peak calling results.
If a dataset seems to have high PCR bottlenecking, then you might want to actually clamp the number of unique mappping reads per position to 1 or upto 5. If not the phantom peak coefficient can be artificially good.
For the IDR rescue strategy, one needs to pool reads from replicates and then shuffle and subsample the mapped reads to create two balanced pseudoReplicates. This is much easier to implement on tagAlign/BED read-mapping files using the unix 'shuf' command. So it is recommended to use the tagAlign format.
In most cases, you can simply use the maximum reported strand correlation peak as the predominant fragment length. However, it is useful to manually take a look at the cross-correlation plot to make sure the selected max peak is not an artifact.
Also, if there are problems with library size-selection, a dataset's cross-correlation profile can have multiple strong cross-correlation peaks. This is currently not autodetected.
BAM format: This is a binary alignment format specified in http://samtools.sourceforge.net/SAM-1.3.pdf You MUST have samtools installed to use run_spp.R with BAM files
TagAlign files: This a text-based BED3+3 alignment format that is easier to manipulate. It contains 6 tab delimited columns.
| col. | abbrv. | type | description |
|---|---|---|---|
| 1 | chrom | string | Name of the chromosome |
| 2 | chromStart | int | The starting position of the feature in the chromosome. The first base in a chromosome is numbered 0. |
| 3 | chromEnd | int | The ending position of the feature in the chromosome or scaffold. The chromEnd base is not included in the display of the feature. For example, the first 100 bases of a chromosome are defined as chromStart=0, chromEnd=100, and span the bases numbered 0-99. |
| 4 | sequence | string | Sequence of this read |
| 5 | score | int | Indicates uniqueness or quality (preferably 1000/alignmentCount). |
| 6 | strand | char | Orientation of this read (+ or -) |
NOTE: You dont have to store the sequence of reads in the sequence field as the peak caller never really uses that field. You can just put the letter 'N' in that field. This saves space significantly.
For the IDR rescue strategy, one needs to use shuffled and subsampled version of the alignment files. This is much easier to implement on tagAlign text files using the unix shuf command.
So it is recommended to preferably use the tagAlign format.
It is very quick to convert pre-filtered BAM files (after removing unmapped, low quality reads, multimapping reads and duplicates) to gzipped tagAlign files using
samtools view -F 0x0204 -o - <bamFile> | awk 'BEGIN{OFS="\t"}{if (and($2,16) > 0) {print $3,($4-1),($4-1+length($10)),"N","1000","-"} else {print $3,($4-1),($4-1+length($10)),"N","1000","+"} }' | gzip -c > <gzip_TagAlignFileName>NarrowPeak/RegionPeak format: The output peak file is in BED6+4 format known as tagAlign. It consists of 10 tab-delimited columns
| col. | abbrv. | type | description |
|---|---|---|---|
| 1 | chrom | string | Name of the chromosome |
| 2 | chromStart | int | The starting position of the feature in the chromosome. The first base in a chromosome is numbered 0. |
| 3 | chromEnd | int | The ending position of the feature in the chromosome or scaffold. The chromEnd base is not included in the display of the feature. For example, the first 100 bases of a chromosome are defined as chromStart=0, chromEnd=100, and span the bases numbered 0-99. |
| 4 | name | string | Name given to a region (preferably unique). Use '.' if no name is assigned. |
| 5 | score | int | Indicates how dark the peak will be displayed in the browser (1-1000). If '0', the DCC will assign this based on signal value. Ideally average signalValue per base spread between 100-1000. |
| 6 | strand | char | +/- to denote strand or orientation (whenever applicable). Use '.' if no orientation is assigned. |
| 7 | signalValue | float | Measurement of overall (usually, average) enrichment for the region. |
| 8 | pValue | float | Measurement of statistical signficance (-log10). Use -1 if no pValue is assigned. |
| 9 | qValue | float | Measurement of statistical significance using false discovery rate (-log10). Use -1 if no qValue is assigned. |
| 10 | peak | int | Point-source called for this peak; 0-based offset from chromStart. Use -1 if no point-source called. |
ChIP-seq guidelines and practices of the ENCODE and modENCODE consortia. Landt SG*, Marinov GK*, Kundaje A*, Kheradpour P*, Pauli F, Batzoglou S, Bernstein BE, Bickel P, Brown JB, Cayting P, Chen Y, DeSalvo G, Epstein C, Fisher-Aylor KI, Euskirchen G, Gerstein M, Gertz J, Hartemink AJ, Hoffman MM, Iyer VR, Jung YL, Karmakar S, Kellis M, Kharchenko PV, Li Q, Liu T, Liu XS, Ma L, Milosavljevic A, Myers RM, Park PJ, Pazin MJ, Perry MD, Raha D, Reddy TE, Rozowsky J, Shoresh N, Sidow A, Slattery M, Stamatoyannopoulos JA, Tolstorukov MY, White KP, Xi S, Farnham PJ, Lieb JD, Wold BJ, Snyder M.
Genome Res. 2012 Sep;22(9):1813-31. doi: 10.1101/gr.136184.111.