---
title: '`r paste0("Statistical report of project ", projectName, ": pairwise comparison(s) of conditions with DESeq2")`'
author: '`r author`'
date: '`r Sys.Date()`'
output:
  html_document:
    toc: TRUE
    toc_float: TRUE
    number_sections: TRUE
bibliography: bibliography.bib
csl: medecine-sciences.csl
# css: styles.css
---

The SARTools R package which generated this report has been developped at PF2 - Institut Pasteur by M.-A. Dillies and H. Varet (hugo.varet@pasteur.fr) and modified by Cenny Taslim (taslim.2@osu.edu). Thanks to cite H. Varet, L. Brillet-Guéguen, J.-Y. Coppee and M.-A. Dillies, _SARTools: A DESeq2- and EdgeR-Based R Pipeline for Comprehensive Differential Analysis of RNA-Seq Data_, PLoS One, 2016, doi: http://dx.doi.org/10.1371/journal.pone.0157022 when using this tool for any analysis published.

# Introduction

The analyses reported in this document are part of the `r projectName` project. The aim is to find features that are differentially expressed between `r paste(paste(levels(target[,varInt])[-nlevels(target[,varInt])],collapse=", "),levels(target[,varInt])[nlevels(target[,varInt])],sep=" and ")`. The statistical analysis process includes data normalization, graphical exploration of raw and normalized data, test for differential expression for each feature between the conditions, raw p-value adjustment and export of lists of features having a significant differential expression between the conditions. `r ifelse(!is.null(batch),paste0("In this analysis, the ",batch, " effect will be taken into account in the statistical models."),"")`

The analysis is performed using the R software [@rcoreteam], Bioconductor [@Gentleman2004] packages including DESeq2 [@Anders2010; @Love2014] and the SARTools package developed at PF2 - Institut Pasteur. Normalization and differential analysis are carried out according to the DESeq2 model and package. This report comes with additional tab-delimited text files that contain lists of differentially expressed features.

For more details about the DESeq2 methodology, please refer to its related publications [@Anders2010; @Love2014].

# Description of raw data

The count data files and associated biological conditions are listed in the following table.

```{r , echo=FALSE, results="asis"}
kable_styling(kable(target, row.names=FALSE, caption="Table 1: Data files and associated biological conditions.", format="html"), c("striped", "bordered", "responsive"), font_size=12)
```

After loading the data we first have a look at the raw data table itself. The data table contains one row per annotated feature and one column per sequenced sample. Row names of this table are feature IDs (unique identifiers). The table contains raw count values representing the number of reads that map onto the features. For this project, there are `r nrow(counts)` features in the count data table.

```{r , echo=FALSE, results="asis"}
kable_styling(kable(head(counts[, 1:min(ncol(counts), 10)]), row.names=TRUE, digits=0, caption="Table 2: Partial view of the count data table.", format="html"), c("striped", "bordered", "responsive"), font_size=12)
```

Looking at the summary of the count table provides a basic description of these raw counts (min and max values, median, etc).

```{r , echo=FALSE, results="asis"}
fun_summary=function(x){
  out=c(quantile(x,c(0,0.25,0.5),type=1),mean(x),quantile(x,c(0.75,1),type=1))
  names(out)=c("Min.","1st Qu.","Median","Mean","3rd Qu.","Max.")
  return(round(out,0))
}
kable_styling(kable(t(apply(counts, 2, fun_summary)), row.names=TRUE, digits=0, caption="Table 3: Summary of the raw counts.", format="html"), c("striped", "bordered", "responsive"), font_size=12)
nbNull <- nrow(counts) - nrow(removeNull(counts)) # needed in one of the next paragraphs
```

Figure 1 shows the total number of mapped and counted reads for each sample. We expect total read counts to be similar within conditions, they may be different across conditions. Total counts sometimes vary widely between replicates. This may happen for several reasons, including:

- different rRNA contamination levels between samples (even between biological replicates);
- slight differences between library concentrations, since they may be difficult to measure with high precision.


<center>
![Figure 1: Number of mapped reads per sample. Colors refer to the biological condition of the sample.](figures/barplotTotal.png){width=600}

</center>

Figure 2 shows the percentage of features with no read count in each sample. We expect this percentage to be similar within conditions. Features with null read counts in the `r ncol(counts)` samples are left in the data but are not taken into account for the analysis with DESeq2. Here, `r nbNull` features (`r round(100*nbNull/nrow(counts),2)`%) are in this situation (dashed line). Results for those features (fold-change and p-values) are set to NA in the results files.

