Package: looppredictor
Predicting unrecognized enhancer-mediated genome topology by an ensemble machine learning modelContentsWhat can LoopPredictor do?Installation1. Create conda environment2. Install LoopPredictorExample usage1. Classifying loops for known chromatin interaction2. Predicting loops for unknown cell types3. Customize model for extensive researchWhat can LoopPredictor do?LoopPredictor is an ensemble machine learning model, used to predict enhancer mediated loops in a genome-wide fashion across different cell lines, which is also applicable to different model organisms.Annotate current chromatin interactions and classify the loops into "e-p", "e-e", "p-p" and inactivate types through integrating the enrichment of active/inactive histone mark and distance to Transcription Start Sites(TSS), Which helped users to have a keen insight into topology structure of known cell type.Predict chromatin interactions for the unknown cell types which lack of 3D profile, LoopPredictor was trained by HiChIP and multi-omics datasets from three cell types (K562, GM12878, HCT116), users only need to feed the multi-omics features of interested cell type into the pre-trained adaptive model, the sensitive predictions helped users to have a preliminary investigation of unknown chromatin interaction.Construct customized models for an extensive prediction research. As 3D chromatin detecting technologies are developing at a high speed, LoopPredictor provided an open workframe for users to construct their own model, the features and targets could be organized as user-defined, and the self-adaptive parameters wil be chosen to tarin the model. After training, users can use the customized model to predict the topology structure of interest.InstallationLoopPrediction is built on Python 3 and R 3.6.2. Homer is also needed for the annotation of chromatin regions.Prerequisites:Python(>=3.4.0),R(>=3.6.2),HomerDependencies:python packages:pandas,numpy,scikit-learn,pathosR packages:stringr,GenomicRanges,TxDb.Hsapiens(download the corresponding TxDb package for the species you want to predict)1. Create conda environmentThe virtual environment of conda was recommended for the installation of LoopPredictor and its dependencies. A virtual environment can be created and (de)activated as follows by usingconda:# createcondacreate-nLoopPredictor-envpython=3.6pandasnumpyscikit-learn=0.20.3pathos# activatecondaactivateLoopPredictor-env# deactivatecondadeactivateThe virtual environment can also be created by usingvirtualenv.2. Install LoopPredictorAfter creating and activating the environment, download and install LoopPredictor (lastest version) from github:gitclonehttps://github.com/bioinfomaticsCSU/LoopPredictor.gitcdLoopPredictor
pythonsetup.pyinstallOr install LoopPredictor usingpip:pipinstalllooppredictorExample usage1. Classifying loops for known chromatin interactionThe testing data were available in /example/K562_classification_example. The structure of folder was shown as below, two kinds of necessary files need to be prepared as input, and the classification results will be *_Output.txt.example/K562_classification_example/featureData/# [necessary input]features of corresonding cell line input for the classificationtmp/# [intermediate]temporary files generated within runninglog/# [intermediate]log files generated within running*.bedpe# [necessary input]loops file with .bedpe format*_Output.txt# [output]results of loops classificationStep1: Prepare featureData filesThe classification was taken by the integration of active/inactive histone mark, so the corresonding ChIP-seq peaks of H3K27ac, H3K4me1, and H3K4me3 were the basic requirement. The peak files should be the standard ENCODEnarrowPeak/broadPeakfile without head line, shown as below, which were listed in the folder /example/K562_classification_exampleas/featureData.chr221684344516868802.322.2.12058213.1-1
chr221702479317024896.985.11.4834292.8-1
chr221703842417038594.854.9.6336105.0-1
chr221705004417050593.465.4.1431742.0-1
chr221705041817050537.984.11.4685834.2-1
chr221706639217067403.892.10.16934014.8-1
chr221706795917068242.878.9.96645613.3-1
chr221706865217068827.835.9.3583644.9-1Step2: Prepare loops fileThe loops file should be .bedpe format with at least 6 columns, columns were seperated by tab. The minimum columns should include the chrom name, start, end of each anchor, shown as below.chr223829051438294289chr223868060938682339chr59603360596042289chr59625919096260539chr12366519423673403chr12409753624108995chr3176676833176679516chr3176741264176748850chr116360413263609924chr116375169363756217chr173700556337012402chr173880132438806978chr3138311141138315068chr3138482903138484460chr11126078482126084019chr11126210767126227804Step3: Running classificationThe parameters of the script are as following,classifyloops-l<loops>-f<featurePath>-g<genome>-o<output_name>-i<integer>
-l[string]loopfilewith./bedpeformattobeclassified.
-f[string]absolutepathofthefeatureDatafolder.
-g[string]genomeofloops.
-o[string]pathtosavetheoutputresult.-i[integer(1-5)]1.Outputalltypesofloopswithoutfiltering;2.Outputonly"e-p"/"p-e"typeloops;3.Outputonly"e-e"typeloops;4.Outputonly"p-p"typeloops;5.Outputonly"inactivate-*"/"*-inativate"typeloops;Here is a running example:classifyloops-l/path/to/example/K562_classification_example/K562_classifyLoop_example.bedpe\-f/path/to/example/K562_classification_example/featureData\-o/path/to/example/K562_classification_example-ghg19-i12. Predicting loops for unknown cell typesThe testing data were available in /example/NIH3T3_prediction_example. The structure of folder was shown as below, the featureData is the necessary input for the prediction, and if you want to investigate the topology structures of a set of specific genes, a bed file containing the regions of genes could be provided. If there is no bed file inputing, the prediction will be performed for the whole genome in de novo, which will take some time.example/NIH3T3_prediction_example/featureData/# [necessary input]features of corresonding cell line input for the predictiontmp3/# [intermediate]temporary files generated within runninglog/# [intermediate]log files generated within running*.bed# [optional input]input bed file of interested regions for loops predictionfeature_out.txt# [intermediate]features are extracted from files within running*predicted_result.bedpe# [output]predicted results of loopsStep1: Choose the proper pre-trained modelWe provided three typical pre-trained model for the prediction, which could be found in folder /trained_model/. The model should be chosen to match the features you can get access to.pre-trained modelmulti-omics features requirementMinimum model-ATAC-seq, -ChIP-seq/CUT&RUN(H3K27ac,H3K4me3)Median model-ATAC-seq, -ChIP-seq/CUT&RUN(H3K27ac,H3K4me3,H3K4me1,H3K9ac,H3K9me3,CTCF), -RNA-seqMaximum model-ATAC-seq, -ChIP-seq/CUT&RUN(H3K27ac,H3K4me3,H3k4me2,H3K4me1,H3K9ac,H3K9me3,H3K36me3,H3K79me2,CTCF,ELF1,JUND,MAX,YY1), -RNA-seq, -MethylationStep2: Prepare the input featuresThe multi-omics features data should be put into folder featureData/.
For ATAC-seq and ChIP-seq/CUT&RUN data, the format should be standardnarrowPeak/broadPeak, as shown above.
For RNA-seq data, we recommend to useHomerto build
tag files for the alignment, and then "findPeaks" function is utilized to detect the highly enriched regions, the output from "findPeaks" can be used as the feature file of RNA-seq data after removing the head line.
For Methylation data, we recommend to download the .bedRrbs format of RRBS data fromENCODE,
which is shown as below,chr110001701000171K562_Rep3_RRBS46+10001701000171155,255,04635chr110001901000191K562_Rep3_RRBS46+10001901000191105,255,04615chr110001911000192K562_Rep3_RRBS53-1000191100019255,255,0539chr110001981000199K562_Rep3_RRBS46+10001981000199105,255,04620chr110001991000200K562_Rep3_RRBS53-10001991000200105,255,05315chr110002061000207K562_Rep3_RRBS53-10002061000207155,255,05326Step3: Prepare the interested gene file (optional)If you want to detect the enhancer-mediated interactions for a set of interested gene, we recommend to extract the name of genes to the coordinates on the chromatin byUCSC Table Browser. The coordinates should be ./bed format with at least 3 columns(chrom,start,end).Step4: Running predictionAfter preparing the input files, you can run the script "LoopPredictor.py" to perform the prediction.
The parameters of the script are as following,looppredictor-b<bedfile>-f<featurePath>-g<genome>-t<trainfile>-m<model>-c<cutoff>-o<output_name>
-b[string]coordinate.bedfileofasetofinterestedgenes.
-f[string]absolutepathofthefeatureDatafolder.
-g[string]genomeofthefeaturesdata.
-t[string].fixfileforthepre-trainedmodel.
-m[string]thepre-trainedmodelchosentouse.
-c[integer(>0)]thecutoffofloopscoretofilterthepredictedoutputloops.-o[string]pathtosavetheoutputresult.Here is a running example:looppredictor-b/path/to/example/NIH3T3_prediction_example/NIH_geneEnh_example.bed\-f/path/to/example/NIH3T3_prediction_example/featureData\-gmm10\-t/path/to/trained_model/features_median_forTraining.fix\-m/path/to/trained_model/GBRT_trained_model_median.m\-c1\-o/path/to/example/NIH3T3_prediction_example3. Customize model for extensive researchStep1: prepare trianing dataThe training data contains target and multi-omics data, target file shoule be the chromatin interactions in ./bedpe format, which is the prior knowledge to train the model. The target file should be 8 columns without head line, the final column must be the score of interaction, which is important for the prediction, shown as below,chr177511567675125670chr177673170976734226loop_name_11chr125664993556654417chr125686047856865446loop_name_217chr185302697353030447chr185430252754308273loop_name_32chr101564468715646877chr101582576015862181loop_name_47chr213543925035465483chr213669351736722679loop_name_53The multi-omics data for the corresponding cell line should be prepared in the featureData/ folder as mentionedabove.Step2: Running training workflowAfter preparing the input training data, you can run the script "Customized_GBRT_trainer.py" to train your own model.
The parameters of the script are as following,customized_gbrt_trainer-t<trainfile>-f<feature>-g<genome>-o<output_path>-n<output_name>
-t[string]targetfileofasetofloopswithscoretotrainthemodel,whichis.bedpeformat.
-f[string]absolutepathofthefeatureDatafolder.
-g[string]genomeofthefeaturesdata.
-o[string]pathtosavetheoutputresult.
-n[string]outputnameofthemodel.Here is a running example:customized_gbrt_trainer-t/path/to/example/HCT116_custom_model_example/HCT116_custom_example.bedpe\-f/path/to/example/HCT116_custom_model_example/featureData\-ghg19\-o/path/to/example/NIH3T3_prediction_example\-nHCT116_custom_model