---
output: 
    html_document:
        theme: spacelab
        toc: true
        toc_float: true
        df_print: kable
        code_folding: show
    pdf_document:
        toc: true
always_allow_html: yes
editor_options: 
    chunk_output_type: console
title: "`r sampleId`"
date: "`r Sys.Date()`"
author: "`r paste0('alevinQC (v', utils::packageVersion('alevinQC'), ')')`"
---

<style>
   tbody tr:nth-child(odd){
    background-color: #D6E0F5;
  }
</style>

```{r prep, include = FALSE}
knitr::opts_chunk$set(echo = showCode, warning = FALSE, message = FALSE)
knitr::opts_knit$set(progress = FALSE, verbose = FALSE)
```

```{r setup}
## Read input files
if (!quiet) message("Reading Alevin output files...")
alevin <- readAlevinQC(baseDir)
```

## Version info for alevin run

```{r}
knitr::kable(
    alevin$versionTable
)
```

## Summary tables

#### Full set of cell barcodes

```{r}
if (!quiet) message("Generating summary tables...")
knitr::kable(
    alevin$summaryTables$fullDataset
)
```

#### Initial whitelist

```{r}
knitr::kable(
    alevin$summaryTables$initialWhitelist
)
```

#### Final whitelist

```{r}
knitr::kable(
    alevin$summaryTables$finalWhitelist
)
```

## Knee plot

The knee plot displays the number of times each cell barcode is observed, in
decreasing order. By finding a 'knee' in this plot, Alevin determines a
threshold (indicated in the plot) that defines an initial 'whitelist' - a set
of cell barcodes that likely represent non-empty droplets - and distinguishes
them from the background. For this run, the initial whitelist contains 
`r alevin$cbTable %>% dplyr::filter(inFirstWhiteList) %>% dplyr::filter(ranking == max(ranking)) %>% dplyr::pull(ranking)` cell barcodes, each observed at least 
`r alevin$cbTable %>% dplyr::filter(inFirstWhiteList) %>% dplyr::filter(ranking == max(ranking)) %>% dplyr::pull(originalFreq)` times. 

```{r}
if (!quiet) message("Generating knee plot...")
plotAlevinKneeRaw(alevin$cbTable)
```

## Cell barcode error correction and merging with initial whitelist

Once the initial set of whitelisted cell barcodes is defined, Alevin goes
through the remaining cell barcodes. If a cell barcode is similar enough to a
whitelisted cell barcode, it will be corrected and the reads will be added to
those of the whitelisted one. The figure below shows the original frequency of
the whitelisted barcodes vs the frequency after this correction. The reads
corresponding to cell barcodes that can not be corrected to a whitelisted
barcode are discarded. 

```{r}
if (!quiet) message("Generating barcode collapsing plot...")
plotAlevinBarcodeCollapse(alevin$cbTable)
```

## Quantification

After cell barcode collapsing, Alevin estimates the UMI count for each cell and
gene. Following quantification, an additional cell barcode whitelisting is
performed with the aim of extracting good quality cells, using not only the
barcode frequency but also other features such as the fraction of mapped reads,
the duplication rate and the average gene count. The plots below show the
association between the cell barcode frequency (the number of observed reads
corresponding to a cell barcode), the total UMI count (obtained by summing the
UMI counts for the individual genes in the returned count matrix) and the number
of detected genes (also obtained from the returned count matrix). The cell
barcodes are colored by whether or not they are included in the final whitelist.

These figures can give an indication of whether the sequenced reads actually
align to genes, as well as the duplication rate and the degree of saturation.
For many droplet data sets, the association between the barcode frequency and
the total UMI count is rougly linear, while the association of any of these with
the number of detected genes often deviates from linearity, if a small subset of
the genes are assigned a large fraction of the UMI counts.

```{r fig.width = 10}
if (!quiet) message("Generating quantification summary plot...")
plotAlevinQuant(alevin$cbTable)
```

## Knee plot, number of detected genes

Similarly to the knee plot that was used to select the initial cell barcode
whitelist, the plot below shows the number of detected genes for each cell
barcode included in the initial whitelist, in decreasing order.

```{r}
if (!quiet) message("Generating knee plot for nbr genes...")
plotAlevinKneeNbrGenes(alevin$cbTable)
```


## Session info

```{r}
sessionInfo()
```

