% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CVnorm.R
\name{CVnorm}
\alias{CVnorm}
\title{CVnorm: chromVAR-inspired ATAC-seq normalization}
\usage{
CVnorm(
  object,
  bias = NULL,
  grouping = NULL,
  smoothGrouping = grouping,
  shrinkMode = c("dampen", "qsmooth"),
  toAssay = "corrected",
  bs = NULL,
  w = 0.1,
  Z = FALSE,
  useWidthAdj = NULL,
  enforceZeros = TRUE
)
}
\arguments{
\item{object}{A matrix of counts, or a SummarizedExperiment-like object with
an assay named 'counts'.}

\item{bias}{A vector of length equal to \code{ncol(object)} specifying the
per-peak bias (i.e. GC content). If omitted, will try to get it
from \code{rowData(object)$bias}.}

\item{grouping}{Optional grouping for the baseline expectation (prevents
bias toward more abundant groups). This should either be a vector coercible
to factor of length equal to \code{ncol(object)}, of a character of length 1
specifying a column of \code{colData(object)} (if \code{object} is a
\code{SummarizedExperiment}).}

\item{smoothGrouping}{Optional grouping to determine correction strength.
If bias is consistent within these groups, correction is reduced. Accepts
the same type of inputs as \code{grouping}, and by default takes the same
values.}

\item{shrinkMode}{The way to perform the group-based shrinkage. With
\code{shrinkMode="dampen"} (default), no corrected is applied in bins when the
bias is entirely explained by groups. \code{shrinkMode="qsmooth"} instead
reproduces the logic of the \code{qsmooth} package: if variance in bias is
chiefly explained by groups, between group bias will not be corrected, but
within-group differences will be. Using this prior to differential analysis
however leads to increase Type I error rate, and it should therefore not be
used for downstream application.}

\item{toAssay}{The name of the assay in which to store the corrected data
(default 'corrected'). Ignored unless \code{object} is a
SummarizedExperiment-like object.}

\item{bs}{Number of bins per dimension (see \code{\link{getBackgroundBins}}).}

\item{w}{Standard deviation of the Gaussian kernel for bin smoothing.}

\item{Z}{Logical; whether to return standardized residuals (Z-scores)
instead of the (default) corrected counts.}

\item{useWidthAdj}{Whether to adjust for the different width of the regions.
If omitted, will be TRUE if the average absolute difference to the median
width is greater than 10\% of the median width. If TRUE, will adjust for
\code{pmax(200L,width)}. If an integer scalar, will adjust for
\code{pmax(useWidthAdj,width)}.}

\item{enforceZeros}{Logical; whether to enforce that zero counts should
remain zeroes after correction (ignored if \code{Z=TRUE}).}
}
\value{
If \code{object} is a matrix, then a matrix of corrected counts of the
same dimensions. If \code{object} is a SummarizedExperiment-like object, then
the object is returned with an extra assay named based on \code{toAssay}.
}
\description{
Corrects ATAC peak counts by removing the effects of technical biases
(GC/accessibility) using the chromVAR background binning approach and an
optional variance-based bias shrinkage (inspired from the qsmooth package)
to preserve group biological signal.
}
\examples{
counts_se <- getDummyData()$counts
# if GC content not already in the object, use:
# counts_se <- addGCBias(counts_se, genome=YOUR_GENOME)
counts_se <- CVnorm(counts_se)
}
\references{
\itemize{
\item 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
\item Hicks SC, Okrah K, Paulson JN, Quackenbush J, Irizarry RA, Corrado
Bravo H (2018). “Smooth quantile normalization.” Biostatistics 19 (2),
doi: 10.1093/biostatistics/kxx028
}
}
\author{
Pierre-Luc Germain
}