<center>
![Figure 2: Percentage of features with null read counts in each sample.](figures/barplotNull.png){width=600}

</center>

Figure 3 shows the distribution of read counts for each sample (on a log scale to improve readability). Again we expect replicates to have similar distributions. In addition, this figure shows if read counts are preferably low, medium or high. This depends on the organisms as well as the biological conditions under consideration.

<center>
![Figure 3: Density distribution of read counts.](figures/densplot.png){width=600}

</center>

It may happen that one or a few features capture a high proportion of reads (up to 20% or more). This phenomenon should not influence the normalization process. The DESeq2 normalization has proved to be robust to this situation [Dillies, 2012]. Anyway, we expect these high count features to be the same across replicates. They are not necessarily the same across conditions. Figure 4 and table 4 illustrate the possible presence of such high count features in the data set. Please check to make sure the feature with high proportion of reads (usually 20% or more) is NOT rRNA. If it is, you may have contamination.

<center>
![Figure 4: Percentage of reads associated with the sequence having the highest count (provided in each box on the graph) for each sample.](figures/majSeq.png){width=600}

</center>


```{r , echo=FALSE, results="asis"}
kable_styling(kable(t(as.matrix(majSequences))[,1:min(10, nrow(majSequences))], row.names=TRUE, digits=2, caption="Table 4: Percentage of reads associated with the sequences having the highest counts.", format="html"), c("striped", "bordered", "responsive"), font_size=12)
```

We may wish to assess the similarity between samples across conditions. A pairwise scatter plot is produced (figure 5) to show how replicates and samples from different biological conditions are similar or different (using a log scale). Moreover, as the Pearson correlation has been shown not to be relevant to measure the similarity between replicates, the SERE statistic has been proposed as a similarity index between RNA-Seq samples [@Schulze2012]. It measures whether the variability between samples is random Poisson variability or higher. Pairwise SERE values are printed in the lower triangle of the pairwise scatter plot. The value of the SERE statistic is:

- 0 when samples are identical (no variability at all: this may happen in the case of a sample duplication);

- 1 for technical replicates (technical variability follows a Poisson distribution);

- greater than 1 for biological replicates and samples from different biological conditions (biological variability is higher than technical one, data are over-dispersed with respect to Poisson). The higher the SERE value, the lower the similarity. It is expected to be lower between biological replicates than between samples of different biological conditions. Hence, the SERE statistic can be used to detect inversions between samples.


<center>
![Figure 5: Pairwise comparison of samples (not produced when more than 12 samples).](figures/pairwiseScatter.png)

</center>

# Variability within the experiment: data exploration

The main variability within the experiment is expected to come from biological differences between the samples. This can be checked in two ways. The first one is to perform a hierarchical clustering of the whole sample set. This is performed after a transformation of the count data which can be either a Variance Stabilizing Transformation (VST) or a regularized log transformation (rlog) [@Anders2010; @Love2014].

A VST is a transformation of the data that makes them homoscedastic, meaning that the variance is then independent of the mean. It is performed in two steps: (i) a mean-variance relationship is estimated from the data with the same function that is used to normalize count data and (ii) from this relationship, a transformation of the data is performed in order to get a dataset in which the variance is independent of the mean. The homoscedasticity is a prerequisite for the use of some data analysis methods, such as hierarchical clustering or Principal Component Analysis (PCA). The regularized log transformation is based on a GLM (Generalized Linear Model) on the counts and has the same goal as a VST but is more robust in the case when the size factors vary widely.

Figure 6 shows the dendrogram obtained from `r typeTrans`-transformed data. An euclidean distance is computed between samples, and the dendrogram is built upon the Ward criterion. We expect this dendrogram to group replicates and separate biological conditions.

<!-- IMPORTANT!! need to have at least one newline character after figure declaration -->
<center>
![Figure 6: Sample clustering based on normalized data.](figures/cluster.png){width=600}

</center>

Another way of visualizing the experiment variability is to look at the first principal components of the PCA, as shown on the figure 7. On this figure, the first principal component (PC1) is expected to separate samples from the different biological conditions, meaning that the biological variability is the main source of variance in the data.

<!-- IMPORTANT!! need to have at least one newline character after figure declaration -->
<center>
![Figure 7: First two components of a Principal Component Analysis, with percentages of variance associated with each axis.](figures/PCA.png){width=1200}

</center>

