% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/runScreen.R
\name{runScreen}
\alias{runScreen}
\title{Differential abundance for functional screens}
\usage{
runScreen(
  x,
  groups,
  comparisons,
  covariates = NULL,
  block = NULL,
  subset.factor = NULL,
  subset.levels = NULL,
  subset.groups = TRUE,
  design = NULL,
  contrasts = NULL,
  dc.block = NULL,
  robust = TRUE,
  trend = FALSE,
  quality = TRUE,
  lfc.threshold = 0,
  filter.reference.factor = NULL,
  filter.reference.levels = NULL,
  filter.num.mads = 3,
  filter.default = TRUE,
  norm.control.barcodes = NULL,
  norm.control.genes = NULL,
  norm.control.type.field = NULL,
  norm.control.types = NULL,
  norm.tmm = TRUE,
  gene.field = NULL,
  report.summary = TRUE,
  summary.threshold = 0.05,
  consolidation = c("simes", "fry", "holm-min"),
  fry.args = list(),
  holm.min.n = 3,
  holm.min.prop = 0.3,
  assay = 1,
  row.data = gene.field,
  gene.data = NULL,
  metadata = NULL,
  output.dir = "voom",
  author = NULL,
  dry.run = FALSE,
  save.results = TRUE,
  suppress.plots = FALSE
)
}
\arguments{
\item{x}{A \link[SummarizedExperiment]{SummarizedExperiment} object containing read counts for each barcode (row) and sample (column).
Alternatively, the output of \code{\link[augere.core]{wrapInput}} that refers to a SummarizedExperiment.}

\item{groups}{String specifying the \code{\link[SummarizedExperiment]{colData}(x)} column containing the grouping factor of interest,
see \code{\link[augere.de]{processSimpleDesignMatrix}} for more details.
This may be \code{NULL} for experimental designs with no groups, e.g., \code{covariates} only.
Ignored if \code{design} and \code{contrasts} are provided.}

\item{comparisons}{Character vector specifying two or more groups to compare from \code{groups}, or the covariate to be tested from \code{covariates}.
Alternatively, or a list of such character vectors specifying multiple comparisons to perform.
See \code{\link[augere.de]{processSimpleComparisons}} for more details.
Ignored if \code{design} and \code{contrasts} are provided.}

\item{covariates}{Character vector specifying the \code{\link[SummarizedExperiment]{colData}(x)} columns containing continuous covariates of interest,
see \code{\link[augere.de]{processSimpleDesignMatrix}} for more details.
Ignored if \code{design} and \code{contrasts} are provided.}

\item{block}{Character vector specifying the \code{\link[SummarizedExperiment]{colData}(x)} columns containing additional (uninteresting) blocking factors,
see \code{\link[augere.de]{processSimpleDesignMatrix}} for more details.
Ignored if \code{design} and \code{contrasts} are provided.}

\item{subset.factor}{String specifying the \code{\link[SummarizedExperiment]{colData}(x)} column containing the factor to use for subsetting.}

\item{subset.levels}{Vector containing the levels of the \code{subset.factor} to be retained.}

\item{subset.groups}{Boolean indicating whether to automatically subset the dataset to only those samples assigned to groups in \code{comparisons}.
Setting this to \code{TRUE} sacrifices some residual degrees of freedom for greater robustness against variability in irrelevant groups.
Ignored if \code{design} and \code{contrasts} are provided.
Also ignored if \code{covariates} is provided, as all samples are informative for a continuous covariate.}

\item{design}{Matrix, function, or formula specifying the experimental design, see \code{\link[augere.de]{processCustomDesignMatrix}} for details.
If this and \code{contrasts} are specified, \code{groups}, \code{block}, \code{covariates}, \code{comparisons} and \code{subset.groups} are ignored.}

\item{contrasts}{String, function or matrix specifying a custom contrast, or a list of such objects; see \code{\link[augere.de]{processCustomContrasts}} for details.
If this and \code{design} are specified, \code{groups}, \code{block}, \code{covariates}, \code{comparisons} and \code{subset.groups} are ignored.}

\item{dc.block}{String specifying the blocking factor to use in \code{\link[limma]{duplicateCorrelation}}.
Typically used for uninteresting factors that cannot be used in \code{block} as they are confounded with the factors of interest.
No additional blocking is performed if \code{NULL}.}

\item{robust}{Boolean indicating whether robust empirical Bayes shrinkage should be used in \code{\link[limma]{eBayes}}.
Setting this to \code{TRUE} sacrifices some precision for improved robustness against genes with extreme variances.}

\item{trend}{Boolean indicating whether variances should be shrunk towards a trend in \code{\link[limma]{eBayes}}.
Usually unnecessary as the observation weights already account for the mean-variance relationship.}

\item{quality}{Boolean indicating whether quality weighting should be performed.
This reduces the influence of low-quality samples at the cost of more computational work.}

\item{lfc.threshold}{Number specifying a threshold on the log-fold change in \code{\link[limma]{treat}}.
If zero, \code{\link[limma]{eBayes}} will be used instead.}

\item{filter.reference.factor}{String specifying \code{\link[SummarizedExperiment]{colData}(se)} column that indicates whether a sample is a reference.
This is used to filter out barcodes that are not present in the original barcode library.}

\item{filter.reference.levels}{Character vector containing the reference levels in the \code{filter.reference.factor} column.
Only used if \code{filter.reference.factor} is supplied.}

\item{filter.num.mads}{Number specifying the number of median absolute deviations below the median to define an outlier threshold for filtering barcodes.
Only used if \code{filter.reference.factor} is supplied.}

\item{filter.default}{Boolean indicating whether to filter barcodes using the default \pkg{edgeR} method, i.e., \code{\link[edgeR]{filterByExpr}}.
If \code{TRUE} and \code{filter.reference.factor} is supplied, the default filtering is applied in addition to the reference-based filtering.
Otherwise, it is applied alone.}

\item{norm.control.barcodes}{A named list of character vectors containing one or more sets of control barcodes.
Each vector should contain the names of barcodes, corresponding to the row names of \code{se}.
The names of the vectors will be stored in the metadata.}

\item{norm.control.genes}{A named list containing one or more sets of control genes.
Each vector should contain the names of genes, corresponding to the entries of the \code{gene.field} column.
The names of the vectors will be stored in the metadata.
Only used if \code{gene.field} is supplied.}

\item{norm.control.type.field}{String specifying the \code{\link[SummarizedExperiment]{rowData}(se)} column containing the feature type for each barcode.}

\item{norm.control.types}{Character vector containing the control feature types in the \code{norm.type.field} column. 
Only used if \code{norm.type.field} is supplied.}

\item{norm.tmm}{Boolean indicating whether TMM normalization should be used.
If \code{FALSE}, normalization is instead performed using the library size for each sample.}

\item{gene.field}{String specifying the \code{rowData(se)} column that contains the gene identity for each barcode.
If \code{NULL}, consolidation of barcode-level statistics into per-gene inferences will not be performed.}

\item{report.summary}{Boolean indicating whether to report barcode-level summaries within the per-gene data frames.
Only used if \code{gene.field} is supplied.}

\item{summary.threshold}{Number specifying the FDR threshold when summarizing the number of significant barcodes per gene.
Only used if \code{report.summary=TRUE}.}

\item{consolidation}{Character vector specifying the consolidation method(s) to convert per-barcode statistics into per-gene results.
This can be zero, one or more of:
\itemize{
\item \code{"simes"}, which uses \code{\link[metapod]{groupedSimes}} to combine barcode-level p-values into a single per-gene p-value. 
This is the most sensitive approach for detecting a small number of barcodes (possibly just 1) that are differentially abundant.
\item \code{"holm-min"}, which uses \code{\link[metapod]{groupedHolmMin}} to combine barcode-level p-values into a single per-gene p-value. 
This should be used when a minimum number/proportion of barcodes for a gene is expected to exhibit differential abundance. 
\item \code{"fry"}, which uses \code{\link[limma]{fry}} to test for differential abundance across all barcodes for a gene.
This favors consistent differences across the majority of barcodes for a given gene.
However, it is not compatible with ANOVA-like contrasts and will ignore any \code{lfc.threshold > 0}.
}
Only used if \code{gene.field} is supplied.}

\item{fry.args}{Named list of additional arguments to pass to \code{\link[limma]{fry}}.}

\item{holm.min.n}{Integer specifying the minimum number of significant barcodes per gene when \code{consolidation="holm"},
see the \code{min.sig.n=} in \code{?\link[metapod]{groupedHolmMin}} for details.}

\item{holm.min.prop}{Integer specifying the minimum proportion of significant barcodes per gene when \code{consolidation="holm"},
see the \code{min.sig.prop=} in \code{?\link[metapod]{groupedHolmMin}} for details.}

\item{assay}{String or integer specifying the assay of \code{x} containing the count matrix.}

\item{row.data}{Character vector specifying the \code{\link[SummarizedExperiment]{rowData}(x)} columns containing extra gene annotations to include in the result DataFrames.}

\item{gene.data}{Character vector containing the names of \code{\link[SummarizedExperiment]{rowData}(se)} columns to add to the per-gene result tables.
If a gene has multiple barcodes, the row corresponding to the first barcode is used.}

\item{metadata}{Named list of additional metadata to store alongside each result.}

\item{output.dir}{String containing the path to an output directory in which to write the Rmarkdown file and save results.}

\item{author}{Character vector containg the names of the authors.
If \code{NULL}, defaults to the current user.}

\item{dry.run}{Boolean indicating whether to perform a dry run.
This generates the Rmarkdown report in \code{output.dir} but does not execute the analysis.}

\item{save.results}{Boolean indicating whether the results should be saved to file.}

\item{suppress.plots}{Boolean indicating whether plots should be suppressed.
This can be set to \code{TRUE} for faster execution.}
}
\value{
A Rmarkdown report named \code{report.Rmd} is written inside \code{output.dir} that contains the analysis commands.

If \code{dry.run=FALSE}, a list is returned containing:
\itemize{
\item \code{barcode}, a named list of \link[S4Vectors]{DataFrame}s containing barcode-level result tables.
Each DataFrame corresponds to a comparison/contrast where each row corresponds to a barcode (i.e., row) in \code{se}.
Each DataFrame contains the following columns:
\itemize{
\item \code{AveAb}, the average abundance.
\item \code{t}, the t-statistic.
(For non-ANOVA-like contrasts only.)
\item \code{F}, the F-statistic.
(For ANOVA-like contrasts only.)
\item \code{LogFC}, the log-fold change.
(For non-ANOVA-like contrasts only.)
\item \code{LogFC.<COLUMN>}, the log-fold change corresponding to each column of the contrast matrix.
(For ANOVA-like contrasts only.)
\item \code{PValue}, the p-value;
\item \code{FDR}, the Benjamini-Hochberg-adjusted p-value.
}
\item \code{gene}, a named list of lists containing one entry per method in \code{consolidation}.
Each inner list contains one \link[S4Vectors]{DataFrame} per contrast where each row corresponds to a gene (not barcode). 
Each DataFrame contains at least the following columns:
\itemize{
\item \code{NumBarcodes}, the number of barcodes per gene (possibly after filtering).
\item \code{PValue}, the p-value for differential abundance across all barcodes for the gene.
\item \code{FDR}, the Benjamini-Hochberg-adjusted p-value.
\item \code{Direction}, the overall direction of change for all barcodes of the gene.
(For non-ANOVA-like contrasts only.)
\item \code{NumUp}, the number of barcodes with a significant increase in abundance.
(For non-ANOVA-like contrasts only, when \code{report.summary=TRUE}.)
\item \code{NumDown}, the number of barcodes with a significant decrease in abundance.
(For non-ANOVA-like contrasts only, when \code{report.summary=TRUE}.)
\item \code{LogFC}, the log-fold change of the barcode with the lowest p-value.
(For non-ANOVA-like contrasts only, when \code{report.summary=TRUE}.)
\item \code{NumSig}, the number of significant barcodes.
(For ANOVA-like contrasts only, when \code{report.summary=TRUE}.)
\item \code{AveAb}, the average abundance of the barcode with the lowest p-value.
}
Only reported if \code{gene.field} is not \code{NULL}.
\item \code{normalized}, a copy of \code{x} with normalized abundance values, possibly subsetted by sample.
This contains:
\itemize{
\item \code{lib.size} and \code{norm.factors} columns in its \code{\link[SummarizedExperiment]{colData}},
containing the library sizes and normalization factors, respectively.
\item a \code{retained} column in its \code{\link[SummarizedExperiment]{rowData}},
indicating whether a gene was retained after filtering.
\item a \code{logcounts} assay, containing the log-normalized counts.
}
\code{normalized} may be subsetted by sample, depending on \code{subset.factor}, \code{subset.group}, etc.
}
If \code{save.results=TRUE}, the results are saved in a \code{results} directory inside \code{output}.

If \code{dry.run=TRUE}, \code{NULL} is returned.
Only the Rmarkdown report is saved to file.
}
\description{
Use \code{\link[limma]{voom}} to test for differential abundance of barcodes in a functional screen.
}
\section{Reference filtering}{

A reference sample should represent the barcode distribution before any perturbation, e.g., time zero in a time course.
All barcodes should have similar abundances in the reference samples as they should be present at the same molarity in the original barcode library.
If a barcode has very low abundance, it was probably missing from the original library due to some manufacturing defect.

To identify these low outliers, we compute the average abundance across reference samples for each barcode.
We define a filtering threshold based on the median absolute deviation (MAD) below the median of the average abundances across barcodes.
Barcodes with average abundances below this threshold are discarded.

% This approach is a little suspect if the reference samples are being compared as it's not independent of the comparison.
% Specifically, we could enrich for barcodes that are spuriously upregulated in the reference.
% Fortunately, the density of barcodes at the outlier filter boundary should be so low that any biases should not be noticeable.

We also use \code{\link[edgeR]{filterByExpr}} to remove low-abundance barcodes. 
This ensures that all remaining barcodes have sufficiently large counts for \code{\link[limma]{voom}}, 
especially if the reference samples themselves are not used in the rest of the analysis.
}

