Package: peakachu
NOTE:Peakachu (version>=1.1.2) now supports both.hicand.coolformats.IntroductionAccurately predicting chromatin loops from genome-wide interaction matrices such as Hi-C data is critical to deepening our understanding of proper gene regulation. Current approaches are mainly focused on searching for statistically enriched dots on a genome-wide map. However, given the availability of orthogonal data types such as ChIA-PET, HiChIP, Capture Hi-C, and high-throughput imaging, a supervised learning approach could facilitate the discovery of a comprehensive set of chromatin interactions. Here, we present Peakachu, a Random Forest classification framework that predicts chromatin loops from genome-wide contact maps. We compare Peakachu with current enrichment-based approaches, and find that Peakachu identifies a unique set of short-range interactions. We show that our models perform well in different platforms, across different sequencing depths, and across different species. We apply this framework to predict chromatin loops in 56 Hi-C datasets, and release the results at the 3D Genome Browser.CitationSalameh, T.J., Wang, X., Song, F. et al. A supervised learning framework for chromatin loop detection in genome-wide contact maps. Nat Commun 11, 3428 (2020).https://doi.org/10.1038/s41467-020-17239-9InstallationPeakachu requires Python3 and several scientific packages to run. It is best to first set up the environment using conda and then install Peakachu fromPyPI:condaconfig--addchannelsdefaults
condaconfig--addchannelsbioconda
condaconfig--addchannelsconda-forge
condacreate-npeakachucoolernumbascikit-learn=1.1.2joblib=1.1.0
condaactivatepeakachu
pipinstall-Upeakachuhic-straw==0.0.6Peakachu should now be installed as a command-line tool within the new environment. Options for all peakachu commands and sub-commands can be accessed with the -h option.peakachu-husage: peakachu [-h] {train,score_chromosome,score_genome,depth,pool} ...

Unveil Hi-C Anchors and Peaks.

positional arguments:
  {train,score_chromosome,score_genome,depth,pool}
    train               Train RandomForest model per chromosome
    score_chromosome    Calculate interaction probability per pixel for a chromosome
    score_genome        Calculate interaction probability per pixel for the whole genome
    depth               Calculate the total number of intra-chromosomal chromatin contacts and select the most appropriate pre-trained model
                        for you.
    pool                Print centroid loci from score_genome/score_chromosome output

options:
  -h, --help            show this help message and exitExample: predicting loops in GM12878 Hi-CThe following example will download an example cooler file containing the GM12878 Hi-C data at the 10kb resolution, train a series of models using H3K27ac HiChIP interactions, and then predict loops using the trained models.Data preparationPeakachu requires the contact map to be a .cool file or a .hic file and any training input to be a text file in bedpe format. Example training data can be found at thetraining-setssubfolder. Cooler files may be found at the4DN data portal.wgethttp://3dgenome.fsm.northwestern.edu/peakachu/test_file/Rao2014-GM12878-MboI-allreps-filtered.10kb.coolTrain a model and predict loopsIt is always a good idea to call the help function immediately before entering a command:peakachutrain-husage: peakachu train [-h] [-r RESOLUTION] [-p PATH] [--balance] [-b BEDPE] [-w WIDTH] [--nproc NPROC] [-O OUTPUT]

options:
  -h, --help            show this help message and exit
  -r RESOLUTION, --resolution RESOLUTION
                        Resolution in bp (default 10000)
  -p PATH, --path PATH  Path to a .cool URI string or a .hic file.
  --balance             Whether or not using the ICE/KR-balanced matrix.
  -b BEDPE, --bedpe BEDPE
                        Path to the bedpe file containing positive training set.
  -w WIDTH, --width WIDTH
                        Number of bins added to center of window. default width=5 corresponds to 11x11 windows
  --nproc NPROC         Number of worker processes that will be allocated for training. (default 4)
  -O OUTPUT, --output OUTPUT
                        Folder path to store trained models.peakachutrain-r10000-pRao2014-GM12878-MboI-allreps-filtered.10kb.cool--balance-Omodels-bgm12878.mumbach.h3k27ac-hichip.hg19.bedpeThis will train 23 random forest models, each labeled by a chromosome. The model for every chromosome
was trained using interactions from all the other 22 chromosomes in the provided bedpe file. The purpose of this is to avoid Peakachu to predict loops from the same map it used for training, without overfitting. To use these models, you may either use the score_chromosome function to predict loops in only one chromosome, or the score_genome function to perform a genome-wide prediction.peakachuscore_chromosome-husage: peakachu score_chromosome [-h] [-r RESOLUTION] [-p PATH] [--balance] [-C CHROM] [-m MODEL] [-l LOWER] [-u UPPER]
                             [--minimum-prob MINIMUM_PROB] [-O OUTPUT]