```{r , echo=FALSE, results="asis"}
if (!is.null(batch)){
  cat("For the statistical analysis, we need to take into account the batch effect (i.e. the ",batch," parameter). Statistical models and tests will thus be adjusted on it.  \n")
  cat("As a comparison, Figure 7b below shows the PCA plot after batch effect adjustment estimated using limma package.\n")
}
```

<!-- IMPORTANT!! need to have at least one newline character after figure declaration -->
<center>

```{r,echo=FALSE, results="asis"}
if(!is.null(batch)){
  cat("\n![Figure 7b: First two components of a Principal Component Analysis (after batch adjustment), with percentages of variance associated with each axis.](figures/PCA_batchRem.png){width=1200}\n")
}
```

</center>


# Normalization

Normalization aims at correcting systematic technical biases in the data, in order to make read counts comparable across samples. The normalization proposed by DESeq2 relies on the hypothesis that most features are not differentially expressed. It computes a scaling factor for each sample. Normalized read counts are obtained by dividing raw read counts by the scaling factor associated with the sample they belong to. Scaling factors around 1 mean (almost) no normalization is performed. Scaling factors lower than 1 will produce normalized counts higher than raw ones, and the other way around. Two options are available to compute scaling factors: locfunc="median" (default) or locfunc="shorth". Here, the normalization was performed with locfunc="`r locfunc`".

```{r , echo=FALSE, results="asis"}
kable_styling(kable(t(matrix(out.DESeq2$sf, dimnames=list(target$label,"Size factor"))), row.names=TRUE, digits=2, caption="Table 5: Normalization factors.", format="html"), c("striped", "bordered", "responsive"), font_size=12)
```

The histograms (figure 8) can help to validate the choice of the normalization parameter ("median" or "shorth"). Under the hypothesis that most features are not differentially expressed, each size factor represented by a red line is expected to be close to the mode of the distribution of the counts divided by their geometric means across samples.

<center>
![Figure 8: Diagnostic of the estimation of the size factors.](figures/diagSizeFactorsHist.png)

</center>

The figure 9 shows that the scaling factors of DESeq2 and the total count normalization factors may not perform similarly.

<center>
![Figure 9: Plot of the estimated size factors and the total number of reads per sample.](figures/diagSizeFactorsTC.png){width=600}

</center>

Boxplots are often used as a qualitative measure of the quality of the normalization process, as they show how distributions are globally affected during this process. We expect normalization to stabilize distributions across samples. Figure 10 shows boxplots of raw (left) and normalized (right) data respectively.

<center>
![Figure 10: Boxplots of raw (left) and normalized (right) read counts.](figures/countsBoxplots.png){width=1200}

</center>

# Differential analysis

## Modelisation

DESeq2 aims at fitting one linear model per feature. For this project, the design used is counts `r paste(as.character(design(out.DESeq2$dds)),collapse=" ")` and the goal is to estimate the models' coefficients which can be interpreted as $\log_2(\texttt{FC})$. These coefficients will then be tested to get p-values and adjusted p-values.

## Outlier detection

Model outliers are features for which at least one sample seems unrelated to the experimental or study design. For every feature and for every sample, the Cook's distance [@cook1977] reflects how the sample matches the model. A large value of the Cook's distance indicates an outlier count and p-values are not computed for the corresponding feature. `r ifelse(!cooksCutoff,"For this project, the detection of model outliers have been turned off by setting the cut-off to the infinite.","")`

## Dispersions estimation

The DESeq2 model assumes that the count data follow a negative binomial distribution which is a robust alternative to the Poisson law when data are over-dispersed (the variance is higher than the mean). The first step of the statistical procedure is to estimate the dispersion of the data. Its purpose is to determine the shape of the mean-variance relationship. The default is to apply a GLM (Generalized Linear Model) based method (fitType="parametric"), which can handle complex designs but may not converge in some cases. The alternative is to use fitType="local" as described in the original paper [@Anders2010] or fitType="mean". The parameter used for this project is fitType="`r fitType`". Then, DESeq2 imposes a Cox Reid-adjusted profile likelihood maximization [@cox1897 and McCarthy, 2012] and uses the maximum _a posteriori_ (MAP) of the dispersion [Wu, 2013].


<center>
![Figure 11: Dispersion estimates (left) and diagnostic of log-normality (right).](figures/dispersionsPlot.png){width=1200}

</center>

