estimateVarRatio {MAnorm2}

Estimate Relative Variance Ratio Factors of bioCond Objects

Description

Given a set of bioCond objects assumed to be associated with the same mean-variance curve, estimateVarRatio robustly estimates their relative variance ratio factors, by selecting one of the bioConds as the base condition and comparing the others to it.

Usage

estimateVarRatio(
  conds,
  base.cond = NULL,
  subset = NULL,
  invariant = NULL,
  no.rep.rv = NULL
)

Arguments

conds

A list of bioCond objects.

base.cond

An optional positive integer or character name indexing the base bioCond in conds. Note that the base condition must contain replicate samples. By default, the base bioCond is automatically selected by measuring the variation levels of the bioConds (see "Details").

subset

An optional vector specifying the subset of intervals to be used for measuring the variation levels. Defaults to the intervals occupied by all the bioConds. Ignored if base.cond is specified.

invariant

An optional non-negative real specifying the upper bound of difference in mean signal intensity for a genomic interval to be treated as invariant between two bioCond objects. By default, intervals occupied by both bioConds are treated as invariant between them. Note that estimateVarRatio uses exactly the invariant intervals to compare the variance ratio factors of two bioConds.

no.rep.rv

A positive real specifying the (relative) variance ratio factor of those bioConds without replicate samples, if any. By default, it's set to be the geometric mean of variance ratio factors of the other bioConds.

Details

Technically, estimateVarRatio uses 1 as the (relative) variance ratio factor of the base bioCond, and estimates the variance ratio factors of the other bioConds by separately comparing each of them to the base. Refer to varRatio for details about comparing the variance ratio factors of two bioConds by using their invariant genomic intervals.

If the base bioCond is not explicitly specified by users, estimateVarRatio will measure the variation level of each bioCond containing replicate samples. Technically, the variation levels are calculated by applying the median ratio strategy to the observed variances of the bioConds. This process is rather similar to the one for estimating size factors of ChIP-seq samples (see also estimateSizeFactors). After that, the bioCond whose variation level is closest to 1 is selected as the base (with the exception that, if there are only two bioConds that contain replicate samples, the function will always use the bioCond with the lower variation level as the base, for avoiding potential uncertainty in selection results due to limited numerical precision).

Value

A named vector of the estimated relative variance ratio factors, with the names being those of the corresponding bioCond objects. Besides, the following attributes are associated with the vector:

var.level

Variation levels of the bioCond objects. Present only when the base bioCond is automatically selected by the function.

base.cond

Name of the base bioCond.

no.rep.rv

Variance ratio factor of the bioConds with no replicate samples. Present only when it's ever been used.

References

Tu, S., et al., MAnorm2 for quantitatively comparing groups of ChIP-seq samples. Genome Res, 2021. 31(1): p. 131-145.

See Also

bioCond for creating a bioCond object; fitMeanVarCurve for fitting a mean-variance curve for a set of bioCond objects; varRatio for a formal description of variance ratio factor.

Examples

data(H3K27Ac, package = "MAnorm2")
attr(H3K27Ac, "metaInfo")

## Estimate the relative variance ratio factors of cell lines.

# Perform the MA normalization and construct bioConds to represent cell
# lines.
norm <- normalize(H3K27Ac, 4, 9)
norm <- normalize(norm, 5:6, 10:11)
norm <- normalize(norm, 7:8, 12:13)
conds <- list(GM12890 = bioCond(norm[4], norm[9], name = "GM12890"),
              GM12891 = bioCond(norm[5:6], norm[10:11], name = "GM12891"),
              GM12892 = bioCond(norm[7:8], norm[12:13], name = "GM12892"))
autosome <- !(H3K27Ac$chrom %in% c("chrX", "chrY"))
conds <- normBioCond(conds, common.peak.regions = autosome)

# Automatically select the base bioCond.
estimateVarRatio(conds)

# Explicitly specify the base bioCond.
estimateVarRatio(conds, base.cond = "GM12891")