% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/heatmap_plots.R
\name{pheatmap_plots}
\alias{pheatmap_plots}
\title{Function to generate heatmap of gene expression values}
\usage{
pheatmap_plots(
  d3,
  id,
  sym.col = "gene_symbol",
  samp.info,
  samples,
  groups,
  sample.plot.names = NULL,
  main = NULL,
  add.main = NULL,
  color.blind.pal = "PuOr",
  n.pal.cols = 11,
  color.extremes = c("#3182BD", "#E6550D"),
  palette.length = NULL,
  anno.color = NULL,
  anno.name = "Sample Class",
  p.thr = 0.05,
  fdr.thr = 0.05,
  logfc.thr = 1,
  topn = 100,
  split.expr = FALSE
)
}
\arguments{
\item{d3}{\code{data.frame}. Data frame containing all necessary columns to generate a heatmap with gene labels (at least p-values, FDR values, log-ratios and gene symbols or other IDs)}

\item{id}{\code{character}. Name of the gene ID column. Can be the same as `sym.col` but usually refers to an additional column with, e.g., Ensembl Gene IDs.}

\item{sym.col}{\code{character}. Name of column with gene symbols, e.g., HGNC Symbols.}

\item{samp.info}{\code{data.frame}. 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}{Factor of sample groups for colouring and legend.}

\item{sample.plot.names}{\code{character}. Optional name of a column with "nice" sample names for plotting.
Need to be in the same order as sample column names!}

\item{main}{\code{character}. Main plot title. (Will be complemented with additional information, e.g., 'FDR' when
labelling according to and FDR threshold.)}

\item{add.main}{\code{character}. Additional information printed in the heatmap title.}

\item{color.blind.pal}{string determining the color-blind-friendly palette; must be one of
RColorBrewer's diverging palettes (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); must be within 3:11; 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{p.thr}{\code{numeric}. Plotted values with a P-Value below this threshold will be labelled in the P-Value plot.}

\item{fdr.thr}{\code{numeric}. Plotted values with a FDR below this threshold will be labelled in the FDR plot.}

\item{logfc.thr}{\code{numeric}. FC threshold on the log2-scale. Only used if 'split.expr' is TRUE. Values above this
threshold will be retained. Defaults to 1.}

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

\item{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}.}
}
\value{
Returns a named \code{list} of heatmap objects: an element \code{fdr} (built from the
  FDR-filtered genes) and/or \code{pval} (used only when nothing passes the FDR threshold), each a
  list holding the \code{regular} heatmap and the gene/sample \code{correlogram} objects. Also
  called for its side effect of drawing those objects on the active graphics device.
}
\description{
Function to generate heatmap of gene expression values
}
\details{
The actual heatmap is produced as a side effect by printing the individual plot components.

This is the convenience entry point used by \code{diffExpr()} to build a contrast's
  heatmaps; it is exported so the same heatmaps can be regenerated from a stored result table
  (e.g. \code{res$contrasts[[<contrast>]]}) with different thresholds or colours, without re-running
  the pipeline. The lower-level work horse it calls is \code{\link{diffr_pheatmap}}.
}
\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)
contr  <- diff_expr_make_contrasts(design, groups)
fit    <- diff_expr_fit(counts, d, design, do.voom = FALSE, quasi.likelihood = TRUE)
## a per-contrast table like the ones diffExpr() stores in res$contrasts
de <- edgeR::glmQLFTest(fit$fit, contrast = contr[, 1])
d3 <- merge(edgeR::cpm(fit$d2, log = TRUE),
            as.data.frame(edgeR::topTags(de, n = Inf)), by = "row.names")
names(d3)[1] <- "ID"; d3$gene_symbol <- d3$ID
## regenerate the heatmap at a stricter cut-off and a different palette, no refit
hm <- pheatmap_plots(d3, id = "ID", samp.info = si, samples = "SampleNames",
                     groups = groups, fdr.thr = 0.01, topn = 30, color.blind.pal = "RdBu")
}
}