\section{Control normalization}{

Control barcodes might not target any gene (non-targeting controls, or NTCs) or they might target non-essential genes (NEGs).
We assume that such barcodes do not genuinely change in abundance across conditions, allowing us to use them to compute normalization factors.
The choice of control barcodes can be made by one or more of the \code{norm.barcodes}, \code{norm.genes} and \code{norm.types} arguments.
If more than one of these modes is provided, the union of barcodes is used. 

By default, we use TMM normalization (see \code{\link[edgeR]{calcNormFactors}}) on the control barcodes. 
This avoids composition biases and provides some robustness against changes in abundance due to inadvertent biological activity.
If \code{norm.tmm=FALSE}, we instead use the total sum of counts across the controls to derive normalization factors.
This can be more precise but is more sensitive to genuine changes in abundance.

If no control barcodes are specified, normalization uses all barcodes that remain after filtering.
If \code{norm.tmm=TRUE}, TMM normalization is performed on all (filtered) barcodes.
Otherwise, the total sum of counts across all (filtered) barcodes is used.
}

\examples{
# Creating an example dataset.
mu <- 2^runif(1000, 0, 5)
grouping <- rep(c("A", "B", "ctrl"), each=3)
counts <- matrix(rnbinom(length(mu)* length(grouping), mu=mu, size=20), ncol=length(grouping))
rownames(counts) <- sprintf("BARCODE-\%s", seq_along(mu))

library(SummarizedExperiment)
se <- SummarizedExperiment(list(counts=counts))
rowData(se)$type <- sample(c("NTC", "NEG", "other"), length(mu), replace=TRUE)
rowData(se)$gene <- paste0("GENE-", sample(LETTERS, length(mu), replace=TRUE))
colData(se)$group <- grouping

output <- tempfile()
res <- runScreen(
    se,
    groups="group",
    comparisons=c("A", "B"),
    norm.control.type.field="type",
    norm.control.types="NEG",
    filter.reference.factor="group",
    filter.reference.levels="ctrl",
    gene.field="gene",
    output.dir=output
)

list.files(output, recursive=TRUE)
res$barcode[[1]]
res$gene$simes[[1]]
res$normalized

}
\author{
Aaron Lun, Jean-Philippe Fortin
}
