% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/betterChromVAR.R
\name{betterChromVAR}
\alias{betterChromVAR}
\title{betterChromVAR}
\usage{
betterChromVAR(
  object,
  annotations,
  grouping = NULL,
  nthreads = NULL,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{object}{A SummarizedExperiment (or SingleCellExperiment) with an assay
'counts', and with a 'bias' column in \code{rowData(object)}. Note that the
regions should have similar widths.}

\item{annotations}{Peak annotation (sparse) matrix, with motifs as columns,
or a SummarizedExperiment containing this in the first assay. Values
should be either logical or between 0 and 1.}

\item{grouping}{An optional factor or vector coercible to a factor indicating
the groupings of the columns of \code{object}. This is optionally used to
compute the base expectation such that rare cell types are given as much
weight as abundant ones. In single-cell data, the grouping can for
instance be the interaction of samples and cell types. This should either
be a vector coercible to factor of length equal to \code{ncol(object)}, or a
character of length 1 specifying a column of \code{colData(object)}.}

\item{nthreads}{Either an integer scalar indicating the number of threads to
use, or a \code{BiocParallelParam} object.}

\item{verbose}{Logical; whether to output progress messages (default FALSE).}

\item{...}{Passed to \code{\link{getBackgroundBins}}.}
}
\value{
A SummarizedExperiment containing the adjusted deviations and
z-scores for each motif/sample. The rowData additionally contains the
number of motif matches and their variability.
}
\description{
A fast, analytic implementation of \code{chromVAR}.
This is a wrapper around the \code{\link{getBackgroundBins}},
\code{\link{computeBackgrounds}}, and \code{\link{computeDeviationsAnalytic}}
steps. It additionally allows for multithreading. For more control or
optimization, see the individual steps.
}
\details{
Contrarily to the original chromVAR, this function is entirely deterministic,
and achieves higher precision and much higher efficiency through two changes:
\enumerate{
\item working with expected background sampling mean and variances, rather than
actual permutations, and 2) computing expectations and variance at the level
of bias bins, instead of in the peak-space. The function additionally
includes experimental bias shrinkage options, the possibility to handle
annotations that are not binary (e.g. probability scores) and a third
bias dimension (fragment length bias, which should be stored in
\code{rowData(object)$flbias} see \code{\link{getBackgroundBins}} for details).
}
}
\examples{
attach(getDummyData())
# if GC content not already in the object, use:
# counts <- addGCBias(counts, genome=YOUR_GENOME)
dev <- betterChromVAR(counts, motifMatches)
dev
# note that this is the exact equivalent of doing:
# bg <- getBackgroundBins(counts)
# bg <- computeBackgrounds(counts, bg)
# dev <- computeDeviationsAnalytic(counts, bg, motifMatches)
}
\references{
Schep A.N., Wu B., Buenrostro J.D., Greenleaf W.J. (2017) chromVAR:
inferring transcription-factor-associated accessibility from
single-cell epigenomic data, Nature Methods, doi: 10.1038/nmeth.4401
}
\author{
Pierre-Luc Germain
}
