plotDMRs {dmrseq} | R Documentation

## Plot Differentially Methylated Regions

### Description

Generates trace plots of methylation proportions by genomic position.

### Usage

    plotDMRs(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 = .alpha("#C77CFF", 0.2), 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.
`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 GRangesList object that contains up to four custom tracks (GRanges 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 GRanges 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.

### 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. 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.

### Value

None (generates a plot)

### Examples

    # load the example data
    data(BS.chr21)

    # load example results (computed with dmrseq function)
    data(dmrs.ex)

    # get annotation information (using getAnnot function)
    # here we'll load the example annotation from chr21
    data(annot.chr21)

    # plot the 1st DMR
    plotDMRs(BS.chr21, regions=dmrs.ex[1,], testCovariate=1,
       annoTrack=annot.chr21)

[Package dmrseq version 1.12.0 Index]