% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diffExpr.R
\name{diffExpr}
\alias{diffExpr}
\title{Main wrapper for executing the entire pipeline from reading in expression data such as count
files to producing text files and graphs}
\usage{
diffExpr(
  expr.dat,
  samp.info,
  control,
  design = NULL,
  samples = NULL,
  sample.plot.names = NULL,
  groups = NULL,
  pairs = NULL,
  block = FALSE,
  contrasts = NULL,
  out.dir = NULL,
  analysis.name = NULL,
  filter.strict = TRUE,
  filter.min.samp = NULL,
  fit.voom = FALSE,
  fit.voom.fun = "voomLmFit",
  fit.use.weights = FALSE,
  fit.norm.method = c("tmm", "quantile"),
  fit.disp = c("gene", "trend", "common"),
  fit.bayes.trend = FALSE,
  fit.bayes.robust = FALSE,
  fit.quasi.likelihood = NA,
  p.thr = 0.05,
  fdr.thr = 0.05,
  logfc.thr = 1,
  numlab = 25,
  point.lab = TRUE,
  de.plot.base.size = 16,
  biom.use = FALSE,
  biom.data.set = "hsapiens_gene_ensembl",
  biom.mart = "ensembl",
  biom.host = "https://www.ensembl.org",
  biom.timeout = 10,
  biom.filter = "ensembl_gene_id",
  biom.attributes = c("ensembl_gene_id", "hgnc_symbol", "description", "entrezgene_id"),
  biom.force.ensg = FALSE,
  biom.cache = NULL,
  biom.use.cache = FALSE,
  biom.sym.col = "hgnc_symbol",
  biom.rm.dups = FALSE,
  qc.top.n = 500,
  qc.gene.selection = "common",
  qc.pc = c(1, 2, 3),
  qc.type = c("both", "uncorrected", "pseudo-corrected"),
  qc.ellipse = TRUE,
  qc.ellipse.groups = NULL,
  qc.ellipse.legend = NA,
  qc.label.samples = TRUE,
  qc.point.size = 2,
  qc.label.size = 5,
  qc.circle = TRUE,
  qc.varname.size = 0,
  qc.var.axes = FALSE,
  hm.topn = 100,
  hm.p.thr = 0.05,
  hm.fdr.thr = 0.05,
  hm.logfc.thr = 1,
  hm.split.expr = FALSE,
  hm.pal.blind = "PuOr",
  hm.pal.n = 11,
  hm.pal.extremes = c("#3182BD", "#E6550D"),
  hm.pal.length = NULL,
  hm.anno.color = NULL,
  hm.anno.name = "Sample Class",
  enr.do = TRUE,
  enr.methods = c("clusterProfilerGO", "clusterProfilerKEGG", "gProfileR", "topGO"),
  enr.plot = FALSE,
  enr.plot.fdr.thr = fdr.thr,
  enr.plot.logfc.thr = logfc.thr,
  enr.plot.num.terms = 5,
  out.plots = TRUE,
  out.tables = TRUE,
  out.filtered.tables = TRUE,
  verbose = TRUE,
  log.file = NULL,
  dry.run = FALSE
)
}
\arguments{
\item{expr.dat}{\code{character} or \code{list}. String or vector or list of input file paths, or matrix of count values}

\item{samp.info}{\code{data.frame}. samp.info object containing information of the project's sample sheet}

\item{control}{\code{character}. Name of the control group}

\item{design}{\code{matrix}. design matrix}

\item{samples}{\code{character}. Name of the column in 'samp.info' containing sample names. If 'samp.info' is not supplied
vector of sample names.}

\item{sample.plot.names}{\code{character}. Optional name of a column with "nice" sample names for plotting.}

\item{groups}{\code{character}. Name of the column in 'samp.info' containing grouping information. If 'samp.info' is not supplied
vector of groups.}

\item{pairs}{\code{character}. Name of the column in 'samp.info' containing paired sample information.}

\item{block}{\code{logical}. Are the samples not independent? See Details section.}

\item{contrasts}{\code{character}. Vector of contrasts to be made. If not provided, all possible contrasts will be made.
This specifies group name pairs to be compared in the format expected by \code{makeContrasts()}, i.e., "group2-group1".}

\item{out.dir}{\code{character}. Path to the output directory. This argument is required: all
result tables, plots and the run log are written below it. There is deliberately no default,
so that no files are ever created in the working directory unintentionally. Use, e.g.,
\code{out.dir = tempdir()} to try the pipeline out without keeping the results.}

\item{analysis.name}{\code{character}. Name of the analysis. If not provided, a default name will be generated.}

\item{filter.strict}{\code{logical}. For miRNA analysis: only keep a miRNA if there are > 5 reads per million in at least half of the samples?}

\item{filter.min.samp}{\code{integer}. Number of samples in which a feature needs to be covered by at least one read per million.
Defaults to the size of the smallest group of replicates. See \emph{details}.}

\item{fit.voom}{\code{logical}. Should the voom function be used? Defaults to \code{FALSE}.}

\item{fit.voom.fun}{\code{character}. The voom function to be used. Should be one of 'limma::voom', 'limma::voomWithQualityWeights' or
'edgeR::voomLmFit'. Defaults to \code{edgeR::voomLmFit}. See 'Details'.}

\item{fit.use.weights}{\code{logical}. Should sample-specific quality weights be estimated?}

\item{fit.norm.method}{\code{character}. The normalisation method to be used. Defaults to "tmm".}

\item{fit.disp}{\code{character}. The dispersion method to be used. Defaults to "gene".}

\item{fit.bayes.trend}{\code{logical}. Should an intensity-trend be allowed for the prior variance? Passed to 'limma::eBayes'.}

\item{fit.bayes.robust}{\code{logical}. Should the estimation of df.prior and var.prior be robustified against outlier sample variances? Passed to 'limma::eBayes'.}

\item{fit.quasi.likelihood}{Logical; should quasi-likelihood methods be used? See \emph{Details} section.
Defaults to NA, which will determine the method based on the number of replicate samples.
If more than 4 replicates are present, the likelihood ratio test is used, otherwise the quasi-likelihood methods.
If \code{TRUE}, then the quasi-likelihood methods are used, if \code{FALSE}, then the likelihood ratio test is used.}

\item{p.thr}{\code{numeric}. Threshold for p-values. Defaults to 0.05.}

\item{fdr.thr}{\code{numeric}. Threshold for FDR values. Defaults to 0.05.}

\item{logfc.thr}{\code{numeric}. Threshold for fold-change values on the log2-scale. Defaults to 1.}

\item{numlab}{\code{numeric}. Maximum number of point labels to be shown in the plot. This overrides/limits
values calculated by any thresholds. Defaults to 25.}

\item{point.lab}{\code{logical}. Should point labels be shown in the plot? Defaults to \code{TRUE}.}

\item{de.plot.base.size}{\code{numeric}. Overall text/point scale (the `ggplot2` \code{base_size}) for the
M-A and volcano plots, defaulting to 16. Raising it enlarges legend, axes, titles, point labels and
points together. The default (16, up from the `ggplot2` default of ~11) keeps text readable on the
default per-contrast plot PDF, which is opened at 15x15 inches to hold the heatmaps.}

\item{biom.use}{\code{logical}. Should the biomart be used for gene annotation? Defaults to \code{FALSE}.}

\item{biom.data.set}{\code{character}. The biomart dataset to be used. Defaults to "hsapiens_gene_ensembl".}

\item{biom.mart}{\code{character}. The biomart to be used.}

\item{biom.host}{\code{character}. The host to be used for the biomart. Defaults to "www.ensembl.org".}

\item{biom.timeout}{\code{numeric}. Time budget in seconds for each attempt of the BioMart
availability check performed at the start of a run when \code{biom.use=TRUE}. A host that does
not answer within this budget is treated as unreachable, so a server that is down costs seconds
rather than a full network timeout per candidate host. This applies only to the reachability
probe, never to the annotation query itself, which may legitimately take much longer. Raise it
if a slow but working mart is being rejected. Defaults to 10.}

\item{biom.filter}{\code{character}. The biomart filter to be used. Defaults to "ensembl_gene_id".}

\item{biom.attributes}{\code{character}. The biomart attributes to be used. Defaults to c("ensembl_gene_id", "hgnc_symbol", "description", "entrezgene_id").}

\item{biom.force.ensg}{\code{logical}. Should Ensembl Gene IDs be checked for (and stripped of) Ensembl version numbers? Defaults to \code{FALSE}.}

\item{biom.cache}{\code{character}. Path name giving the location of the cache \command{getBM()} uses if \code{use.cache=TRUE}. Defaults to the value in the \emph{BIOMART_CACHE} environment variable.}

\item{biom.use.cache}{(\code{logical}). Should \command{getBM()} use the cache? Defaults to \code{TRUE} as in the \command{getBM()} function and is passed on to that.}

\item{biom.sym.col}{\code{character}. Name of the column in the query result with gene symbols}

\item{biom.rm.dups}{\code{logical}. Should duplicates be removed from the output of the biomart request? Defaults to \code{FALSE}.}

\item{qc.top.n}{\code{integer}. Passed to \code{plotMDS()} (\code{top}): number of top genes used to calculate pairwise distances. Defaults to 500.}

\item{qc.gene.selection}{\code{character}. passed to \code{plotMDS()} specifying the mode to select genes for comparisons. Defaults to "common".}

\item{qc.pc}{\code{numeric}. Which principal components to plot. Defaults to 1:3.}

\item{qc.type}{\code{character}. Which type of plot to produce. Needs to be one of "both", "uncorrected", "pseudo-corrected"
describing which values should be plotted. "uncorrected" will plot the input counts matrix while
"pseudo-corrected" will plot pseudo counts for blocked designs (e.g., paired samples or batch factors).
Defaults to "both".}

\item{qc.ellipse}{\code{logical}. Should an ellipse be plotted around samples belonging to the same sample group? Defaults to \code{TRUE}.}

\item{qc.ellipse.groups}{\code{character} The name of the column in 'samp.info' with group names for ellipse drawing. If \code{NULL} (default)
will use the \code{groups} column. If 'samp.info' is not supplied vector of groups.}

\item{qc.ellipse.legend}{\code{logical}. Should a legend be added for ellipses in PCA plots? NA, the default, includes
if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select
the aesthetics to display.}

\item{qc.label.samples}{\code{logical}. Should points in appropriate QC plots be labelled. So far, applies only to PCA ggplot. Defaults to \code{TRUE}.}

\item{qc.point.size}{\code{numeric}. Size of points in appropriate QC plots. So far, applies only to PCA ggplot. Defaults to 2.}

\item{qc.label.size}{\code{numeric}. Font size used for point labels in appropriate QC plots. So far, applies to PCA ggplot and M-A plots. Defaults to 5.}

\item{qc.circle}{\code{logical}. Draw a correlation circle around points representing correlating samples? Only applies when prcomp was called with scale = TRUE and when var.scale = 1. Defaults to \code{TRUE}.}

\item{qc.varname.size}{\code{numeric}. Size of the text for variable names. Defaults to 0.}

\item{qc.var.axes}{\code{logical}. Draw arrows for the variables? Defaults to \code{FALSE}.}

\item{hm.topn}{\code{numeric}. Number of top values to be plotted. Defaults to 100.}

\item{hm.p.thr, hm.fdr.thr, hm.logfc.thr}{\code{numeric}. Significance and fold-change thresholds used
specifically for selecting genes shown in the heatmaps, kept separate from \option{p.thr},
\option{fdr.thr} and \option{logfc.thr} (which control the plots and tables) because heatmaps
usually read best with a stricter gene set. Default to 0.05, 0.05 and 1.}

\item{hm.split.expr}{\code{logical}. Should the top up- and top down-regulated genes be displayed at equal numbers (50/50),
if they meet the significance threshold (regardless of the actual significance)? Defaults to \code{FALSE}.}

\item{hm.pal.blind}{string determining the RColorBrewer color blind palette (default = "PuOr");
other option can be visualized with the following command: brewer.pal.info[brewer.pal.info$colorblind,]}

\item{hm.pal.n}{desired length of the number of different colours in 'color.blind.pal'. Will also be used
as length of the numeric vector of probabilities in 'quantile_breaks()' (see ?quantile); defaults to 11}

\item{hm.pal.extremes}{character vector of length 2 giving the two extremes of a user-defined colour palette
varying from the first hue to the second via white.}

\item{hm.pal.length}{integer setting the desired length of the colour palette to be used in the heatmap}

\item{hm.anno.color}{list of named character vectors giving the colours used in the heatmap annotation bars. See 'annotation_colors'
in [pheatmap()]. Automatically generated if NULL (default).}

\item{hm.anno.name}{character string used as the column annotation legend title. If 'anno.color' is not NULL and of length 1 the slot name will be used if existing.}

\item{enr.do}{\code{logical}. Whether or not to call enrichment wrapper. Defaults to \code{TRUE}.}

\item{enr.methods}{\code{character}. One or more of the following: c("clusterProfilerGO", "clusterProfilerKEGG", "gProfileR", "topGO"). By default, uses them all.}

\item{enr.plot}{\code{logical}. Whether or not to draw a network plot for the enrichment results. Defaults to \code{FALSE}.}

\item{enr.plot.fdr.thr}{\code{numeric}. FDR threshold used in the enrichment plot. This may be useful to tweak to produce a more informative plot.
Defaults to 0.05.}

\item{enr.plot.logfc.thr}{\code{numeric}. FC threshold on the log2-scale used in the enrichment plot. Defaults to 1.}

\item{enr.plot.num.terms}{\code{integer}. Number of terms shown in the plot. Defaults to 5.}

\item{out.plots}{\code{logical}. Should plots be produced? Defaults to \code{TRUE}.}

\item{out.tables}{\code{logical}. Should lists of differentially expressed genes be produced? Defaults to \code{TRUE}.}

\item{out.filtered.tables}{\code{logical}. Should lists of differentially expressed genes be produced for filtered data? Defaults to \code{TRUE}.}

\item{verbose}{\code{logical} or \code{character}. Controls console output. \code{TRUE} (default) prints
major workflow steps, \code{FALSE} prints nothing, and \code{"all"} mirrors the full detail of the log
file to the console. Console output is written to \code{stdout} and is controlled solely by this argument.
Irrespective of this setting, the complete log is always written to \option{log.file}.}

\item{log.file}{\code{character}. Path to the run log file. If \code{NULL} (default), a log file named
\emph{<analysis.name>_diffwrap.log} is created in \option{out.dir}. No log file is written if
\code{dry.run=TRUE}.}

\item{dry.run}{\code{logical}. If \code{TRUE}, the function will not create any output files or directories.}
}
\value{
A list of all relevant objects generated in the course of the workflow:
\itemize{
  \item if `voom=TRUE`, voomed counts, otherwise DGEList object with TMM-normalisation factors
  \item if `voom=TRUE`, lmFit object, otherwise DGEList object with estimated dispersion
  \item if `voom=TRUE`, eBayes output of contrasted groups, otherwise glmFit object
  \item annotated topTable/topTags output
}
However, the function is first and foremost called for its side effects of generating results tables and plots.
}
\description{
\command{diffExpr} is a convenience wrapper performing all steps automatically.
   Most sub-functions are exported and can be called by the user, as well, if desired.
   These functions may be applicable to different kinds of data/input, rely, however,
   on the conventions set for this package.
}
\details{
For experimental designs involving comparisons within as well as between subjects inter-subject needs to be computed.
    In this case, the column specified in the 'pairs' argument must assign the subjects to the treatment/tissue/etc groups.
    For example, if we have two treatments the effects of which are to be observed in each two tissues, this design would apply.
    The 'pairs' factor is passed to the functions 'duplicateCorrelation()' and 'lmFit()'.
    The 'block' argument is used to specify whether the comparisons are to be made within AND between subjects or in the case of
    technical replicates, i.e., if the samples are not independent, in other words, correlated. That correlation is addressed by
    means of the 'duplicateCorrelation()' function in the limma package.
    If 'block' is set to \code{TRUE}, the (selected) 'voom' function is enforced.
    As of version 0.4, the 'edgeR::voomLmFit()' function is incorporated, which replaces 'voom()', 'lmFit()' and
    'voomWithQualityWeights()'. voomLmFit()' ensures unbiased estimation of the residual variances and automates the estimation
    of sample weights and intrablock correlations.
    In edgeR, it is recommended to remove features without at least 1 read per million in n of the
    samples, where n is the size of the smallest group of replicates (determined from the 'groups' vector).
    The 'min.samp' argument is used to specify the number of samples in which a feature needs to be covered by at least one read per million.
    Quasi-likelihood pipeline:
    While the likelihood ratio test is a more obvious choice for inferences with GLMs, the QL
    F-test is preferred as it reflects the uncertainty in estimating the dispersion for each gene. It
    provides more robust and reliable error rate control when the number of replicates is small.
    The QL dispersion estimation and hypothesis testing is done by using the functions
    glmQLFit() and glmQLFTest().
}
\section{Argument groups}{

The arguments are grouped by name prefix:
\itemize{
  \item no prefix: core experiment definition, plus the primary differential-expression thresholds
    (\code{p.thr}, \code{fdr.thr}, \code{logfc.thr}, \code{numlab}, \code{point.lab});
  \item \code{filter.*}: count pre-filtering;
  \item \code{fit.*}: model fitting (voom / edgeR options);
  \item \code{biom.*}: 'biomart' gene annotation;
  \item \code{qc.*}: quality-control plots (MDS / PCA);
  \item \code{hm.*}: heatmaps, including their own significance thresholds and colour palette;
  \item \code{enr.*}: enrichment analysis;
  \item \code{out.*}, \code{verbose}, \code{log.file}, \code{dry.run}: output and run control.
}
}

\examples{
\donttest{
out.dir <- file.path(tempdir(), "diffwrap_demo")
dir.create(out.dir, showWarnings = FALSE)
res <- diffExpr(expr.dat = diffwrap_counts,
                samp.info = diffwrap_samp_info,
                samples = "SampleName", groups = "Group",
                control = "control", analysis.name = "demo",
                out.dir = out.dir, enr.do = FALSE)
names(res$contrasts)
}
}
