Skip to contents

Plot Differentially Methylated Regions

Source: R/plotDMRs2.R
plotDMRs2.Rd

Generates trace plots of methylation proportions by genomic position. Modified from the plotDMRs function in the dmrseq R package (plotDMRs).

Usage

plotDMRs2(
  BSseq,
  regions = NULL,
  testCovariate = NULL,
  extend = (end(regions) - start(regions) + 1)/2,
  main = "",
  addRegions = regions,
  annoTrack = NULL,
  col = NULL,
  lty = NULL,
  lwd = NULL,
  label = NULL,
  mainWithWidth = TRUE,
  regionCol = "#FF00001A",
  addTicks = TRUE,
  addPoints = TRUE,
  pointsMinCov = 1,
  highlightMain = FALSE,
  qval = TRUE,
  stat = TRUE,
  verbose = TRUE,
  includeYlab = TRUE,
  compareTrack = NULL,
  labelCols = NULL,
  horizLegend = FALSE,
  addLines = TRUE
)

Arguments

BSseq

An object of class BSseq. Can be smoothed or not smoothed.

regions

A data.frame containing the DMRs (output from the main dmrseq function).

testCovariate

integer value or vector indicating which of columns of pData(bs) contains the covariate of interest. This is used to construct the sample labels and colors (unless this is over-ridden by specifying label).

extend

Describes how much the plotting region should be extended in either direction. The total width of the plot is equal to the width of the region plus twice extend.

main

The plot title. The default is to construct a title with information about which genomic region is being plotted.

addRegions

A set of additional regions to be highlighted on the plots. Same format as the regions argument.

annoTrack

a GRangesList object with two elements returned by getAnnot. The first contains CpG category information in the first element (optional) coding gene sequence information in the second element (optional). At least one of these elements needs to be non-null in order for any annotation to be plotted, but it is not necessary to contain both.

col

The color of the methylation estimates. It is recommended to leave this value as default (NULL), and specify a value of testCovariate to indicate which column of pData(bs) to use as a factor for coloring the points and lines of the plot. Alternatively, you can specify particular colors by passing this information through the pData slot of the object BSseq (a data.frame that houses metadata). To do so, place the color value for each sample in a column titled col, and leave this argument as its default value of NULL. Alternatively, you may specify a vector of color values (one for each sample), but you *must* make sure that this vector is in the same order as the samples are in the BSseq object. If NULL and no col column is found in pData, then estimates are plotted in black for all samples.

lty

The line type of the methylation estimates. It is recommended to pass this information through the pData slot of the object BSseq (a data.frame that houses metadata). To do so, place the line type value for each sample in a column titled lty, and leave this argument as its default value of NULL. Alternatively, you may specify a vector of line type values (one for each sample), but you *must* make sure that this vector is in the same order as the samples are in the BSseq object. If NULL and no lty column is found in pData, then estimates are plotted with lty=1 for all samples.

lwd

The line width of the methylation estimates. It is recommended to pass this information through the pData slot of the object BSseq (a data.frame that houses metadata). To do so, place the line width value for each sample in a column titled lwd, and leave this argument as its default value of NULL. Alternatively, you may specify a vector of line width values (one for each sample), but you *must* make sure that this vector is in the same order as the samples are in the BSseq object. If NULL and no lwd column is found in pData, then estimates are plotted with lwd=1 for all samples.

label

The condition/population labels for the plot legend. If NULL (default) this is taken from the testCovariate column of pData. Alternatively, you can pass in labels by adding this information through the pData slot of the object BSseq (a data.frame that houses metadata). To do so, place the labels for each sample in a column titled label, and leave this argument as its default value of NULL. You may instead specify an arbitrary vector of labels (one for each sample), but be aware that you *must* make sure that this vector is in the same order as the samples are in the BSseq object. If NULL, and testCovariate is also NULL and no label column is found in pData, then no legend is created.

mainWithWidth

logical value indicating whether the default title should include information about width of the plot region.

regionCol

The color used for highlighting the region.

addTicks

logical value indicating whether tick marks showing the location of methylation loci should be added. Default is TRUE.

addPoints

logical value indicating whether the individual methylation estimates be plotted as points.

pointsMinCov

The minimum coverage a methylation loci need in order for the raw methylation estimates to be plotted. Useful for filtering out low coverage loci. Only used if addPoints = TRUE. Default value is 1 (no filtering).

highlightMain

logical value indicating whether the plot region should be highlighted.

qval

logical value indicating whether the region FDR estimate (q-value) should be displayed in the plot title. The value is extracted from the regions argument.

stat

logical value indicating whether the region statistic should be displayed in the plot title. The value is extracted from the regions argument.

verbose

logical value indicating whether progress messages should be printed to the screen.

includeYlab

a logical indicating whether to include the Y axis label 'Methylation' (useful to turn off if combining multiple region figures and you do not want to include redundant y axis label information)

compareTrack

a named GenomicRangesList item that contains up to four custom tracks (GenomicRanges objects) which will be plotted below the region. Only one of `compareTrack` or `annoTrack` can be specified since there is only for plotting either the built in GpG category and exon tracks, *or* a custom set of tracks.

labelCols

a character vector with names of the mcols slot of the GenomicRanges items in `compareTrack'. Only used if plotting custom tracks using the `compareTrack' argument. If specified, the (first) value in that column is printed along with a label that includes the name of the list item. If NULL (default), just the name of the track is printed.

horizLegend

logical indicating whether the legend should be horizontal instead of vertical (default FALSE). This is useful if you need to plot many labels and want to preserve whitespace.

addLines

logical indicating whether to plot smooth lines between points. Default is true. Can be useful to turn this off for very small regions.

Value

None (generates a plot)

Details

Creates aesthetially pleasing DMR plots. By default will plot individual points with size proportional to coverage, along with a smoothed line for each sample. If BSseq object is smoothed, it will use these values. Otherwise, raw methylation values will be smoothed with loess. Elements will be colored by biological condition (label). Also has functionality to add annotations below the main plot (CpG category, genes) if annoTrack is specified.

References

plotDMRs