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: `DBA_ID` `DBA_TISSUE` `DBA_FACTOR` `DBA_CONDITION` `DBA_TREATMENT` `DBA_REPLICATE` `DBA_CONSENSUS` `DBA_CALLER`

`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

- `profileplyr::profileplyr-class`

- `profileplyr::BamBigwig_to_chipProfile`

- `profileplyr::generateEnrichedHeatmap`

- `profileplyr::profileplyr` (Vignette)

- `DBA.config`

### 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.2.7 Index]