TITLE: CUT&amp;Tag Data Processing and Analysis Tutorial for Time Series
AUTHORS: Ye Zheng, Kami Ahmad, Steven Henikoff, karina_jhingan

[DESCRIPTION]
This tutorial is largely based off of Ye Zheng's CUT&Tag analysis https://www.protocols.io/view/cut-amp-tag-data-processing-and-analysis-tutorial-e6nvw93x7gmk/v1?step=9 and has been edited to fit with time series data as well as a higher focus on producing  clusters heatmaps. 

[STEPS]
SECTION: I. Introduction
1. Overview of CUT&Tag 

This tutorial is a time series tweaked approach based off of a CUT&Tag processing and analysis pipeline created by Ye Zheng, https://www.protocols.io/view/cut-amp-tag-data-processing-and-analysis-tutorial-e6nvw93x7gmk/v1 (Zheng Y et al (2020). Protocol.io). Some sections and text from Zheng's tutorial are left unchanges. Unlike Zheng's tutorial, this pipeline will not work with duplicates and instead with time series data, focusing on the following histones: K27ac, K4me1, and K4me3.

This tutorial will not go into the science, except for the sections left in that were written by Ye Zheng,  instead I'll focus on the computation/coding. 

**Note: it's common to receive errors in linux  if you are copying and pasting directly from this tutorial because of the format. If this happens, copy the code into a text editor and make sure the format is correct and then paste into the command line from the text editor. 

SECTION: I. Introduction
2. Requirements

Linux system
R (versions >= 3.6)
      - dplyr
      - stringr
      - ggplot2
      - viridis
      - GenomicRanges
      - chromVAR
      - DESeq2
      - ggpubr
      - corrplot


 

FastQC(version >= 0.11.9) [Optional]
Bowtie2 (version >= 2.3.4.3)
samtools (version >= 1.10)
bedtools (version >= 2.29.1)
Picard (version >= 2.18.29)
SEACR (version >= 1.3)
deepTools (version >= 2.0)
3. Data Downloading and Folder Setup 


First, we need to specify the project path.
 

We have human and mice data as well as 6 different time points that data was collected from. Our analysis will be focusing on the three noted histones. 
 
    
Now let's set up the folders where we will be storing the data.

 

data paths
 