options:
  -h, --help            show this help message and exit
  -r RESOLUTION, --resolution RESOLUTION
                        Resolution in bp (default 10000)
  -p PATH, --path PATH  Path to a .cool URI string or a .hic file.
  --balance             Whether or not using the ICE/KR-balanced matrix.
  -C CHROM, --chrom CHROM
                        Chromosome label. Only contact data within the specified chromosome will be considered.
  -m MODEL, --model MODEL
                        Path to pickled model file.
  -l LOWER, --lower LOWER
                        Lower bound of distance between loci in bins (default 6).
  -u UPPER, --upper UPPER
                        Upper bound of distance between loci in bins (default 300).
  --minimum-prob MINIMUM_PROB
                        Only output pixels with probability score greater than this value (default 0.5)
  -O OUTPUT, --output OUTPUT
                        Output file name.peakachuscore_chromosome-r10000-pRao2014-GM12878-MboI-allreps-filtered.10kb.cool--balance-OGM12878-chr2-scores.bedpe-Cchr2-mmodels/chr2.pklpeakachupool-r10000-iGM12878-chr2-scores.bedpe-oGM12878-chr2-loops.bedpe-t.9The pool function serves to select the most significant non-redundant results from per-pixel probabilities calculated by the score functions. It is recommended to try different probability thresholds to achieve the best sensitivity-specificity tradeoff. The output is a standard bedpe file with the 7th and the final column containing the predicted probability from the random forest model and the interaction frequency extracted from the contact matrix, respectively, to support further filtering. The results can be visualized injuiceboxorhiglassby loading as 2D annotations. Here is an example screenshot of predicted GM12878 loops in juicer:Using Peakachu as a standard loop callerModels for predicting loops in Hi-C have been trained using CTCF ChIA-PET interactions, H3K27ac HiChIP interactions, and a high-confidence loop set (loops that can be detected by at least two orthogonal methods from CTCF ChIA-PET, Pol2 ChIA-PET, Hi-C, CTCF HiChIP, H3K27ac HiChIP, SMC1A HiChIP, H3K4me3 PLAC-Seq, and TrAC-Loop) as positive training samples, at a variety of read depths. Simply download the appropriate model file and directly run the score_genome/score_chromosome function if you want to detect chromatin loops on your own Hi-C or Micro-C maps.If you are using Peakachu>=2.0, please select a model from the following table:Total intra readshigh-confidence (5kb)high-confidence (10kb)high-confidence (25kb)2 billiontotal 5kbtotal 10kbtotal 25kb1.8 billion90% 5kb90% 10kb90% 25kb1.6 billion80% 5kb80% 10kb80% 25kb1.4 billion70% 5kb70% 10kb70% 25kb1.2 billion60% 5kb60% 10kb60% 25kb1 billion50% 5kb50% 10kb50% 25kb900 million45% 5kb45% 10kb45% 25kb850 million42.5% 5kb42.5% 10kb42.5% 25kb800 million40% 5kb40% 10kb40% 25kb750 million37.5% 5kb37.5% 10kb37.5% 25kb700 million35% 5kb35% 10kb35% 25kb650 million32.5% 5kb32.5% 10kb32.5% 25kb600 million30% 5kb30% 10kb30% 25kb550 million27.5% 5kb27.5% 10kb27.5% 25kb500 million25% 5kb25% 10kb25% 25kb450 million22.5% 5kb22.5% 10kb22.5% 25kb400 million20% 5kb20% 10kb20% 25kb350 million17.5% 5kb17.5% 10kb17.5% 25kb300 million15% 5kb15% 10kb15% 25kb250 million12.5% 5kb12.5% 10kb12.5% 25kb200 million10% 5kb10% 10kb10% 25kb150 million7.5% 5kb7.5% 10kb7.5% 25kb100 million5% 5kb5% 10kb5% 25kb50 million2.5% 5kb2.5% 10kb2.5% 25kb30 million1.5% 5kb1.5% 10kb1.5% 25kb10 million0.5% 5kb0.5% 10kb0.5% 25kb5 million0.25% 5kb0.25% 10kb0.25% 25kbInstead, if you are using an older Peakachu version (<2.0), please select a model
