% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/computeDeviationsFromKNN.R
\name{computeDeviationsFromKNN}
\alias{computeDeviationsFromKNN}
\title{computeDeviationsFromKNNbg}
\usage{
computeDeviationsFromKNN(
  object,
  cBg,
  annotations,
  l = 1,
  chunkSize = 1000,
  verbose = TRUE
)
}
\arguments{
\item{object}{A SummarizedExperiment or sparse matrix of counts.}

\item{cBg}{The peak-by-peak sparse kNN matrix, as produced by
\code{\link{getBackgroundKNN}}.}

\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{l}{Lambda parameter determining the weight by which background peaks
containing the foreground motif are scaled in relative importance. Set to
1 to treat them normally (default), to 0 to exclude them entirely
(potentially unstable, a small value such as \code{0.1} is instead recommended).}

\item{chunkSize}{Number of cells to process simultaneously. Increasing this
will increase speed, but also memory consumption.}

\item{verbose}{Logical; whether to print progress messages.}
}
\value{
A SummarizedExperiment with 'deviations' and 'z' assays. If overall
motif variability and their significance are additionally needed, see
\code{\link{computeMotifVariability}}.
}
\description{
Computes analytical deviations using a nearest-neighbor background matrix
while optionally excluding peaks containing the target motif from its own
background pool.
}
\details{
This method combines the analytic strategy used by \code{betterChromVAR} with
Ruochi Zhang's approach to use a continuous, multidimensional background
space instead of background bins. If \code{l<1} it downweighs (multiplying them
by \code{l}) peaks harboring the tested motif from the corresponding motif's
background.
}
\examples{
attach(getDummyData())
bg <- getBackgroundKNN(counts)
dev <- computeDeviationsFromKNN(object=counts, cBg=bg,
                                annotations=motifMatches)
dev
}
