plotMeanVarCurve {MAnorm2}

Plot a Mean-Variance Curve

Description

Given a list of bioCond objects associated with a common mean-variance curve, plotMeanVarCurve draws a scatter plot of observed (mean, log10(variance)) pairs from the genomic intervals contained in them. It also adds the mean-variance curve to the plot.

Usage

plotMeanVarCurve(
  conds,
  subset = c("all", "occupied", "non-occupied"),
  col = alpha("blue", 0.02),
  pch = 20,
  xlab = "Mean",
  ylab = "log10(Var)",
  args.legend = list(x = "bottomleft"),
  args.lines = list(col = "red", lwd = 2),
  only.add.line = FALSE,
  ...
)

Arguments

conds

A list of bioCond objects with which a mean-variance curve has been associated.

subset

A character string indicating the subset of genomic intervals used for the scatter plot (see "Details"). Must be one of "all" (default), "occupied", or "non-occupied". Can be abbreviated.

col, pch

Optional vectors specifying the color and point character for genomic intervals in each bioCond. Elements are recycled if necessary.

xlab, ylab

Labels for the X and Y axes.

args.legend

Further arguments to be passed to legend.

args.lines

Further arguments to be passed to lines.

only.add.line

A logical value. If set to TRUE, only the mean-variance curve is added to the current plot.

...

Further arguments to be passed to plot.

Details

All bioCond objects supplied in conds should be associated with the same mean-variance curve. Thus, they must have the same "mvcID" (see fitMeanVarCurve for the data structure stored in a bioCond object describing its fit of mean-variance trend). Typically, conds is a returned value from fitMeanVarCurve, setMeanVarCurve or extendMeanVarCurve.

Notably, to make the observed variance of each genomic interval in each bioCond object comparable to the mean-variance curve, all variance values used for the scatter plot have been adjusted for the variance ratio factor specific to each bioCond. See fitMeanVarCurve and estimatePriorDf for a description of variance ratio factor. Note also that there is a function named plotMVC that is specifically designed for plotting a mean-variance curve on a single bioCond. This function scales mean-variance curve by the associated variance ratio factor and leaves observed variances unadjusted.

By default, each genomic interval in each bioCond object that contains replicate samples provides one point for the scatter plot. Setting subset to "occupied" ("non-occupied") makes the function use only those intervals occupied (not occupied) by their bioConds to draw the plot (see normalize and bioCond for more information about occupancy states of genomic intervals).

Value

The function returns NULL.

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 given a list of bioCond objects; extendMeanVarCurve for extending the application scope of a fitted mean-variance curve to additional bioCond objects; varRatio for a formal description of variance ratio factor; plotMVC for plotting a mean-variance curve on a single bioCond object; normalize for using occupancy states of genomic intervals to normalize ChIP-seq samples; alpha for adjusting color transparency.

Examples

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

## Fit and plot a mean-variance curve for GM12891 and GM12892 cell lines.

# Perform the MA normalization and construct bioConds to represent
# individuals.
norm <- normalize(H3K27Ac, 5:6, 10:11)
norm <- normalize(norm, 7:8, 12:13)
conds <- list(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)

# Fit mean-variance trend based on the presumed parametric form.
conds <- fitMeanVarCurve(conds, method = "parametric", occupy.only = TRUE)
summary(conds[[1]])

# Plot the fitted mean-variance curve.
plotMeanVarCurve(conds, subset = "occupied")

# Use different colors for the two bioConds, to see if the mean-variance
# points from the two cell lines mix uniformly with each other.
plotMeanVarCurve(conds, subset = "occupied",
                 col = scales::alpha(c("blue", "green3"), 0.02))