% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/de_util.R
\name{diff_expr_extract_contrasts}
\alias{diff_expr_extract_contrasts}
\title{Function to extract contrasts and generate top tables and plots}
\usage{
diff_expr_extract_contrasts(
  contrasts = NULL,
  fit,
  fit2 = NULL,
  normcnt,
  out.l,
  do.voom = TRUE,
  quasi.likelihood = TRUE,
  out.dir,
  analysis.name = NULL,
  biomart = FALSE,
  biom.data.set = "hsapiens_gene_ensembl",
  biom.mart = "ensembl",
  host = "https://www.ensembl.org",
  biom.filter = "ensembl_gene_id",
  biom.attributes = c("ensembl_gene_id", "hgnc_symbol", "description"),
  biom.force.ensg = FALSE,
  biom.cache = NULL,
  use.cache = FALSE,
  sym.col = "hgnc_symbol",
  rm.dups = FALSE,
  p.thr = 0.05,
  fdr.thr = 0.05,
  logfc.thr = 1,
  numlab = 25,
  point.lab = TRUE,
  heatmap.topn = 100,
  hm.p.thr = 0.05,
  hm.fdr.thr = 0.05,
  hm.logfc.thr = 1,
  heatmap.split.expr = FALSE,
  color.blind.pal = "PuOr",
  n.pal.cols = 11,
  color.extremes = c("#3182BD", "#E6550D"),
  palette.length = NULL,
  anno.color = NULL,
  anno.name = "Sample Class",
  heatmap.main = NULL,
  font.size = 5,
  plots = TRUE,
  lists = TRUE,
  filtered.lists = TRUE,
  samp.info = NULL,
  samples = NULL,
  groups = NULL,
  sample.plot.names = NULL,
  de.plot.base.size = 16
)
}
\arguments{
\item{contrasts}{Contrast matrix as generated by \code{makeContrasts()}. If \code{NULL}, the default, the design matrix
is expected to describe simple pair-wise comparisons, i.e., with the contrasts already included in the matrix.
Consequently, in that case, no contrasts will be fitted.}

\item{fit}{An MArrayLM object produced by \code{lmFit}.}

\item{fit2}{An MArrayLM object produced by \code{eBayes}.}

\item{normcnt}{Matrix; depth-adjusted reads per million or "voomed" counts, i.e., a numeric matrix of
normalized expression values on the log2 scale.}

\item{out.l}{List; list of result objects generated upstream in the workflow to add output from this function to.}

\item{do.voom}{Logical; should data be "voomed"?}

\item{quasi.likelihood}{Logical; should quasi-likelihood methods be used? See \emph{Details} section.
If \code{TRUE}, the default, then the quasi-likelihood methods are used, if \code{FALSE}, then the
likelihood ratio test is used. Please note the main wrapper function \code{diffExpr()} will set this parameter.}

\item{out.dir}{Character; output directory for final tables. Required; no default is used so that nothing is written to the working directory unintentionally.}

\item{analysis.name}{Character used in the output file name.}

\item{biomart}{Logical; should biomart annotation be added?}

\item{biom.data.set}{\code{character} of length one. Biomart data set to use.}

\item{biom.mart}{\code{character} vector. Biomart to use (uses the first element of the vector), defaults to "ensembl".}

\item{host}{\code{character} of length one. Host URL.}

\item{biom.filter}{\code{character} of length one. Name of biomart filter, i.e., type of query ids, defaults to "ensembl_gene_id".}

\item{biom.attributes}{\code{character} vector. Biomart attributes, i.e., type of desired result(s); make sure query id type is included!}

\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{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{sym.col}{\code{character}. Name of the column in the query result with gene symbols.}

\item{rm.dups}{\code{logical}. Should duplicated input IDs (\option{biom.filter}) be removed from the result?}

\item{p.thr}{Numeric; P-Value threshold used in plots.}

\item{fdr.thr}{Numeric; FDR threshold used in plots and for generating cleaned output tables.}

\item{logfc.thr}{Numeric; FC threshold on the log2-scale used in plots and for generating cleaned output tables.}

\item{numlab}{\code{numeric}. Maximum number of labels per plot. Overrides numbers calculated based on `p.thr` and `fdr.thr`.}

\item{point.lab}{\code{logical}. Should points be labelled, at all?}

\item{heatmap.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 when selecting genes for the heatmaps. These are kept separate from the plot/table
thresholds (\option{p.thr}, \option{fdr.thr}, \option{logfc.thr}) because heatmaps usually read best
with a stricter gene set. Default to 0.05, 0.05 and 1.}

\item{heatmap.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{color.blind.pal}{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{n.pal.cols}{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{color.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{palette.length}{integer setting the desired length of the colour palette to be used in the heatmap}

\item{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{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{heatmap.main}{\code{character}. Additional information printed in the heatmap title.}

\item{font.size}{\code{numeric}. Size of point labels in M-A plots.}

\item{plots}{Logical; should plots be generated?}

\item{lists}{Logical; should output tables be written to files?}

\item{filtered.lists}{Logical; should the DGE table be filtered before saving it to a file?}

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

\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{groups}{\code{character}. Name of the column in 'samp.info' containing grouping information. If 'samp.info' is not supplied
vector of groups.}

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

\item{de.plot.base.size}{\code{numeric}. Overall text/point scale (`ggplot2` \code{base_size}, default 16)
passed to the M-A and volcano plots. Raise it so labels and legends stay readable on the large
per-contrast PDF (opened at 15x15 inches).}
}
\value{
The input list \option{out.l}, extended with a \code{contrasts} element holding one annotated
  result \code{data.frame} per contrast and, if plots were requested, with the \code{MAplots},
  \code{volcanoPlots} and \code{heatmapPlots} elements. Called also for its side effects of writing
  result tables, plot files and Venn section spreadsheets below \option{out.dir}.
}
\description{
Function to extract contrasts and generate top tables and plots
}
\examples{
\donttest{
si <- diff_expr_get_samp_info(diffwrap_samp_info, "SampleName", "Group")
counts <- diff_expr_filter_counts(diff_expr_read_counts(diffwrap_counts, si), si)
groups <- stats::relevel(si$Groups, ref = "control")
d <- edgeR::calcNormFactors(edgeR::DGEList(counts, group = groups))
design <- diff_expr_make_design(si, groups)
contrasts <- diff_expr_make_contrasts(design, groups)
fit <- diff_expr_fit(counts, d, design, do.voom = FALSE, quasi.likelihood = TRUE)
normcnt <- edgeR::cpm(fit$d2, log = TRUE)
out <- diff_expr_extract_contrasts(contrasts = contrasts, fit = fit$fit,
                                   normcnt = normcnt, out.l = list(),
                                   do.voom = FALSE, out.dir = tempdir(),
                                   analysis.name = "demo", plots = FALSE,
                                   samp.info = si, samples = "SampleNames",
                                   groups = groups)
names(out$contrasts)
}
}
