Package: maxatac
maxATAC: genome-scale transcription-factor binding prediction from ATAC-seq with deep neural networksIntroductionmaxATAC is a Python package for transcription factor (TF) binding prediction from ATAC-seq signal and DNA sequence inhumancell types. maxATAC works with both population-level (bulk) ATAC-seq and pseudobulk ATAC-seq profiles derived from single-cell (sc)ATAC-seq. maxATAC makes TF binding site (TFBS) predictions at 32 bp resolution.
maxATAC requires three inputs:DNA sequence, in.2bitfile format.ATAC-seq signal, processed as describedbelow.Trained maxATAC TF Models, in.h5file format.maxATAC was trained and evaluated on data generated using the hg38 reference genome. The default paths and files that are used for each function will reference hg38 files. If you want to use maxATAC with any other species or reference, you will need to provide the appropriate chromosome sizes file, blacklist, and.2bitfile specific to your data.InstallationIt is best to install maxATAC into a dedicated virtual environment.This version requires python 3.9,bedtools,samtools,pigz,wget,git,graphviz, anducsc-bedgraphtobigwigin order to run all functions.The total install data requirements for maxATAC is ~2 GB.Installing with CondaCreate a conda environment for maxATAC withconda create -n maxatac -c bioconda python=3.9 samtools wget bedtools ucsc-bedgraphtobigwig pigzIf you get an error regarding graphviz while training a model, re-install graphviz withconda install graphvizInstall maxATAC withpip install maxatacTest installation withmaxatac -hDownload reference data withmaxatac dataIf you have an error related to pybigwig, reference issues:96and87Installing with python virtualenvCreate a virtual environment for maxATAC withvirtualenv -p python3.9 maxatac.Install required packages and make sure they are on your PATH: samtools, bedtools, bedGraphToBigWig, wget, git, pigz.Install maxatac withpip install maxatacTest installation withmaxatac -hDownload reference data withmaxatac dataDownloading required reference dataIn order to run the maxATAC models that were described in themaxATAC pre-print, the following files are required to be downloaded from themaxATAC_datarepository and installed in the correct directory:hg38 reference genome.2bitfilehg38 chromosome sizes filemaxATAC extended blacklistTF specific.h5model filesTF specific thresholding filesBash scripts for preparing dataThe easiest option is to use the commandmaxatac datato download the data to the required directory. Themaxatac datafunction will download the maxATAC_data repo and reference data into your~/opt/directory under~/opt/maxatac. Only the hg38 reference genome has been extensively tested.Using custom reference dataThe directory~/opt/maxatac/datais the default location where maxATAC will look for the maxATAC models, hg38 reference annotations, etc.If you want to use your own references (e.g., hg19) or models, set the appropriate flags for each file with the path to your custom files. You can also adjust the relative paths inconstants.pyto be the default values for all functions.maxATAC Quick Start OverviewSchematic: Overview of a typical maxATAC workflow. First, ATAC-seq data is prepared using the maxatac prepare function. The prepare function processes bulk and scATAC-seq into normalized signal files. The normalized signal track can then be used to make TF binding predictions for the TF of interest. The IGV screenshot shows the maxATAC-normalized ATAC-seq signal (blue) and maxATAC TFBS predictions for the FOXP1 model (magenta), predictions are represented as signal tracks (.bw, bigwig) and TFBS (.bed files), the default outputs from maxATAC.InputsDNA sequence, in.2bitfile format.ATAC-seq signal, processed as describedbelow.Trained maxATAC TF Models, in.h5file format.OutputsRaw maxATAC TFBS scores tracks in.bwfile format..bedfile of TF binding sites, thresholded according to a user-supplied confidence cut off (e.g., corresponding to an estimated precision, recall value or $log_2(precision:precision_{random} > 7$) or default ($max(F1score)$)).ATAC-seq Data RequirementsAs described in themaxATAC pre-print,maxATAC processing of ATAC-seq signal is critical to maxATAC prediction. Key maxATAC processing steps, summarized in a single commandmaxatac prepare, include identification of Tn5 cut sites from ATAC-seq fragments, ATAC-seq signal smoothing, filtering with an extended "maxATAC" blacklist, and robust, min-max-like normalization.The maxATAC models were trained on paired-end ATAC-seq data in human. For this reason, we recommend paired-end sequencing with sufficient sequencing depth (e.g., ~20M reads for bulk ATAC-seq). Until these models are benchmarked in other species, we recommend limiting their use to human ATAC-seq datasets.Preparing the ATAC-seq signalThe currentmaxatac predictfunction requires a normalized ATAC-seq signal in a bigwig format. Usemaxatac prepareto generate a normalized signal track from a.bamfile of aligned reads. Seethe prepare documentationfor more details about the expected outputs and file name descriptions.Bulk ATAC-seqThe functionmaxatac preparewas designed to take an input BAM file that has aligned to the hg38 reference genome. The inputs tomaxatac prepareare the input bam file, the output directory, and the filename prefix.maxatacprepare-iSRX2717911.bam-o./output-prefixSRX2717911-dedupThis function took 38 minutes for a sample with 52,657,164 reads in the BAM file. This was tested on a 2019 Macbook Pro with a 2.6 GHz 6-Core Intel Core i7 and 16 GB of memory.Pseudo-bulk scATAC-seqFirst, convert the.tsv.gzoutput fragments file from CellRanger into pseudo-bulk specific fragment files. Then, usemaxatac preparewith each of the fragment files in order to generate a normalized bigwig file for input intomaxatac predict.maxatacprepare-iHighLoading_GM12878.tsv-o./output-prefixHighLoading_GM12878The prediction parameters and steps are the same for scATAC-seq data after normalization.Predicting TF binding from ATAC-seqFollowing maxATAC-specific processing of ATAC-seq signal inputs, use themaxatac predictfunction to predict TF binding with a maxATAC model.TF binding predictions can be made genome-wide, for a single chromosome, or, alternatively, the user can provide a.bedfile of genomic intervals for maxATAC predictions to be made.Whole genome predictionExample command for TFBS prediction across the whole genome:maxatacpredict-tfCTCF--signalGM12878_IS_slop20_RP20M_minmax01.bw-ooutputdir/If data has been installed with maxATAC data, then the following command will use the best model and call peaks using the TF specific threshold statistics.maxatacpredict-tfCTCF-sGM12878_IS_slop20_RP20M_minmax01.bw-ooutputdir/Prediction in a specific genomic region(s)For TFBS predictions within specific regions of the genome, aBEDfile of genomic intervals,roi(regions of interest) are supplied:maxatacpredict-tfCTCF--signalGM12878_IS_slop20_RP20M_minmax01.bw--roiROI.bedPrediction on a specific chromosome(s)For TFBS predictions on a single chromosome or subset of chromosomes, these can be provided using the--chromosomesargument:maxatacpredict-tfCTCF--signalGM12878_IS_slop20_RP20M_minmax01.bw--chromosomeschr3chr5Raw signal tracks (prediction bigwigs) are largeEach output prediction file for a whole genome is ~700 MB per TF.The output bed files are ~60Mb.There are 127 TF models x ~700MB per TF model = ~88.9 GB of bigwig files for a single ATAC-seq input track. (Note: it only makes sense to generate maxATAC predicitons for TFs expressed in your cell type / conditions of interest, so this is a worst-case estimate.)maxATAC functionsSubcommandDescriptionpreparePrepare input dataaverageAverage ATAC-seq signal tracksnormalizeMinmax normalize ATAC-seq signal trackstrainTrain a modelpredictPredict TF bindingbenchmarkBenchmark maxATAC predictions against ChIP-seqpeaksCall "peaks" on maxATAC signal tracksvariantsPredict sequence specific TF bindingPublicationThe maxATAC manuscript is available onPLoS Computational Biology.Tareian Cazares, Faiz W. Rizvi, Balaji Iyer, Xiaoting Chen, Michael Kotliar, Joseph A. Wayman, Anthony Bejjani, Omer Donmez, Benjamin Wronowski, Sreeja Parameswaran, Leah C. Kottyan, Artem Barski, Matthew T. Weirauch, VB Surya Prasath, Emily R. Miraldi (2023) maxATAC: Genome-scale transcription-factor binding prediction from ATAC-seq with deep neural networks. PLoS Comput Biol 19(1): e1010863. https://doi.org/10.1371/journal.pcbi.1010863