dba.plotProfile {DiffBind}R Documentation

Generate profiles and make profile heatmaps

Description

Generates profiles and makes heatmap plots.

Usage

dba.plotProfile(Object, samples, sites, scores, labels, 
                normalize=TRUE, merge=DBA_REPLICATE,
                maxSites=1000, absScores=TRUE,
                doPlot=is(Object,"profileplyr"), 
                ...)

Arguments

Object

Either a DBA object, or a profileplyr-class object.

samples

Sample mask.

A vector of logical or numeric values indicating which samples to be included in the plot. Alternatively, samples can be specified as a list of sample masks to specify sample groups (using list element names if present).

If absent, all samples will be included; if sites indicates that the results of an analysis should be used, the samples involved in the specified contrast will be included (if it is a two-way contrast); these samples will be merged into two sample groups representing the two sides of the contrast.

Some groups of samples may be merged as indicated in the merge parameter.

sites

sites is used to specify which sites are to be used in the heatmaps. It can be specified in a number of ways:

  • GRanges object containing a set of genomic intervals (eg. as returned by dba.report)

  • logical or numeric vector of length > 1 indicating which sites to include in the heatmaps. If logical, vector should be same length as number of consensus sites binding matrix.

  • GRangesList containing a list of GRanges, each containing a set of genomic intervals. Each element of the list will be plotted in a separate heatmap as a group of sites. If the constituent GRanges elements are named, the names will be used as labels for the site groups.

  • A numeric value indicating a contrast on which an analysis has been run. In this case, all of the differentially-bound sites will be included, divided into two groups: a group of Gain sites (Fold > 0) and a group of Loss sites (Fold < 0).

  • A report-based DBA object, as generated by dba.report. Each set of peaks in the object will be included as a separate group of sites.

If sites is absent, and an analysis has been completed, the first contrast will be used (sites=1); otherwise, all sites (subject to the maxSites limit) will be included.

scores

character string corresponding to the name of a metadata column containing numerical scores used to sort the sites (within each group).

These can be any of the mcols name values when passing in sites as a GRanges or GRangesList object, or the metadata fields in a report-based DBA object. If the Object is of type profileplyr-class, it can be any of its mcols names for columns corresponding to numeric values.

If scores=NULL, the sites will be sorted by their mean counts across all the samples.

labels

Either a vector of sample label names (one for each sample in the plot), or a set of attributes to include (positive values) or exclude (negative values). Attributes include:

normalize

logical indicating if the window counts should be normalized using the normalization established by dba.normalize.

Can also be a vector of normalization factors, once for each sample. All counts for a sample will be divided by the normalization factor for that sample.

merge

Set of attributes to be used to determine which samples should be merged. All samples that share the same values for all other attributes except those specified will be merged by taking their mean count score (after normalizing, if specified), and included as a single sample column.

Can also be specified as a list of vectors of sample numbers (relative to their order in mask). The samples corresponding to the values in each vector will be merged into a single sample.

maxSites

Maximum number of sites to include in a heatmap group. The top-scoring sites will be retained.

absScores

If TRUE, the absolute values for the score values (specified by the scores parameter) will be used for sorting sites. Useful for fold changes. If score values are greater than zero, this has no effect.

doPlot

logical indicating if the heatmap should be plotted. If FALSE, the profiles are generated and returned but not plotted.

...

additional parameters passed on to profileplyr::generateEnrichedHeatmap.

Details

This function enables the computation of peakset profiles and the plotting of complex heatmaps. It serves as a front-end to enable experiments analyzed using DiffBind to more easily use the profiling and plotting functionality provided by the profileplyr package written by Tom Carroll and Doug Barrows.

Processing proceeds in two phases.

In the first phase, specific peaksets are extracted from a DiffBind DBA object, and profiles are calculated for these peaks for set of samples in the DiffBind experiment. Profiles are calculated by counting the number of overlapping reads in a series of bins upstream and downstream of each peak center.

In the second phase, the derived profiles are plotted in a series of complex heatmaps showing the relative intensity of overlapping peaks in each bin for each peak in each sample, along with summary plots showing the average profile across the sites for each sample.

Due to the computational cost of this function, it is advised that the calculation of profiles and the plotting of heatmaps be separated into two calls, so that the profiles do not need to be re-generated if something goes wrong in the plotting. By default, when a DBA object is passed in to generate profiles, plotting is turned off and a profileplyr object is returned. When dba.plotProfile is called with a profileplyr object, a plot is generated by default.

More detailed documentation is included in a markdown demonstration script included with the DiffBind package. This can be located as follows:

system.file('extra/plotProfileDemo.Rmd',package='DiffBind')

An HTML version of the demonstration notebook can be accessed online at https://content.cruk.cam.ac.uk/bioinformatics/software/DiffBind/plotProfileDemo.html

Value

silently returns a profileplyr-class object.

Author(s)

Rory Stark

References

Carroll T, Barrows D (2020). profileplyr: Visualization and annotation of read signal over genomic ranges with profileplyr. DOI: 10.18129/B9.bioc.profileplyr

See Also

Examples


# See plotProfileDemo notebook:
# system.file('extra/plotProfileDemo.Rmd',package='DiffBind')

data(tamoxifen_analysis)

# default Profile plot
## Not run: dba.plotProfile(tamoxifen)


[Package DiffBind version 3.4.5 Index]