---
title: "Spiky: Analysing cfMeDIP-seq data with spike-in controls"
author: "Samantha L Wilson and Lauren M Harmon"
date: "February 8, 2021"
output: rmarkdown::html_vignette
bibliography: references.bib 
csl: nature.csl
link-citations: yes
vignette: >
  %\VignetteIndexEntry{Spiky: Analysing cfMeDIP-seq data with spike-in controls}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(devtools)
load_all("./")
```

# Introduction

To meet the need for a reference control in cell-free methylated DNA immunoprecipitation-sequencing (cfMeDIP-seq)[@shen2018sensitive; @shen2019preparation] experiments, we designed spike-in controls and ligated unique molecular indexes (UMI) to adjust for PCR bias, and immunoprecipitation bias caused by the fragment length, G+C content, and CpG density of the DNA fragments that are immunoprecipitated. This enables absolute quantification of methylated DNA in picomoles, while retaining epigenomic information that allows for sensitive, tissue-specific detection as well as comparable results between different experiments. We designed DNA fragments with 2x3x3x3=54 combinations of methylation status (methylated and unmethylated), fragment length in basepair (bp) (80 bp, 160 bp, 320 bp), G+C content (35%, 50%, 65%), and fraction of CpGs within a fragment (1 CpG/ 80 bp, 1 CpG/ 40 bp, 1 CpG/ 20 bp). Spiky was developed for analyzing DNA methylation of cell-free DNA obtained from cfMeDIP-seq method using reference 'spike-in' controls. This package will:

* Assess methylation specificity in each sample
* Using the spike-in control data, output a Gaussian generalized linear model to predict molar amount on DNA samples
* Predict molar amount (picomoles) for each DNA sequence of interest, adjusting for fragment length G+C content and CpG fraction
* Adjust molar amount and bin the fragments into genomic windows used in analyses

# Installation
Install and load the spiky package from Bioconductor.
```{r eval = FALSE,message=FALSE}
#To install this package, start R (version "3.6" or later) and enter:
  #if (!requireNamespace("BiocManager", quietly = TRUE))
  #  install.packages("BiocManager")
  #
  #BiocManager::install("spiky")

library(spiky)
```

# Process the BAM file

### Input: spikein_data
  * BAM or BED file
  * Columns:
    * chrom/contig: string 
    * position start: numeric
    * position end: numeric
    * read counts: integer
    * fragment length (bp): integer
    * G+C content [0-1]: numeric
    * CpG number: Integer
    
### Output: The output contains objects that will be used downstream in the analysis, including
  * genomic - A GRanges object showing the genomic coverage of the BAM reads
  * spikes - A GRanges object showing the coverage of the spikes.
  
```{r eval=TRUE}
spike_path <- system.file("data", "spike.rda", package = "spiky")
load(spike_path)
#Load in your bam file using scan_spiked_bam
#ssb_res <- scan_spiked_bam("bam/file/path",spike=spike)
#Example result
ssb_res_path <- system.file("data", "ssb_res.rda", package = "spiky")
load(ssb_res_path)
```

# Methylation specificity
For each combination of parameters, we designed two distinct spike-in sequences. One to be methylated and one to be unmethylated. The allows us to assess non-specific binding of the monoclonal antibody on a sample-by-sample basis. To calculate methylation specificity we take the number of methylated reads divided by the total number of reads. It is our recommendation that if methylation specificity is <0.98, then the sample should be flagged or removed from analysis as the cfMeDIP performed inadequately. 

This calculation is done by the 'methylation_specificity' function.

### Input: The output of the 'scan_spiked_bam' function
  * ssb_res as produced in the previous step
  
### Output: methylation specificity mean and median
  * Mean and median of the percent of methylated sequences for each spike-in after cfMeDIP-seq has been performed

### Example
```{r eval=TRUE}
##Calculate methylation specificity
methyl_spec <- methylation_specificity(ssb_res,spike=spike)
print(methyl_spec)
```

# Fit a Gaussian model to predict the molar amount of DNA sequences
For each batch of samples, the coefficients used in the Gaussian generalized linear model will differ. The 'model_glm_pmol' will calculate these coefficients and output the model to be used to calculate molar amount (picomoles) on the user's DNA sequences of interest. We assume that all DNA sequences of interest are methylated after undergoing cfMeDIP-seq. As such, we build the Gaussian generalized linear model on only the methylated spike-in control fragments. A generated Bland-Altman plot will visualize how well the model performs.

### Input: The output of the 'scan_spiked_bam' function
  * Example: data(ssb_res)

### Output: 
  * Gaussian generalized linear model with coefficients specific to samples used in input data; .rda file

### Example
```{r eval=TRUE}
## Build the Gaussian generalized linear model on the spike-in control data
gaussian_glm <- model_glm_pmol(covg_to_df(ssb_res,spike=spike),spike=spike)
summary(gaussian_glm)
```

# Calculating molar amount on DNA sequences of interest
For the samples in which the Gaussian generalized linear model was built, we will calculate the molar amount (picomoles) for each DNA sequence of interest.

### Input: The output of the 'scan_spiked_bam' function
  * Example: data(ssb_res)
  
### Output: sample_pmol_data
  * Data frame
  * Columns: 
    * chrom: string
    * bin position start: numeric
    * bin position end: numeric
    * read counts: coverage of bin
    * fragment length (bp): integer
    * G+C content [0-1]: numeric
    * CpG number: numeric 
    * pmol: numeric
  
### Example
```{r eval=TRUE}
# Predict pmol concentration
# To select a genome other than hg38, use BSgenome::available.packages() to find valid BSgenome name
#library("BSgenome.Hsapiens.UCSC.hg38")
sample_data_pmol <- predict_pmol(gaussian_glm, ssb_res,bsgenome="BSgenome.Hsapiens.UCSC.hg38",ret="df")
head(sample_data_pmol,n=1)

```

# Adjusting molar amount to binned genomic windows
For our analyses, we binned the genome into 300 bp non-overlapping windows. We then look overlap between fragments in our data with each of the 300 bp genomic windows. We adjust the molar amount (picomoles) by a multiplier. This multiplier is the proportion of overlap between our fragment and the 300 bp window. This is done for every fragment in our sample.

### Input: output dataframe produced from predict_pmol
   * Example: sample_pmol_data as produced in previous step
  
### Output: sample_binned_data
  * Data frame
  * Columns: 
    * chrom: string
    * bin position start: numeric
    * bin position end: numeric
    * read counts: coverage of bin
    * fragment length (bp): integer
    * G+C content [0-1]: numeric
    * CpG number: numeric 
    * pmol: numeric
    * adjusted pmol: numeric
  
### Example
```{r eval=TRUE}
sample_binned_data <- bin_pmol(sample_data_pmol)
head(sample_binned_data,n=1)
```


# References
\chaptermark{references.bib}