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

[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 unchanged. 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. Errors may also stem from the order in which modules were loaded so playing around with loading the modules in a different order may help. I would HIGHLY recommend copying the commands over to a code editor such as vscode to be able to view/understand the code better

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.

 

Histone TimePoint peakN
1    K27ac        T2  1370
2    K27ac        T3   127
3    K27ac        T4   240
4    K27ac        T5   706
5    K27ac        T6  1067
6    K4me1        T2  3134
7    K4me1        T3  1748
8    K4me1        T4     1
9    K4me1        T5   124
10   K4me1        T6    94
11   K4me3        T2 12625
12   K4me3        T3 14697
13   K4me3        T4   327
14   K4me3        T5  7241
15   K4me3        T6  1800
 
   Histone TimePoint SeqDepth MappedFragNum_mm10 AlignRate_mm10 FragInPeakNum      FRiPs
1    K27ac        T2         6024227            5830620                96.79                            204870    3.5136915
2    K27ac        T3         6765622            6510809                96.23                             28967     0.4449063
3    K27ac        T4          143632             136962                  95.36                             1515        1.1061462
4    K27ac        T5          808940             787214                  97.31                             16956       2.1539251
5    K27ac        T6          377282             368188                  97.59                             12801      3.4767564
6    K4me1        T2        12248049           11882867             97.02                             475041    3.9976969
7    K4me1        T3         4995126            4800522              96.10                             119477     2.4888335
8    K4me1        T4            2177               2109                      96.88                             11             0.5215742
9    K4me1        T5          508877             500117                 98.28                             19376      3.8742934
10   K4me1        T6          342994             336391               98.07                             14122       4.1980909
11   K4me3        T2         6002937            5906183             98.39                            1478082  25.0260109
12   K4me3        T3         4440669            4269693           96.15                             1644648  38.5191160
13   K4me3        T4          978001             950906               97.23                             26907     2.8296172
14   K4me3        T5         2421522            2376602             98.14                             421345   17.7288835
15   K4me3        T6         2608987            2568003            98.43                             140770  5.4816914



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. I also left in the option to produce raw bigwig files for the heatmap input, but we chose to normalize/scale so in the next step we create normalized bigwig files to input for creating the heatmaps instead.

 

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

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

 
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. 

Debugging tip: If you see the terminal output "Preloading the following deepBlue files" followed by one of your file paths, that means that that path does not exist (you likely have a typo in the path) but instead of throwing an error right away, deepTools assumes you're referencing one of their deepBlue files and will then throw a different error.

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; the following is the script to run the heatmaps on all the various parameters
**Caution** This may take a 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 for kmeans is 3 you would set, (since I tried kmeans set to 3, 4, and 5; I would run this with cluster="3" then cluster="4" then cluster="5"

 

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.

*genome size (gsize) values can be found in deeptools bamcoverage documentation https://deeptools.readthedocs.io/en/latest/content/feature/effectiveGenomeSize.html
 

SECTION: Cluster Analysis
18. 
 

Gene Ontology Analysis: 
Now we will analyze each cluster in the heatmaps, this is where errors regarding homer not having the mm10 genome would pop up, so make sure to follow the steps I noted earlier on downloading homer as a package if this happens.


 

 

SECTION: Cluster Analysis
19. Motifs:
Since I do not have write privileges outside of my personal folder, we have to use the -preparsedDir option and provide any directory that you have write access too.