plotEpistack: plotEpistack()

In GenEpi-GenPhySE/epistack: Heatmaps of Stack Profiles from Epigenetic Signals

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(
  rse,
  assays = NULL,
  tints = "gray",
  titles = NULL,
  legends = "",
  main = NULL,
  x_labels = c("Before", "Anchor", "After"),
  zlim = c(0, 1),
  ylim = NULL,
  metric_col = "exp",
  metric_title = "Metric",
  metric_label = "metric",
  metric_ylab = NULL,
  metric_transfunc = function(x) x,
  bin_palette = colorRampPalette(c("#DF536B", "black", "#61D04F")),
  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("ci95", "sd", "sem"),
  reversed_z_order = FALSE,
  rel_widths = c(score = 0.35, bin = 0.08, assays = 0.35),
  rel_heights = c(1, 0.14, 0.3),
  patterns = NULL,
  ...
)

Arguments

rse	a RangedSummarizedExperiment input. Aletrnatively: can be a GRanges object (for backward compatibility, patterns will be required).
assays	specify the name(s) and order of assay(s) to plot. A vector of names that should match assayNames(rse).
tints	a vector of colors to tint the heatmaps. Can alos be a function returning n colors, or a list of such palette functions.
titles	titles of each heatmap. Defaults to assays.
legends	legend names for the epistacks.
main	Main title for the figure.
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). zlim can also be specified of as a list of pairs of limits, on for each assay.
ylim	limits of the y axis for bottom plots. ylim can also be specified of as a list of pairs of limits, on for each assay. 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_ylab	y axis label of the top left plot.
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 vector of colors, or a function that returns a palette of 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,	error_type, can be either "sd" (standard deviation), "sem" (standard error of the mean), or "ci95" (95% confidence interval). Default: "ci95".
reversed_z_order	For the bottom panels: should the z-order of the curves be reversed (i.e. first or last bin on top)?
rel_widths	A named vector of three elements of relative panel widths: score is the left-most panel, bin is the optionnal binning panels, and assays are the panels of the stacked-matrices. Default to c(score = .35, bin = .08, assays = .35)
rel_heights	A vector of three elements of relative panel heights. Default to c(1, .14, .3)
patterns	only if rse is of class GRanges. A character vector of column prefixes (can be regular expressions) that should match columns of rse.
...	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 RangedSummarizedExperiment object with expected rowData 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 a rowData in the input RangedSummarizedExperiment object (hereafter rse).

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

rse's rowData 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 assay(s) in rse. Such matrix can be obtained using EnrichedHeatmap::normalizeToMatrix() for example. The assay names are then specified through assays.

If an optionnal bin column is present in rse's rowData, 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.

The input can also be a GRanges object for backward compatibility. See GRanges2RSE. patterns would then be required.

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))

GenEpi-GenPhySE/epistack documentation built on July 27, 2023, 1:09 a.m.