TITLE: Processing Bulk Calling Card Sequencing Data
AUTHORS: Arnav Moudgil, Rob Mitra

[DESCRIPTION]
<div class = "text-blocks"><div class = "text-block"><span>Here we present a computational pipeline for processing bulk RNA calling card data. These data will have been generated from transfection/-duction of either undirected </span><span style = "font-style:italic;">piggyBac</span><span> transposase or your favorite transcription factor (YFTF) fused to </span><span style = "font-style:italic;">piggyBac</span><span>. Multiple biological replicates should have been generated, each with a unique combination of primer barcode and index sequences. This workflow demonstrates how to analyze a single replicate; the workflow can be parallelized on distributed computing architectures (e.g. slurm).</span></div></div>

[STEPS]
?. [Preamble]
To illustrate the workflow, let's say that we have performed bulk RNA calling cards on our favorite transcription factor (YFTF) in a human cell line. We have prepared libraries from 10 biological replicates of cells transfected with wild-type piggyBac transposase, and 10 replicates of cells with YFTF-piggyBac. We have sequenced these libraries and now need to map these insertions across the genome.We will consider a single replicate; the workflow can then be repeated for all remaining replicates. At the end we can combine the data from the 10 piggyBac replicates, and the 10 YFTF-piggyBac replicates, respectively, into a single CCF file each.
?. [Preamble]
In this example, we will be analyzing a single replicate from the wild-type piggyBac libraries: PBase_rep1. The read 1 sequencing file is PBase_rep1_L001_R1_001.fastq.gzThis biological replicate had GAT as its primer barcode and CTCACGGTGA as its index sequence. It was prepared by PCR ligation with the following primers:>OM-PB-GAT (barcode in bolded)AATGATACGGCGACCACCGAGATCTACACTCTTTCCCTACACGACGCTCTTCCGATCTGATTTTACGCAGACTATCTTTCTAG>Nextera_N7_CTCACGGTGA (index in bold; note the reverse complement orientation)CAAGCAGAAGACGGCATACGAGATTCACCGTGAGGTCTCGTGGGCTCGGThus, each read 1 should begin with GATTTTACGCAGACTATCTTTCTAG.
For bulk RNA calling card libraries, only read 1 is analyzed, as it contains the junction between the transposon and genome.
?. [Adapter Trimming]
The purpose of this step is to check that reads have (1) the appropriate primer barcode sequence and (2) the transposon sequence is correct and ends in TTAA, piggyBac's insertion motif. If these conditions are true, those bases are trimmed (hard clipped), to facilitate genomic alignment. Only reads with perfect matches to the barcode and transposon sequence are carried forward.cutadapt \    -g ^GATTTTACGCAGACTATCTTTCTAGGGTTAA \    --minimum-length 1 \    --discard-untrimmed \    -e 0 \    --no-indels \    -o PBase_rep1_trimBC.fastq.gz \    PBase_rep1_L001_R1_001.fastq.gzTypically 70-90% of reads will pass this filter, although there may be sample-dependent variation.
?. [Adapter Trimming]
Next, we re-examine the passing reads and trim any reads that end in the Nextera adapter that was added during tagmentation. This step reduces the amount of non-genomic bases, which should accelerate alignment. Only a small fraction (5-10%) typically have any adapter sequence at all, so virtually every read will pass this filter.cutadapt \    -a CTGTCTCTTATACACATCTCCGAGCCCACGAGACTCTCACGGTGATCTCGTATGCCGTCTTCTGCTTG \    --minimum-length 1 \    -o PBase_rep1_trimmed.fastq.gz \    Base_rep1_trimBC.fastq.gzThe index sequence has been emphasized in bold, but if you are processing libraries with many index different indexes, you can replace the bolded sequence with N's (keeping the length same). cutadapt can handle degenerate bases in adapters.
?. [Alignment]
Now that our reads are trimmed, we are ready to align them to the genome. This step can be done with any aligner; we typically use novoalign, so that is what we will demonstrate here.novoalign \    -d hg38.nvx \    -f PBase_rep1_trimmed.fastq.gz \    -n 40 \    -o SAM \    -o SoftClip > PBase_rep1_trimmed.samThe "-n 40" flag tells novoalign to align only the first 40 bases of the read. We have found that this reduction can increase the speed of alignment with minimal impact on total number of insertions recovered. Faster aligners (e.g. bowtie2, GATK, STAR) may not need this setting.
?. [Annotation]
The BAM format provides a flexible way to annotate reads through the use of short tags. These tags remain with the reads in the BAM file, which makes for a simple and portable archive of a calling card experiment. We use the following custom tags:XP: primer barcodeXJ: index 1 sequenceXK: index 2 sequence (optional; reserved for future use)XI: insertion site annotationXZ: adjacent sequence (to verify transposase motif)
?. [Annotation]
First, we will annotate reads with the XP tag for the primer barcode GAT.python TagBam.py \    --tag XP:Z:GAT \    PBase_rep1_mapped.bam \    PBase_rep1_tagged.bam
?. [Annotation]
Next, we will annotate reads with the XJ tag for the index sequence CTCACGGTGA.python TagBam.py \    --tag XJ:Z:CTCACGGTGA \    PBase_rep1_tagged.bam \    PBase_rep1_tagged2.bam
?. [Annotation]
Lastly, we will annotate reads with respect to the insertion site. This script checks each read to make sure that it maps next to the piggyBac insertion site motif TTAA. Remember, this part of read 1 was trimmed in step 4. By double checking that the read maps next to a genomic TTAA, we add an extra layer of specificity to the alignment. The sequence of the adjacent bases will also be annotated with the XZ tag. Reads that pass will be annotated with the insertion site coordinates in the XI tag and written to the output file.python AnnotateInsertionSites.py \    --transposase PB \    -f \    PBase_rep1_tagged2.bam \    hg38.2bit \    PBase_rep1_final.bamYou can provide a path to the .2bit file if your genome references are in another directory.
?. [Alignment]
After alignment, we filter out reads that mapped to multiple locations in the genome (e.g. in a repetitive element) and convert to the more space-efficient BAM format.samtools view \    -bS -h -F 260 \    PBase_rep1_trimmed.sam | \    samtools sort - -o PBase_rep1_mapped.bam
?. [Finishing Up]
To finish, we first index the BAM file.samtools index PBase_rep1_final.bamsamtools index $out_map_sort_prefix"_final.bam"
?. [Finishing Up]
Next, clean up intermediate files.rm PBase_rep1_trimBC.fastq.gzrm PBase_rep1_trimmed.fastq.gzrm PBase_rep1_trimmed.samrm PBase_rep1_mapped.bamrm PBase_rep1_tagged.bamrm PBase_rep1_tagged2.bam
?. [Notes]
This workflow described how to process a SINGLE biological replicate. After each replicate has been processed, CCF files can be combined to consolidate all insertions from a given experiment. For example, to combine data from all replicates from our wild-type piggyBac libraries, we can use cat and bedops (preferred):cat \PBase_rep1_final.ccf \PBase_rep2_final.ccf \PBase_rep3_final.ccf \PBase_rep4_final.ccf \PBase_rep5_final.ccf \PBase_rep6_final.ccf \PBase_rep7_final.ccf \PBase_rep8_final.ccf \PBase_rep9_final.ccf \PBase_rep10_final.ccf | sort-bed - > PBase.ccfSimilarly, CCFs from the YFTF replicates can be combined:cat YFTF-PBase_rep*_final.ccf | sort-bed - > YFTF-PBase.ccfThe concatenated CCF files can also be sorted using bedtools:cat PBase_rep*_final.ccf | bedtools sort -i - > PBase.ccfOr, using the standard shell sort command:cat PBase_rep*_final.ccf | sort -k1V -k2n -k3n > PBase.ccf
?. [Finishing Up]
Lastly, convert the BAM file to a CCF file.python BamToCallingCard.py \python BamToCallingCard.py -bXP XJ -i$out_map_sort_prefix"_final.bam"-o$out_map_sort_prefix"_final.ccf"    -b XP XJ \python BamToCallingCard.py -bXP XJ -i$out_map_sort_prefix"_final.bam"-o$out_map_sort_prefix"_final.ccf"    -i PBase_rep1_final.bam \python BamToCallingCard.py -bXP XJ -i$out_map_sort_prefix"_final.bam"-o$out_map_sort_prefix"_final.ccf"python BamToCallingCard.py -bXP XJ -i$out_map_sort_prefix"_final.bam"-o$out_map_sort_prefix"_final.ccf"    -o PBase_rep1_final.ccfpython BamToCallingCard.py -bXP XJ -i$out_map_sort_prefix"_final.bam"-o$out_map_sort_prefix"_final.ccf"This will use the combination of primer barcode and index sequence (XP and XJ, respectively) to identify insertions derived from different biological replicates.Here is an example of a CCF file:chr1	28575	28579	2	+	GCA/TCGCCACCCchr1	28575	28579	10	+	TAG/GAGGTACAGchr1	28575	28579	1	+	GAT/GAGGTACAGchr1	31191	31195	1	+	GCA/TCGCCACCCchr1	31191	31195	49	+	TAG/TCGCCACCCchr1	46620	46624	5	+	CTA/GAGGTACAGchr1	54136	54140	42	-	GCA/TCGCCACCCchr1	54818	54822	16	-	CTA/TCGCCACCCchr1	57829	57833	6	-	CGT/GAGGTACAGchr1	58414	58418	40	+	CTA/TCGCCACCC
?. [Notes]
Analogously, we can combine BAM files from biological replicates into a single archival-quality BAM file for an entire experiment:samtools merge PBase.bam PBase_rep*_final.bam
?. [Notes]
Ideally, each biological replicate will have a unique primer barcode AND unique index sequence. However, sometimes this is not possible. If so, each replicate should be identifiable from a unique combination of primer barcode and index sequence. If multiple replicates share an index, their reads will be found in the same FASTQ file. This is okay as step 3 can separate each replicate based on an exact match to the primer barcode sequence. In that case, you will have to provide the same input file to step 4 multiple times, each with a different primer barcode at the start of the adapter.
?. [Preamble]
The objective of this protocol is to take sequencing reads from a calling cards library and process them into a CCF (calling card format; .ccf) file. A CCF file is a modified BED file (BED3+3) that concisely enumerates every transposition event in the sequenced library.CCF files typically have six columns:chrom: chromosomestart: beginning coordinate of the insertion siteend: ending coordinate of the insertion site; since piggyBac inserts into TTAA's, this typically spans the motif itself.count: the number of reads supporting this insertionstrand: + or -, indicating which strand was targetted (optional but highly recommended)barcode: a string identifying the library from which this insertion originated (optional but highly recommended)This workflow will walk through how to perform quality control, alignment, filtering, and processing of calling card sequencing libraries to generate a CCF file. This file can then be used in downstream applications, such as visualization on the (legacy) WashU Epigenome Browser (instructions here), and as input for peak calling.