cepip: Context-dependent epigenomic weighting for regulatory variant prioritization

Introduction

References

Install and run

System requirement

Java Runtime Environment (JRE) version 6.0 or above is required for cepip. It can be downloaded from the Java web site. Installing the JRE is very easy in Windows OS and Mac OS X.

In Linux, you have more work to do. Details of the installation can be found http://www.java.com/en/download/help/linux_install.xml.

In Ubuntu, if you have an error message like: "Exception in thread "AWT-EventQueue-0" java.awt.HeadlessException ... " , please install the Sun Java Running Environment (JRE) first.

To install the Sun JRE on Ubuntu(10.04), please use the following commands:
sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
sudo apt-get update
sudo apt-get install sun-java6-jre sun-java6-plugin sun-java6-fonts
Detailed explanation of above commands can be found at http://www.ubuntugeek.com/how-install-sun-java-runtime-environment-jre-in-ubuntu-10-04-lucid-lynx.html.

For Mac OS, the JRE 1.6 has been available at http://developer.apple.com/java/download/ since April 2008. Mac OS users may need update the Java application to run cepip. A potential problem is that this update does not replace the existing installation of J2SE 5.0 or change the default version of Java. Similar to the Linux OS, the Java_Home environmental variable has to be configured to initiate cepip.

Download: latest Java version (Fast, now integrate into KGGSeq) | latest Perl version (Slow but no need to download big annotation, <10k variants)

20170318 update: We have integrated our JAVA version cepip into KGGSeq package, now it supports whole genome scoring in an efficient manner (require mannually download dbNCFP wohle genome annotation file). Please refer to the manual for package configuration and running parameters (--regulatory-causing-predict and --cell). The Perl version of cepip is still supported for easy execution of small list of SNVs (< 10K) and reseacher who do not want to download big program-dependent annotation (Please refer to Perl version manual).

20161213 update:  We introduce a Perl version of cepip for remote random access of allele-specific composite score annotations and cell type-specific epigenomic signal annotations. Without downloading the huge annotation file, the user can quickly execute cepip (require Tabix). However, the running speed could be slow using this Perl version. Please run it under small input.  For the first-time user, please download the Perl package from cepip_PL_v0.12.zip (Mac OS X / Linux).

20161024 update:  We allow users to custom their epigenomic annotations. Please download and replace previous jar file from cepip.jar.  For the first-time user, please download the full package from cepip.zip.  We also provide a demo of custom annotations custom_annotations.zip,  please refer to the instrcution in this site for how to use custom annoations.

Installing cepip

Simply decompress the archive and run the following command.

  java -Xms256m -Xmx1300m -jar ./cepip.jar <arguments>

The arguments -Xms256m and -Xmx1300m set the initial and maximum Java heap sizes for cepip as 256 megabytes and 1.3 gigabytes respectively. Specifying a larger maximum heap size can speed up the analysis. A higher setting like -Xmx2g or even-Xmx5g is required when there is a large number of variants, say 5 million. The number, however, should be less than the size of physical memory of a machine.

Note  <arguments >can be saved in a flat text file.

Quick example

Variants file is needed (example.vcf). This example use VCF variant format without genotype, and other formats are also supported!

Note  All files were included in the examples folder of cepip.

Run the command below:

We now walk through the parameter file "params.composite.example.txt" before going into the results. Lines starting with hash sign # are comments. Detailed interpretation for each argument in the parameter file is included in 'Options' part.

#one argument per line
#I.Environmental setting
#--no-resource-check \

#II. Specify the input files
--vcf-file examples/example.vcf \

#III. Output setting
--out example_result \

#IV. Filtering and Prioritization
--db-score dbncfp \
--regulatory-causing-predict all \
--cell GM12878 \

Part (I): Specify general environmental setting

Arguments in this part are used to set general cepip running environment, including resource path and program update

Part (II): Specify the input files

Arguments in this part are used to specify the input files which support various data format, and they are compulsory for running cepip.

Part (III): Output setting

Arguments in this part are used to set the output file name and type, which can be produced simultaneously by cepip.

Part (IV): Prioritization

Arguments in this part are used to apply a set of models (selected regulatory variant scores, cell type definition, etc.) to enable better prioritization of the regulatory.