The left panel on figure 11 shows the result of the dispersion estimation step. The x- and y-axes represent the mean count value and the estimated dispersion respectively. Black dots represent empirical dispersion estimates for each feature (from the observed counts). The red dots show the mean-variance relationship function (fitted dispersion value) as estimated by the model. The blue dots are the final estimates from the maximum _a posteriori_ and are used to perform the statistical test. Blue circles (if any) point out dispersion outliers. These are features with a very high empirical variance (computed from observed counts). These high dispersion values fall far from the model estimation. For these features, the statistical test is based on the empirical variance in order to be more conservative than with the MAP dispersion. These features will have low chance to be declared significant. The figure on the right panel allows to check the hypothesis of log-normality of the dispersions.

## Statistical test for differential expression

Once the dispersion estimation and the model fitting have been done, DESeq2 can perform the statistical testing. Figure 12 shows the distributions of raw p-values computed by the statistical test for the comparison(s) done. This distribution is expected to be a mixture of a uniform distribution on $[0,1]$ and a peak around 0 corresponding to the differentially expressed features. If raw p-values doesn't follow the expected distribution, FDR can be re-estimated using fdrtool [@korbinian2008].

```{r , echo=FALSE, results="asis"}
if(file.exists("figures/rawpHist_corrected.png")) cat("In this analysis, p-values for null distribution were corrected using fdrtool")
```
`r if(!file.exists("figures/rawpHist_corrected.png")){"\\begin{comment}"}`
<center>
![Figure 12: Distribution(s) of corrected raw p-values.](figures/rawpHist_corrected.png)
</center>
`r if(!file.exists("figures/rawpHist_corrected.png")){"\\end{comment}"}`

`r if(file.exists("figures/rawpHist_corrected.png")){"\\begin{comment}"}`
<center>
![Figure 12: Distribution(s) of raw p-values.](figures/rawpHist.png)
</center>
`r if(file.exists("figures/rawpHist_corrected.png")){"\\end{comment}"}`


## Independent filtering

DESeq2 can perform an independent filtering to increase the detection power of differentially expressed features at the same experiment-wide type I error. Since features with very low counts are not likely to see significant differences typically due to high dispersion, it defines a threshold on the mean of the normalized counts irrespective of the biological condition. This procedure is independent because the information about the variables in the design formula is not used [@Love2014]. 

```{r , echo=FALSE, results="asis"}
if (independentFiltering){
  cat("Table 6 reports the thresholds used for each comparison and the number of features discarded by the independent filtering. Adjusted p-values of discarded features are then set to NA.\n")
  kable_styling(kable(summaryResults$tabIndepFiltering, row.names=FALSE, digits=2, caption="Table 6: Number of features discarded by the independent filtering for each comparison.", format="html"), c("striped", "bordered", "responsive"), font_size=12)
} else{
  cat("For this project, no independent filtering has been performed.")
}
```

## Final results

A p-value adjustment is performed to take into account multiple testing and control the false positive rate to a chosen level $\alpha$. For this analysis, a `r pAdjustMethod` p-value adjustment was performed [@BH1995 and BY2001] and the level of False Discovery Rate (FDR) was set to `r alpha`.

```{r , echo=FALSE, results="asis"}
kable_styling(kable(summaryResults$nDiffTotal, row.names=FALSE, digits=0, caption=paste0(ifelse(independentFiltering,"Table 7: ","Table 6: "),"Number of up-, down- and total number of differentially expressed features for each comparison."), format="html"), c("striped", "bordered", "responsive"), font_size=12)
```

```{r , echo=FALSE, results="asis"}
cat(paste(ifelse(independentFiltering,"Table 8: ","Table 7: "),"View of differentially expressed features. Each table below shows top and bottom two (up- and down-regulated) significant features in each comparison. These tables can serve as a diagnostic tool to make sure significant features are indeed different in the samples compared.\n\n\n"))
for (i in 1:length(summaryResults$diffTable)){
  summaryResults$diffTable[[i]][,"FoldChange"]=round(summaryResults$diffTable[[i]][,"FoldChange"],3)
  summaryResults$diffTable[[i]][,"pvalue"]=format(summaryResults$diffTable[[i]][,"pvalue"],digits=3,scientific = TRUE)
  summaryResults$diffTable[[i]][,"padj"]=format(summaryResults$diffTable[[i]][,"padj"],digits=3,scientific = TRUE)
 	kable(summaryResults$diffTable[[i]], row.names=FALSE,
		caption=(paste0(ifelse(independentFiltering,"Table 8.","Table 7."),i,": ","**",
			gsub("_vs_"," vs ",gsub(" ","_",names(summaryResults$diffTable)[i])),"(ref)**\n"))) %>%
	kable_styling(c("striped","bordered","responsive"),font_size=12) %>%
	  htmltools::HTML() %>% 
	print
	cat("\n")

 }
```

