plotEpistack {epistack}R Documentation

plotEpistack()

Description

Given a list of genomic regions, epigenetic signals surrounding these regions, and a score for each regions, plot epigenetic stacks depending on the score. An optional bin column allow the grouping of several genomic regions to produce average profiles per bins.

Usage

plotEpistack(
  gr,
  patterns = "^window_",
  tints = "gray",
  titles = "",
  legends = "",
  x_labels = c("Before", "Anchor", "After"),
  zlim = c(0, 1),
  ylim = NULL,
  metric_col = "expr",
  metric_title = "Metric",
  metric_label = "metric",
  metric_transfunc = function(x) x,
  bin_palette = colorRampPalette(c("magenta", "black", "green")),
  npix_height = 650,
  n_core = 1,
  high_mar = c(2.5, 0.6, 4, 0.6),
  low_mar = c(2.5, 0.6, 0.3, 0.6),
  error_type = c("sd", "sem"),
  ...
)

Arguments

gr

a GRanges input.

patterns

a character vector of column prefixes (can be regular expressions) that should match columns of gr.

tints

a vector of colors to tint the heatmaps.

titles

titles of each heatmap.

legends

legend names for the epistacks.

x_labels

a character vector of length 3 used as x-axis labels.

zlim

the minimum and maximum z values the heatmap. Format: zlim = c (min, max)

ylim

limits of the y axis for bottom plots. Format: ylim = c (min, max)

metric_col

a character, name of a column in gr such as expression value, peak height, pvalue, fold change, etc.

metric_title

title to be display on the leftmost plots.

metric_label

label of the leftmost plots.

metric_transfunc

a function to transform value of metric_col before plotting. Useful to apply log10 transformation (i.e. with trans_func = function(x) log10(x+1)).

bin_palette

a palette of color, (i.e. a function of parameter n that should retrun n colors), used to color average profiles per bin in the bottom plots.

npix_height

The matrix height is reduced to this number of rows before plotting. Useful to limit overplotting artefacts. It should roughtly be set to the pixel height in the final heatmaps

n_core

number of core used to speedup the martrix resizing.

high_mar

a vector of numerical values corresponding to the margins of the top figures. c(bottom, left, top, right)

low_mar

a vector of numerical values corresponding to the margins of the bottom figures. c(bottom, left, top, right)

error_type,

can be either sd (standard deviation) or sem (standard error of the mean). Default: sem.

...

Arguments to be passed to par such as cex

Details

This function produce a comprehensive figure including epigenetic heatmaps and average epigenetic profiles from a well formated GRanges object with expected metadata columns. It scales resonably well up to hundreds of thousands of genomic regions.

The visualisation is centered on an anchor, a set of genomic coordinated that can be transcription start sites or peak center for example. Anchor coordinates are those of the GRanges used as an input (hereafter gr).

Anchors are plotted from top to bottom in the same order as in gr. One should sort gr before plotting if needed.

gr should have a metric column that is used in the leftmost plots. The name of the metric column must be specified to metric_col. The metric can be transformed before plotting if needed using the metric_transfunc parameter.

The matrix or matrices used to display the heatmap(s) should be passed as additional metadata columns of gr. Such matrix can be obtained using EnrichedHeatmap::normalizeToMatrix() for example. The matrix columns names are then specified through patterns using prefixes, suffixes or regular expressions.

If an optionnal bin column is present in gr, it will be used to group genomic regions to performed average profile per bins in the bottom plots.

Epistack are multipanel plots build using layout(). Margins for the panels can be specified using high_mar and low_mar parameters if needed, especially to avoid text overlaps. The default value should be appropriate in most situations. Individual component can be plotted using severa epistack functions such has plotStackProfile() or plotAverageProfile().

Plotting more than > 1000 regions can lead to overplotting issued as well as some plotting artefacts (such as horizontal white strips). Both issues can be resolved with fidling with the npix_height parameter. npix_height should be smaller than the number of regions, and in the same order of magnitude of the final heatmap height in pixels. Last minutes call to the redimMatrix() function will hapen before plotting using npix_height as target height. Parameter n_core is passed to redimMatrix() to speed up the down-scaling.

Value

Display a plot.

See Also

plotStackProfile, plotAverageProfile, redimMatrix, normalizeToMatrix, addMetricAndArrangeGRanges, addBins

Examples

data("stackepi")
plotEpistack(stackepi,
    metric_col = "exp",
    ylim = c(0, 1),
    metric_transfunc = function(x) log10(x+1))


[Package epistack version 1.0.0 Index]