Notes Most of the above arguments are optional, so user can mask some lines by # or delete the lines. Under this circumstance, user can have a systematic view of the impact for each level or even steps. And it will be easier to produce this parameter file by cepip command generator we provide.

Input formats

Variants file

In addition, cepip also support other popular variants and/or genotypes formats which are popular in next generation studies.

ANNOVAR format java -jar cepip.jar --annovar-file path/to/file NOTE cepip can recognize an extended ANNOVAR format in which a head row and and multiple columns for comments are allowed.

Example:
chr startpos endpos ref alt comment1 comment2 comment3
1 69428 69428 T G T 92 129
1 69476 69476 T C T 1 0

Outputs

cepip can flexibly output different formats of the prioritization and annotation results for either final validation or further analysis by third-party tools.

Output file path and file name prefix: --outjava -jar cepip.jar --vcf-file path/to/file1 --out path/to/prefixname Specify path and prefix name of outputs. It is "./cepip" by default.

Odinary outputs

Text format: This is by defaultjava -jar cepip.jar --vcf-file path/to/file1 By default, cepip output results in TEXT format in a file named cepip.flt.txt, in which the fields (or columns) are delimited by the tabs.

Produce SeattleSeq input: --o-seattleseq java -jar cepip.jar --vcf-file path/to/file1 --o-seattleseq Generate an extra copy of output for the prioritized variants in SeattleSeq input format, which can be further annotated by SeattleSeq.

Produce ANNOVAR input: --o-annovar java -jar cepip.jar --vcf-file path/to/file1 --o-annovar Generate an extra copy of output for the prioritized variants in ANNOVAR input format, which can be further annotated by ANNOVAR.

Produce VCF input: --o-vcf java -jar cepip.jar --vcf-file path/to/file1 --o-vcf Generate an extra copy of output for the prioritized variants in VCF format, which can be further analyzed by other tools.

Prediction and Prioritization

Predicting noncoding regulatory variants based on specific condition

Notecepip also support context-dependent prioritization using cell type-specific epigenomic signature.

Predict regulatory variants : --db-score dbncfp --regulatory-causing-predict all --cell
java -jar cepip.jar --vcf-file path/to/file1 --db-score dbncfp --regulatory-causing-predict all --cell GM12878 Assigning a cell type, cepip uses a logit model to measure the probability of regulatory causality for given variants in selected condition. It finally combine the above composite model and context-dependent model into an unified model to estimate the posterior probability of regulatory potential.

cepip can support 16 ENCODE cell types as follows:

cepip can also support 127 RoadMap human reference epigenomes:

The option will append cell type-specifc regulatory potential (Cell_P) and combined probability (Combine_P) to the output file:

Adjust prediction scores in composite model

Notecepip allows to adjust prediction score in the composite, including CADD, DANN, fathmm-MKL, FunSeq, FunSeq2, GWAS3D, GWAVA and SuRFR. Here named "dbncfp" database.

Predict regulatory variants: --db-score dbncfp --regulatory-causing-predict
java -jar cepip.jar --vcf-file path/to/file1 --db-score dbncfp --regulatory-causing-predict 1,3,4,5,6,8,10,11 Use at most 8 existing algorithms for 11 available functional impact scores (listed below) to RE-predict whether a single nucleotide variant (SNV) or Indel will potentially be regulatory. By default, cepip uses all algorithms (8 scores) for a combinatorial prediction. However, the iterative searching shows the best combination for 4 scores can achieve top performance (CADD_cscore, GWAS3D, SuRFR, GWAVA_TSS). Figure: Receiver operating characteristic (ROC) and area under the curves (AUC) of individual scores and combined score by composite model
Note: Figures from our paper.

On the other hand, one can FIX the prediction using a specified subset or full set of the 4 impact scores by option like --regulatory-causing-predict 1,6,8,10
The coding for the functional impact scores used in'--regulatory-causing-predict' options is listed below:

The option will append the corresponding score of selected prediction methods to the output file, as well as the bayes factor (BF) and composite probability (Composite_P):

Custom annotations