Figure 13 represents the MA-plot of the data for the comparisons done, where differentially expressed features are highlighted in red. A MA-plot represents the log ratio of differential expression as a function of the mean intensity for each feature. Triangles correspond to features having a too low/high $\log_2(\text{FC})$ to be displayed on the plot.


<center>
![Figure 13: MA-plot(s) of each comparison. Red dots represent significantly differentially expressed features.](figures/MAPlot.png)

</center>


Figure 14 shows the volcano plots for the comparisons performed and differentially expressed features are still highlighted in red. A volcano plot represents the log of the adjusted P value as a function of the log ratio of differential expression.


<center>
![Figure 14: Volcano plot(s) of each comparison. Red dots represent significantly differentially expressed features.](figures/volcanoPlot.png)

</center>

Heatmaps showing the rlog normalized counts of up-/down-regulated genes in each sample can be found in figures/diffPlot.pdf.
This plot again can serve as a diagnostic tool to make sure the normalized counts in all of the replicates are higher/lower compared to control for up-/down-regulated genes, respectively.

Full results as well as lists of differentially expressed features are provided in the following text files which can be easily read in a spreadsheet. For each comparison:

- TestVsRef.complete.txt contains results for all the features;
- TestVsRef.up.txt contains results for significantly up-regulated features. Features are ordered from the most significant adjusted p-value to the less significant one;
- TestVsRef.down.txt contains results for significantly down-regulated features. Features are ordered from the most significant adjusted p-value to the less significant one.

These files contain the following columns:

- Id: unique feature identifier;
- sampleName: raw counts per sample;
- norm.sampleName: rounded normalized counts per sample;
- baseMean: base mean over all samples;
- `r paste(paste(levels(target[,varInt])[-nlevels(target[,varInt])],collapse=", "),levels(target[,varInt])[nlevels(target[,varInt])],sep=" and ")`: means (rounded) of normalized counts of the biological conditions;
- FoldChange: fold change of expression, calculated as $2^{\log_2(\text{FC})}$;
- log2FoldChange: $\log_2(\text{FC})$ as estimated by the GLM model. It reflects the differential expression between Test and Ref and can be interpreted as $\log_2(\frac{\text{Test}}{\text{Ref}})$. If this value is:
    + around 0: the feature expression is similar in both conditions;
    + positive: the feature is up-regulated ($\text{Test} > \text{Ref}$);
    + negative: the feature is down-regulated ($\text{Test} < \text{Ref}$);
- stat: Wald statistic for the coefficient tested;
- pvalue: raw p-value from the statistical test;
- padj: adjusted p-value on which the cut-off $\alpha$ is applied;
- dispGeneEst: dispersion parameter estimated from feature counts (i.e. black dots on figure 11);
- dispFit: dispersion parameter estimated from the model (i.e. red dots on figure 11);
- dispMAP: dispersion parameter estimated from the Maximum _A Posteriori_ model;
- dispersion: final dispersion parameter used to perform the test (i.e. blue dots and circles on figure 11);
- betaConv: convergence of the coefficients of the model (TRUE or FALSE);
- maxCooks: maximum Cook's distance of the feature.

# R session information and parameters

The versions of the R software and Bioconductor packages used for this analysis are listed below. It is important to save them if one wants to re-perform the analysis in the same conditions.

```{r , echo=FALSE, results="asis"}
si <- as.character(toLatex(sessionInfo()))
si <- si[-c(1,length(si))]
si <- gsub("(\\\\verb)|(\\|)", "", si)
si <- gsub("~", " ", si)
si <- paste(si, collapse=" ")
si <- unlist(strsplit(si, "\\\\item"))
cat(paste(si, collapse="\n -"), "\n")
```

Parameter values used for this analysis are:

- workDir: `r workDir`
- projectName: `r projectName`
- author: `r author`
- targetFile: `r targetFile`
- rawDir: `r rawDir`
- featuresToRemove: `r ifelse(is.null(featuresToRemove),"NULL",paste(featuresToRemove,collapse=", "))`
- varInt: `r varInt`
- condRef: `r condRef`
- batch: `r ifelse(is.null(batch),"NULL",batch)`
- fitType: `r fitType`
- cooksCutoff: `r cooksCutoff`
- independentFiltering: `r independentFiltering`
- alpha: `r alpha`
- pAdjustMethod: `r pAdjustMethod`
- typeTrans: `r typeTrans`
- locfunc: `r locfunc`
- colors: `r colors`

# Bibliography
