dba.plotHeatmap {DiffBind} | R Documentation

## Draw a binding site heatmap

### Description

Draws a binding site heatmap

### Usage

    dba.plotHeatmap(DBA, attributes=DBA$attributes, maxSites=1000, minval, maxval,
                    contrast, method=DBA$config$AnalysisMethod,
                    th=DBA$config$th, bUsePval=DBA$config$bUsePval,
                    report, score, bLog=TRUE, mask, sites, sortFun=sd,
                    correlations=TRUE, olPlot=DBA_COR,
                    ColAttributes,RowAttributes, colSideCols, rowSideCols=colSideCols,
                    margin=10, colScheme="Greens", distMethod="pearson",
                    ...)

### Arguments

`DBA` | DBA object.

`attributes` | attribute or vector of attributes to use for column labels: `DBA_ID` `DBA_TISSUE` `DBA_FACTOR` `DBA_CONDITION` `DBA_TREATMENT` `DBA_REPLICATE` `DBA_CONSENSUS` `DBA_CALLER`
`maxSites` | maximum number of binding sites to use in heatmap. Only used when not drawing a correlation heatmap (`correlations=FALSE`)
`minval` | Set all scores less than this to minval
`maxval` | Set all scores greater than this to maxval
`contrast` | number of contrast to report on; if present, draws a heatmap based on a differential binding affinity analysis (see `dba.analyze`). Only significantly differentially bound sites will be used (subject to the `th` and `bUsePval` parameters). If mask is unspecified, only the samples in the contrast will be included. See `dba.show(DBA, bContrast=TRUE)` to get contrast numbers. If missing, uses scores in the main binding matrix.
`method` | analysis method (used in conjunction with contrast): `DBA_DESEQ2` `DBA_DESEQ2_BLOCK` `DBA_EDGER` `DBA_EDGER_BLOCK`
`th` | significance threshold; all sites with FDR (or p-values, see b`UsePval`) less than or equal to this value will be included in the report (subject to `maxSites`). Used in conjunction with `contrast`.
`bUsePval` | logical indicating whether to use FDR (`FALSE`) or p-value (`TRUE`) for thresholding. Used in conjunction with `contrast`.
`report` | report (obtained from `dba.report` specifying the data to be used. If this is present, the `method`, `th`, and `bUsePval` parameters are ignored. Used in conjunction with `contrast`.
`score` | Score to use for count data. Only used when plotting the global binding matrix (no contrast specified). One of: `DBA_SCORE_NORMALIZED` `DBA_SCORE_READS` `DBA_SCORE_CONTROL_READS` `DBA_SCORE_READS_MINUS` `DBA_SCORE_READS_FOLD` `DBA_SCORE_RPKM` `DBA_SCORE_RPKM_FOLD` `DBA_SCORE_RPKM_MINUS`
`bLog` | Logical indicating that log2 values should be used. Only applicable with read count scores (not peak scores).
`mask` | mask indicating a subset of peaksets to use when using global binding matrix scores. If a `contrast` is specified, these peaksets will be included, but only the significantly differentially bound sites (using `th`, `bUsePva`l, and/or `report`) will be included.
`sites` | logical vector indicating which sites to include; first `maxSites` of these. Only relevant when using global binding matrix (`contrast` is missing).
`sortFun` | function taking a vector of scores and returning a single value. Only relevant when using global binding matrix (`contrast` is missing). If not equal to `FALSE`, the global binding matrix will be sorted (descending) on the results, and the first `maxSites` used in the heatmap. Recommended sort function options include `sd`, `mean`, `median`, `min`.
`correlations` | logical indicating that a correlation heatmap should be plotted (`TRUE`). If `FALSE`, a binding heatmap of scores/reads is plotted. This parameter can also be set to a correlation record; see `dba.overlap(mode=DBA_OLAP_ALL)`, in which case a correlation heatmap is plotted based on the specified correlation record, using the statistic specified in `olPlot`.
`olPlot` | if correlations is specified as a dataframe returned by `dba.overlap`, indicates which statistic to plot. One of: `DBA_COR` Correlation `DBA_OLAP` Percentage overlap `DBA_INALL` number of peaks common to both samples
`ColAttributes` | Attribute or vector of attributes to plot for column color bars. If missing, all attributes with two or more unique non-NA values will be plotted. (For correlation heatmaps, `DBA_GROUP` will be plotted in the column color bar by default when a `contrast` is specified). A value of `NULL` indicates that no column color bar should be drawn. Allowable attribute values include: `DBA_GROUP` `DBA_TISSUE` `DBA_FACTOR` `DBA_CONDITION` `DBA_TREATMENT` `DBA_REPLICATE` `DBA_CALLER`
`RowAttributes` | Attribute or vector of attributes for row color bars. Row color bars are only allowed for correlation heatmaps. Same values as for `ColAttributes` parameter. Default is to draw a row color bar only if a `contrast` is specified, in which case the plotted attribute is `DBA_GROUP` (if present).
`rowSideCols` | Vector of colors to use in row color bars. Uses default colors if missing. Can also be a list of color vectors.
`colSideCols` | Vector of colors to use in column color bars. Uses default colors if missing. Can also be a list of color vectors.
`margin` | margin size of plot
`colScheme` | Color scheme; see `colorRampPalette`
`distMethod` | distance method for clustering; see `Dist`
`...` | passed on to `heatmap.2`, e.g. `scale` etc.

### Details

MODE: Correlation Heatmap plot using statistics for global binding matrix:

`dba.plotHeatmap(DBA, attributes=DBA$attributes, minval, maxval, correlations, olPlot, colScheme="Greens", distMethod="pearson", ...)`

MODE: Correlation Heatmap plot using statistics for significantly differentially bound sites:

`dba.plotHeatmap(DBA, attributes=DBA$attributes, minval, maxval, contrast, method=DBA_DESEQ2, th=0.05, bUsePval=F, mask, overlaps, olPlot=DBA_COR, colScheme="Greens", distMethod="pearson", ...)`

MODE: Binding heatmap plot using significantly differentially bound sites:

`dba.plotHeatmap(DBA, attributes, maxSites, minval, maxval, contrast, method, th, bUsePval, correlations=FALSE, colScheme, distMethod, ...)`

MODE: Binding heatmap plot using the global binding matrix:

`dba.plotHeatmap(DBA, attributes, maxSites, minval, maxval, mask, sites, correlations=FALSE, sortFun, colScheme, distMethod, ...)`

### Value

if correlations is not `FALSE`, the overlap/correlation matrix is returned.

if correlations is `FALSE`, the sites used in the heatmap are returned in a `GRanges` object, in the row order they appear (top to bottom). The metadata contains a column for each sample (also in the order they are appear in the clustering plot), with the values being the actual plotted values.

### Author(s)

Rory Stark

### See Also

`dba.overlap`

### Examples

    data(tamoxifen_peaks)
    # peak overlap correlation heatmap
    dba.plotHeatmap(tamoxifen)

    data(tamoxifen_counts)
    # counts correlation heatmap
    dba.plotHeatmap(tamoxifen)

    data(tamoxifen_analysis)
    #correlation heatmap based on all normalized data
    dba.plotHeatmap(tamoxifen,contrast=1,th=1)

    #correlation heatmap based on DB sites only
    dba.plotHeatmap(tamoxifen,contrast=1)

    #binding heatmap based on DB sites
    dba.plotHeatmap(tamoxifen,contrast=1,correlations=FALSE)

    #binding heatmap based on 1,000 sites with highest variance
    sites <- dba.plotHeatmap(tamoxifen,contrast=1,th=1,
                             correlations=FALSE,sortFun=var)
    sites

    data(tamoxifen_counts)
    #Examples of  heatmaps using DB sites with different subsets of samples
    #exclude T47D
    tamoxifen <- dba.contrast(tamoxifen,design=FALSE,
                              group1=tamoxifen$masks$Resistant,
                              group2=c(3:5,10:11))
    tamoxifen <- dba.analyze(tamoxifen)

    # regular heatmaps with samples from two contrast groups only
    dba.plotHeatmap(tamoxifen, contrast=1)
    #also include the T47D samples
    dba.plotHeatmap(tamoxifen,contrast=1,mask=tamoxifen$masks$All)

    #correlation heatmap without MCF7
    plot(tamoxifen,contrast=1,mask=!tamoxifen$masks$MCF7)

    # binding heatmap using only the MCF7 samples
    dba.plotHeatmap(tamoxifen,contrast=1,mask=tamoxifen$masks$MCF7,correlations=FALSE)

[Package DiffBind version 3.2.7 Index]