---
title: Differential abundance analysis of functional screens
author:
<%= AUTHOR %>
date: "`r Sys.Date()`"
output: BiocStyle::html_document
---

```{r, echo=FALSE}
knitr::opts_chunk$set(error=FALSE, warning=FALSE, message=FALSE)
```

# Data loading

Our `SummarizedExperiment` object contains all experimental data and metadata for this study.
Each row corresponds to a barcode while each column corresponds to a sample.

```{r} 
:BEGIN create-se
:END
original <- se # making a copy for downstream use.
se
```

:BEGIN subset-se
We subset the `SummarizedExperiment` to the desired levels of a factor of interest.

```{r}
sub.factor <- <%= SUBSET_FACTOR %>
sub.levels <- <%= SUBSET_LEVELS %>
se <- se[,SummarizedExperiment::colData(se)[,sub.factor] %in% sub.levels]
subset.meta <- sprintf("%s IN (%s)", sub.factor, paste(sub.levels, collapse=","))
ncol(se)
```
:END

:BEGIN subset-group
We subset the `SummarizedExperiment` to the groups involved in the comparison.
This ensures that our variance estimates are not affected by irrelevant variability in other groups.

```{r}
se <- se[,SummarizedExperiment::colData(se)[,<%= GROUP_FACTOR %>] %in% <%= GROUP_LEVELS %>]
ncol(se)
```
:END

We extract the information into a `DGEList` object in preparation for analysis.

```{r}
y <- edgeR::DGEList(SummarizedExperiment::assay(se, <%= ASSAY %>))

# Also tracking the original row index from the SummarizedExperiment,
# so that we can match them up after filtering out low-abundance barcodes.
y$genes <- data.frame(origin=seq_len(nrow(se)))
```

Finally, we build the design matrix.

```{r}
:BEGIN design-matrix
:END
```

# Barcode filtering 

:BEGIN ref-filtering
We filter out barcodes that were not present in the original pool, e.g., due to manufacturing defects in the screen library.
We use a subset of reference samples to compute the abundances in the pool,
and we define a threshold on the log-average CPM by defining small outliers based on the median absolute deviation.

```{r}
is.ref <- SummarizedExperiment::colData(original)[[<%= REFERENCE_FIELD %>]] %in% <%= REFERENCE_LEVELS %>
summary(is.ref)

ref.counts <- SummarizedExperiment::assay(original, <%= ASSAY %>)[,is.ref,drop=FALSE]
ref.non.empty <- which(Matrix::rowSums(ref.counts) > 0) # ignoring all-zero rows.
ref.ab <- edgeR::aveLogCPM(ref.counts[ref.non.empty,,drop=FALSE])
hist(ref.ab, xlab="Reference average log-CPM") 

# Defining the threshold. 
ref.med.ab <- median(ref.ab)
ref.med.ab
ref.mad.ab <- mad(ref.ab, center=ref.med.ab)
ref.threshold <- ref.med.ab - <%= NUM_MADS %> * ref.mad.ab
ref.threshold

# Applying the filter.
ref.filtered <- logical(nrow(y))
ref.filtered[ref.non.empty] <- ref.ab >= ref.threshold
summary(ref.filtered)
y <- y[ref.filtered,]
```

:END

:BEGIN filter-default
We also filter out low-abundance barcodes to improve the accuracy of the mean-variance trend fit.
This also reduces computational work and the severity of the multiple testing correction.
We use `r BiocStyle::Biocpkg("edgeR")`'s default filtering strategy,
which only retains barcodes with coverage above a threshold in at least $n$ samples.

```{r}
filtered <- edgeR::filterByExpr(y, <%= FILTER_OPTS %>, large.n=0)
y <- y[filtered,]
summary(filtered)
```

The minimum threshold is defined as a CPM equivalent to a count of 10, adjusted for differences in library size.
$n$ is defined as 70% of the size of the smallest group in the experimental design.
(We set `large.n=0` to allow a barcode to be below the threshold in some of the samples of a small group.) 
:END

:BEGIN filter-none
We'll omit the filtering - all barcodes will be tested for differential abundance.
:END
