dba.overlap {DiffBind} | R Documentation

## Compute binding site overlaps (occupancy analysis)

### Description

Computes binding overlaps and co-occupancy statistics

### Usage

    dba.overlap(DBA, mask, mode=DBA_OLAP_PEAKS,
                contrast, method=DBA$config$AnalysisMethod, th=DBA$config$th,
                bUsePval=DBA$config$bUsePval,
                report, byAttribute, bCorOnly=TRUE, CorMethod="pearson",
                DataType=DBA$config$DataType)

### Arguments

`DBA` | DBA object

`mask` | mask or vector of peakset numbers indicating a subset of peaksets to use (see `dba.mask`). When generating overlapping/unique peaksets, either two, three, or four peaksets may be specified. If the mode type is DBA_OLAP_ALL, and a contrast is specified, a value of TRUE (mask=TRUE) indicates that all samples should be included (otherwise only those present in one of the contrast groups will be included).
`mode` | indicates which results should be returned (see MODES below). One of: DBA_OLAP_PEAKS DBA_OLAP_ALL DBA_OLAP_RATE
`contrast` | contrast number to use. Only specified if contrast data is to be used when mode=DBA_OLAP_ALL. See `dba.show(DBA, bContrast=T)` to get contrast numbers.
`method` | if contrast is specified and mode=DBA_OLAP_ALL, use data from method used for analysis: DBA_DESEQ2 DBA_DESEQ2_BLOCK DBA_EDGER DBA_EDGER_BLOCK
`th` | if contrast is specified and mode=DBA_OLAP_ALL, significance threshold; all sites with FDR (or p-values, see `bUsePval`) less than or equal to this value will be included. A value of 1 will include all binding sites, but only the samples included in the contrast.
`bUsePval` | if contrast is specified and mode=DBA_OLAP_ALL, logical indicating whether to use FDR (FALSE) or p-value (TRUE) for thresholding.
`report` | if contrast is specified and mode=DBA_OLAP_ALL, a report (obtained from `dba.report`) specifying the data to be used. If counts are included in the report (and a contrast is specified), the count data from the report will be used to compute correlations, rather than the scores in the global binding affinity matrix. If report is present, the `method`, `th`, and `bUsePval` parameters are ignored.
`byAttribute` | when computing co-occupancy statistics (DBA_OLAP_ALL), limit comparisons to peaksets with the same value for a specific attribute, one of: DBA_ID DBA_TISSUE DBA_FACTOR DBA_CONDITION DBA_TREATMENT DBA_REPLICATE DBA_CONSENSUS DBA_CALLER
`bCorOnly` | when computing co-occupancy statistics (DBA_OLAP_ALL), logical indicating that only correlations, and not overlaps, should be computed. This is much faster if only correlations are desired (e.g. to plot the correlations using `dba.plotHeatmap`).
`CorMethod` | when computing co-occupancy statistics (DBA_OLAP_ALL), method to use when computing correlations.
`DataType` | if mode==DBA_OLAP_PEAKS, the class of object that peaksets should be returned as: DBA_DATA_GRANGES DBA_DATA_RANGEDDATA DBA_DATA_FRAME Can be set as default behavior by setting `DBA$config$DataType`.

### Details

MODE: Generate overlapping/unique peaksets:

dba.overlap(DBA, mask, mode=DBA_OLAP_PEAKS, minVal)

MODE: Compute correlation and co-occupancy statistics (e.g. for dba.plotHeatmap):

dba.overlap(DBA, mask, mode=DBA_OLAP_ALL, byAttribute, minVal, attributes, bCorOnly, CorMethod)

MODE: Compute correlation and co-occupancy statistics using significantly differentially bound sites (e.g. for dba.plotHeatmap):

dba.overlap(DBA, mask, mode=DBA_OLAP_ALL, byAttribute, minVal, contrast, method, th=, bUsePval, attributes, bCorOnly, CorMethod)

Note that the scores from the global binding affinity matrix will be used for correlations unless a report containing count data is specified.

MODE: Compute overlap rates at different stringency thresholds:

dba.overlap(DBA, mask, mode=DBA_OLAP_RATE, minVal)

### Value

Value depends on the mode specified in the mode parameter.

If mode = DBA_OLAP_PEAKS, Value is an overlap record: a list of three peaksets for an A-B overlap, seven peaksets for a A-B-C overlap, and fifteen peaksets for a A-B-C-D overlap:

`inAll` | peaks in all peaksets
`onlyA` | peaks unique to peakset A
`onlyB` | peaks unique to peakset B
`onlyC` | peaks unique to peakset C
`onlyD` | peaks unique to peakset D
`notA` | peaks in all peaksets except peakset A
`notB` | peaks in all peaksets except peakset B
`notC` | peaks in all peaksets except peakset C
`notD` | peaks in all peaksets except peakset D
`AandB` | peaks in peaksets A and B but not in peaksets C or D
`AandC` | peaks in peaksets A and C but not in peaksets B or D
`AandD` | peaks in peaksets A and D but not in peaksets B or C
`BandC` | peaks in peaksets B and C but not in peaksets A or D
`BandD` | peaks in peaksets B and D but not in peaksets A or C
`CandD` | peaks in peaksets C and D but not in peaksets A or B

If mode = DBA_OLAP_ALL, Value is a correlation record: a matrix with a row for each pair of peaksets and the following columns:

`A` | peakset number of first peakset in overlap
`B` | peakset number of second peakset in overlap
`onlyA` | number of sites unique to peakset A
`onlyB` | number of sites unique to peakset B
`inAll` | number of peaks in both peakset A and B (merged)
`R2` | correlation value A vs B
`Overlap` | percentage overlap (number of overlapping sites divided by number of peaks unique to smaller peakset

If mode = DBA_OLAP_RATE, Value is a vector whose length is the number of peaksets, containing the number of overlapping peaks at the corresponding minOverlaps threshold (i.e., Value[1] is the total number of unique sites, Value[2] is the number of unique sites appearing in at least two peaksets, Value[3] the number of sites overlapping in at least three peaksets, etc.).

### Author(s)

Rory Stark

### See Also

`dba.plotVenn`, `dba.plotHeatmap`

### Examples

    data(tamoxifen_peaks)
    # default mode: DBA_OLAP_PEAKS -- get overlapping/non overlapping peaksets
    mcf7 <- dba.overlap(tamoxifen,tamoxifen$masks$MCF7&tamoxifen$masks$Responsive)
    names(mcf7)
    mcf7$inAll

    # mode:  DBA_OLAP_ALL -- get correlation record
    mcf7 <- dba(tamoxifen,tamoxifen$masks$MCF7)
    mcf7.corRec <- dba.overlap(mcf7,mode=DBA_OLAP_ALL,bCorOnly=FALSE)
    mcf7.corRec

    # mode: DBA_OLAP_RATE -- get overlap rate vector
    data(tamoxifen_peaks)
    rate <- dba.overlap(tamoxifen, mode=DBA_OLAP_RATE)
    rate
    plot(rate,type='b',xlab="# peaksets",ylab="# common peaks",
         main="Tamoxifen dataset overlap rate")

[Package DiffBind version 2.12.0 Index]