cepip also supports custom annotations which are defined by user. We suggest the user prepare all chromatin features that was used in our prediction model including DNase, H3K4me1, H3K4me2, H3K4me3, H3K36me3, H3K9me3, H3K79me2, H3K27me3. If the user can not provide certain marks, cepip also require to keep empty files with fixed nomination. To use this custom annotations function, please following instructions:

1. The annotation should be sorted ENCODE narrowPeak format (https://genome.ucsc.edu/FAQ/FAQformat#format12);
2. The annotation file should start with the tissue/cell type name (eg. cellA) and append with "-[MarkName].narrowPeak.sorted", such as "cellA-DNase.narrowPeak.sorted";
3. Using gunzip to compress the above narrowPeak file. The final annotation file for certain mark in specific cell is "cellA-DNase.narrowPeak.sorted.gz";
4. All required mark gz files should be prepared for each custom tissue/cell type, including DNase, H3K4me1, H3K4me2, H3K4me3, H3K36me3, H3K9me3, H3K79me2 and H3K27me,3 even if some mark are not available currently (compress empty narrowPeak file for unavailable marks).
5. Please put all mark gz files into the cepip annotation reource folder, which locates in "[cepip path]/resources/hg19/all_cell_signal/";
6. We currently only support hg19.

cepip_PL whole genome all possible SNVs cell type-specific scoring without downloading huge annotations

Command line:perl cepip_PL.pl -i examples/example.vcf -f vcf -t /usr/bin/tabix -r ftp://147.8.193.36/PRVCS/v1.1/dbNCFP_whole_genome_SNVs.bgz -s 1,3,4,5,6,8,10,11 -a ftp://147.8.193.36/cepip/cell_signal/ -c HepG2 -o cepip.out By default, cepip use Tabix to visit remote compiled dataset for random access. You have to install Tabix and assign the progaram path to script by "-t".

Options: cepip_PL.pl -- Perl version of cepip for prediction cell type-specific regulatory variant -h output help information to screen -i the input variants file -f the format of input file, supporting VCF and ANNOVAR format; default: vcf -t the path of executable tabix program; default: /user/bin/tabix -r the path of dbNCFP reference database; default: ftp://147.8.193.36/PRVCS/v1.1/dbNCFP_whole_genome_SNVs.bgz -s the selected tool scores; default: 1,3,4,5,6,8,10,11 1 CADD_cscore 2 CADD_PHRED 3 DANN_score 4 FunSeq_score 5 FunSeq2_score 6 GWAS3D_score 7 GWAVA_region_score 8 GWAVA_TSS_score 9 GWAVA_unmatched_score 10 SuRFR_score 11 Fathmm_MKL_score -p the casual distribution folder; default: resources/all_causal_distribution -n the neutral distribution folder; default: resources/all_neutral_distribution -a the path of tissue/cell type reference epigenome; default: ftp://147.8.193.36/cepip/cell_signal/ -c the dependent tissue/cell type; default: E116 -o the path of output file; default: cepip1.flt.txt

FAQ?

1) Why cepip does not read my VCF file?

If you use standard VCF output from GATK pipeline, it usually contains variants on mitochondrial DNA. However, mitochondrial DNA is not annotated by gene feature database. Therefore cepip currently only accept VCF file excluding variants on ChrM.

2) Whether cepip supports rare variants or somatic variants?

Our composite model only supports the genetic variants from 1000 Genomes Project phase 1 since we currently prefer to make all collected eight methods work well. We will support all possible SNVs in the human genome very soon. For context-dependent model, it can be apply to any variants in the human genome.

3) Can I use ANNOVAR and cepip together on my dataset?

cepip is quite flexible for interacting with other sequence-oriented analytical programs/software (including SamTools, ANNOVAR, etc). It can accept various input formats, and output different kinds of sequence data. In case of ANNOVAR, cepip can read ANNOVAR-formatted sequence variants, and write the final remaining variants in ANNOVAR format.

4) Can I run cepip on my laptop? Is it time consuming to run a complete cepip process?

Normally, cepip run well and fast with >=1 GB RAM memory. Hence current laptop are certainty affordable for running cepip. The whole process need only <10 minutes, unless first downloading time.

5) How do I report an error or bugs to cepip?

You are welcomed to write an email to mulin0424.li@gmail.com or limx54@yahoo.com.