And copy the data into the folders we just made (making a copy is a good idea in case we accidently alter the data files it won't alter the original data, this also allows us to organize the data into folders which makes ti easier to reference in for-loops).

 




SECTION: II. Data Pre-processing
4. Quality Control using FastQC 

1. Run FastQC for quality check
 

2. Copy over results to your local computer view the html files (alternatively open up R studio launcher for Fred Hutch and navigate to files and open through there to avoid downloading the files).
 

3 Interpret the quality check results.

Quality check reference: https://www.bioinformatics.babraham.ac.uk/projects/fastqc/bad_sequence_fastqc.html.

The discordant sequence content at the beginning of the reads is a common phenomenon for CUT&Tag reads. Failing to pass the Per base sequence content does not mean your data failed.
 
- It can be due to the Tn5 preference.

SECTION: III. Alignment
6. Bowtie2 alignment

Make folders and download genome files

 

Build the Bowtie Index for each genome
 

The paired-end reads are aligned by Bowtie2
*I added in the time function prior to the bowtie2 call to keep track of how long each call takes and how many calls have completed as bowtie2 does not output anything to the terminals it runs or completes.
 
Note: The runtimes I was receiving were around 10-30 (a few for the mice calls took upwards of  around 140 minutes) minutes for each. There are 36 calls to bowtie2 so this will take a while.

If you don't trim your reads , use this parameter instead of --local
 


SECTION: III. Alignment
7. Alignment summary

For more detailed parameters explanation, users can refer to the bowtie2 manual 

Bowtie2 alignment results summaries are saved at 
 
and you should expect the results look similar.

 


- 2573565 is the sequencing depth, i.e., the total number of paired reads.
- 72097 is the number of read-pairs that fail to be mapped.
- 1852091 + 649377 is the number of read-pairs that are successfully mapped.
- 97.20% is the overall alignment rate
SECTION: III. Alignment Summary
8. Report sequencing mapping summary

Summarize the raw reads and uniquely mapping reads to report the efficiency of alignment. Alignment frequencies are expected to be >80% for high-quality data. CUT&Tag data typically has very low backgrounds, so as few as 1 million mapped fragments can give robust profiles for a histone modification in the human genome. Profiling of less-abundant transcription factors and chromatin proteins may require 10 times as many mapped fragments for downstream analysis.

We can evaluate the following metrics:

 - Sequencing depth
 - Alignment rate
 - Number of mappable fragments
 - Duplication rate
 - Unique library size
 - Fragment size distribution
SECTION: III. Alignment Summary
8.1. 1. Sequencing depth
 
I found it was simpler to just set the organism as a variable, run the entire R file (the entire R file can be found below) once with the this variable declared up at the top of the file, first organism set to mouse and then to human

You will also need to perform find and replace on all mm10/hg38 in the R file to make sure we're referencing the correct genome for the organism we're currently running the script on


 

Collect the alignment results from the bowtie2 alignment summary files

 


 



2. Visualizing the sequencing depth and alignment results.
Generate sequencing depth boxplot
 

 




SECTION: IV. Alignment filtering and file format conversion
9. Prepare sam files for peak calling

Filter and keep the mapped read pairs

 


SECTION: V. Peak calling
10. MACS2 
This is assuming T1 as control as MACS2 has a control file as an input (we are performing T1 vs T2 .... T1 vs T6 )

 

parameters:
-c : control file (We are using T1 as control)
callpeak: peak calling from alignment (bowtie2) results.
-f BAMPE : our input files are formatted as BAM
-n: output file name
-q : q-value (these are the following q Values we tried (0.1, 0.001, 0.00001). 
--keep-dup: we decided not to remove duplicates in this experiment (more info?)
 
add .bed to the end of your file names (as seen in the below code section) for narrow peak files in order to input into ucsc genome browser (https://genome.ucsc.edu/cgi-bin/hgCustom?hgsid=1943424434_SEeSvx8fAuJKYhm1CWSwvicOd42W) or IgV (https://igv.org/app/) 
 
*Note we also tested out different q values and MACS2 settings (different combinations of no model and broad) to see how it affects the outputs that we later use as the region input when creating the heatmaps
 



SECTION: V. Peak calling
11. FRagment proportion in Peaks regions (FRiPs)

We calculate the fraction of reads in peaks (FRiPs) as a measure of signal-to-noise and contrast it to FRiPs in the IgG control dataset for illustration. Although sequencing depths for CUT&Tag are typically only 1-5 million reads, the low background of the method results in high FRiP scores.

 




SECTION: V. Peak calling
12. Visualization of peak number, peak width, and FRiPs

 



SECTION: VI. File Formatting
13. More FIle Format Conversion

Here we will sort our bam files by coordinates.

 

SECTION: VIII. Visualization
15. Heatmap Setup
Setup for using DeepTool's heatmap functions
 

*Note: if you receive an error that the mm10 genome is not available through the Homer program loaded through 'ml Homer'. You may need to download the Homer program

 
and run this following code in place of 'ml Homer'

 

SECTION: VIII. Visualization
16. Heatmap on CUT&Tag MACS2 peaks

This is a large for-loop so for ease I will be breaking the code block into steps explaining what is going on. 

An overview of the code is that in order to have the heatmap focus on the regions where we have the MACS2 peaks we will be merging the peak files using Homer's mergePeaks. mergePeak's output is a txt file, so we will turn it into a bed file and then use that as the input for the -R  (region) parameter in deepTool's heatmap. 

Step 1) Merge Peaks: We tried using various values for distances (the best value will likely vary for different histones and genomes); distances=("5000" "7500" "10000"). Here we merge all of our peakCalling data for the given Histone and genome

Step 2) Convert mergePeak output into a bed file

Step 3) This is the actual heatmap function, or at least the first part. As creating the heatmap involves first creating the matrix and then the second part is plotting the matrix.
parameters:
-p 10: number of cores (this is a timely function so I would recommend instead of running the entire for loop at once, try just running pick an example genome, histone, and distance combination to run once to make sure it runs alright (the most common error is referencing a file that does not exist so check your input files for typos). It is normal for either the matrix or plotting portion to sometimes take up to 12 hours for one function call. 

Step 4) This is where we input the matrix file we created form the compute matrix function and output the heat map visual, we also have the option to save the cluster information in outFileSortedRegions. We will be using the cluster information to run Homer's motif finding later to analyze each cluster. The only parameter that needs tuning here is the kmeans parameter as this tells the function how many clusters to look for. We tried clusterSizes=("3" "4" "5")

Parameter values to try out
 



 
*To continue the different combinations we tried in the Alignment MACS2 step where we tried different combinations of no model and broad, as well as the different q values; this is the script to run the heatmaps on all the various outputs
**Caution** This will take a very long time to run. I recommend  only tuning one parameter at a time (i.e remove one of the for x in xlist just set that value to one, for example replace  'for distance in ${distances[@]}; do'  with distance = "5000" to try out the different q values)
 

SECTION: VIII. Analyze Heatmap Cluster
17. Split up bed file into clusters
The bed file from plotHeatmap outputs information where there's a column with the cluster number. we want to separate the bed file based on the cluster column so that we have one bed file per cluster and we can analyze the clusters separately. 

How you run this next code depends on the value chosen for kmeans in plotHeatmap, for example if kmeans is 3 you would set

 

and only run up until and including clusterGroup=("3") as we would only have 3 clusters to split the bed file into. (And if kmeans=4, then cluster="4" and run up to and including clusterGroup=("6"), and so on for other kmeans values)
 

SECTION: II. Data Pre-processing
5. Trim Reads
 Documentation: https://cutadapt.readthedocs.io/en/v4.4/guide.html#paired-end
Since the experiment used 50x50 PE we will be trimming the reads with Cutadapt
 
example output
 

SECTION: VII. Scaling
14. The original tutorial scales the data using E.coli counts . Since our data did not contain E.coli we will be scaling based on reads per genome coverage.

Here we are going to be scaling the bigwig files that we will be inputting to create our heatmaps.

*gzsize values can be found in deeptools bamcoverage documentation https://deeptools.readthedocs.io/en/latest/content/feature/effectiveGenomeSize.html