from this table:Total   intra readsCTCF Models (10kb)H3K27ac Model (10kb)2   billionCTCF   totalH3K27ac   total1.8   billionCTCF   90%H3K27ac   90%1.6   billionCTCF   80%H3K27ac   80%1.4   billionCTCF   70%H3K27ac   70%1.2   billionCTCF   60%H3K27ac   60%1   billionCTCF   50%H3K27ac   50%800   millionCTCF   40%H3K27ac   40%600   millionCTCF   30%H3K27ac   30%400   millionCTCF   20%H3K27ac   20%200   millionCTCF   10%H3K27ac   10%30   millionCTCF   1.5%H3K27ac   1.5%To make it clear, let's download another Hi-C dataset:wget-OSKNAS-MboI-allReps-filtered.mcool-Lhttps://www.dropbox.com/s/f80bgn11d7wfgq8/SKNAS-MboI-allReps-filtered.mcool?dl=0Peakachu provides a handy functionpeakachu depthto extract the total number of intra-chromosomal pairs in your data and help you select the most appropriate pre-trained model:peakachudepth-pSKNAS-MboI-allReps-filtered.mcool::resolutions/1000000The output of above command will be:num of intra reads in your data: 141955751
num of intra reads in a human with matched sequencing coverage: 139325229
suggested model: 150 millionTherefore, we recommend using the 7.5% models (trained with ~150 million intra reads)
to predict loops on this data.peakachuscore_genome-r10000--balance-pSKNAS-MboI-allReps-filtered.mcool::resolutions/10000-OSKNAS-peakachu-10kb-scores.bedpe-mhigh-confidence.150million.10kb.w6.pkl
peakachupool-r10000-iSKNAS-peakachu-10kb-scores.bedpe-oSKNAS-peakachu-10kb-loops.0.95.bedpe-t0.95Not just Hi-CIn addition to Hi-C, Peakachu has also been trained on other 3D genomic platforms with good results, including Micrco-C (Krietenstein et al. 2020), DNA SPRITE (Quinodoz et al. 2018), ChIA-PET (Fullwood et al. 2009), HiChIP (Mumbach et al. 2016), TrAC-loop (Lai et al. 2018), and HiCAR (Wei et al. 2022), etc.If you want to predict loops on HiCAR contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and a series of downsampled versions of a HiCAR dataset in H1ESC cells. As these models were trained using the raw contact values (rather than the ICE-normalized contact values as we did for Hi-C), pleasedo notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models300   million300   million300   million275   million275   million275   million250   million250   million250   million225   million225   million225   million200   million200   million200   million175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict loops on TrAC-loop contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and a series of downsampled versions of a TrAC-loop dataset in H1ESC cells. Again,do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict chromatin loops on CTCF ChIA-PET contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and downsampled versions of a CTCF ChIA-PET dataset in H1ESC cells.Do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models275   million275   million275   million250   million250   million250   million225   million225   million225   million200   million200   million200   million175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict loops on Pol2 (RNA Polymerase II) ChIA-PET contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and downsampled versions of a Pol2 ChIA-PET dataset in WTC11 cells.Do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models200   million200   million200   million175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict loops on H3K27ac HiChIP/PLAC-Seq contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and downsampled versions of a H3K27ac HiChIP dataset in GM12878 cells.Do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models275   million275   million275   million250   million250   million250   million225   million225   million225   million200   million200   million200   million175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict loops on H3K4me3 HiChIP/PLAC-Seq contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and downsampled versions of a H3K4me3 PLAC-Seq dataset in GM12878 cells.Do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict loops on CTCF HiChIP/PLAC-Seq contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and downsampled versions of a CTCF HiChIP dataset in GM12878 cells.Do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models200   million200   million200   million175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionIf you want to predict loops on SMC1A HiChIP/PLAC-Seq contact matrices, please select a model from the following table. The models were trained with a high-confidence loop set and downsampled versions of a SMC1A HiChIP dataset in GM12878 cells.Do notspecify "--balance" when you run "peakachu score_genome" or "peakachu score_chromosome".2kb models5kb models10kb models225   million225   million225   million200   million200   million200   million175   million175   million175   million150   million150   million150   million125   million125   million125   million100   million100   million100   million90   million90   million90   million80   million80   million80   million70   million70   million70   million60   million60   million60   million50   million50   million50   million40   million40   million40   million30   million30   million30   million20   million20   million20   million10   million10   million10   millionRelease NotesVersion 2.1 (11/28/2022)Fixed a bug regarding model training using the raw contact valuesVersion 2.0 (09/06/2022)Re-trained the models using the latest scikit-learn v1.1.2Used the distance-normalized signals instead of original contact signalsAdded a 2D Gaussian filter followed by min-max scaling to pre-process each training imageOptimized the computation efficiency using numba and matrix operations.