dba.contrast: Set up contrasts for differential binding affinity analysis
In DiffBind: Differential Binding Analysis of ChIP-Seq Peak Data

Description Usage Arguments Details Value Note Author(s) See Also Examples

Sets up contrasts for differential binding affinity analysis

dba.contrast(DBA, design=missing(group1), contrast,
             group1, group2=!group1, name1, name2,
             minMembers=3, block, bNot=FALSE, bComplex=FALSE,
             categories=c(DBA_TISSUE,DBA_FACTOR,DBA_CONDITION,DBA_TREATMENT),
             bGetCoefficients=FALSE, reorderMeta)

DBA

DBA object with count data

design

Either a logical value, or a character string containing a valid design formula.

If a logical value is specified, TRUE indicates that a design should automatically be generated. If contrast is missing, contrasts will automatically be added and an appropriate design computed. If a contrast is specified, it must consist of a character vector of length three, containing a factor and two factor values. No groups can be specified. If set to FALSE, the contrast will be added between the groups, if specified; otherwise, if group is missing, all possible contrasts will be added.

If a design formula is specified, it must be composed from the following allowable factors:

Tissue
Factor
Condition
Treatment
Replicate
Caller

If design is not explictly specified, and no group is specified, then design will be set to the value of DBA$config$design, if present (see DiffBind3).

`contrast`	If a `design` has been specified (previously or in the current call), the following contrasts forms may be indicated: Character vector of length three. The first element is a factor from the `design`. The second and third elements are values for that factor associated with sample groups. List of length 1, containing a design matrix column name (as obtained using `bGetCoefficients`). List of length 2, containing two design matrix column names (as obtained using `bGetCoefficients`), first the numerator and the second the denominator. Character vector of length one, containing a design matrix column name (as obtained using `bGetCoefficients`). Numeric vector of the same length as the list of design matrix column names (as obtained using `bGetCoefficients`), with a weighting for each column.
`group1`	mask of samples in first group (when adding a specific contrast). See `dba.mask`. Can not be used with an explicit `design`.
`group2`	mask of samples in second group (when adding a specific contrast). See `dba.mask`. Can not be used with an explicit `design`.
`name1`	label for samples in first group (when adding a specific contrast).
`name2`	label for samples in second group (when adding a specific contrast).
`minMembers`	when automatically generating contrasts, minimum number of unique samples in a group. Must be at least 2, as replicates are strongly advised. If you wish to do an analysis with no replicates, you can set the group1 and group2 parameters explicitly.
`bNot`	include contrasts consisting of a group and all other samples not in that group (indicated by a ! in the contrast name).
`bComplex`	include complex contrasts where groups include samples with the same values for multiple factors.
`categories`	when automatically generating contrasts, attribute or vector of attributes to base contrasts on: DBA_ID DBA_TISSUE DBA_FACTOR DBA_CONDITION DBA_TREATMENT DBA_REPLICATE DBA_CALLER
`block`	blocking attribute for multi-factor analysis. This may be specified as either a value, a vector, or a list. If block is a value, the specified metadata field is used to derive the blocking factor. One of: DBA_TISSUE DBA_FACTOR DBA_CONDITION DBA_TREATMENT DBA_REPLICATE DBA_CALLER If block is a vector, it can either be a mask (logical vector) or a vector of peakset numbers. In this case, the peaksets indicated in the blocking vector are all given the same factor value (true), while any peaksets not included in the vector take the alternative factor value (false). If block is a list, it should be a list of vectors (either logical masks or vectors of peakset numbers), with each indicating a set of peaksets that should share the same value. Each peakset should appear at most once, and any peaksets not specified will be given an default value (other).
`bGetCoefficients`	If `TRUE`, return the names of the columns (coefficients) associated with the `design`. These can be used to specify a `contrast`. If `bGetCoefficients=TRUE`, all other parameters (except `DBA` and `design`, if specified) will be ignored.
`reorderMeta`	By default, the metadata factor levels will be ordered in the order they appear in the sample sheet. They can be re-ordered using this parameter. `reorderMeta` is specified as a list, with each element being a vector of character strings corresponding to unique factor values in the desired order. Each element should be named for the appropriate metadata factor, one of: Tissue Factor Condition Treatment Replicate Caller If the vector of factor values contains a subset of the possible values, the specified values will be set to be ordered first, with the remaining values following in their default order. If only one factor value is supplied, it will be set as the reference (or "control") value. Contrasts that are no longer valid will be removed (and a warning issued) if detected. These include contrasts specified as a numeric vector of coefficients, or contrasts specified using coefficient names that no longer exists after reordering the metadata factor levels. Any existing analysis will be removed when metadata factor levels are reordered, necessitating another call to `dba.analyze`

MODE: Set up a specific contrast using a design:

dba.contrast(DBA, design, contrast)

MODE: Set up all possible contrasts:

dba.contrast(DBA, minMembers, categories)

MODE: Set up a specific contrast without an explicit design:

dba.contrast(DBA, design=FALSE, group1, group2, name1, name2, block)

DBA object with contrast(s) set as DBA$contrasts.

Contrast list can be retrieved using dba.show(DBA, bContrasts=TRUE).

Contrasts will only be set up for peaksets where DBA_CALLER == "counts".

Contrasts can be cleared by DBA$contrasts <- NULL.

Rory Stark

dba.analyze

# Set up an explicit contrast
data(tamoxifen_counts)
tamoxifen <- dba.contrast(tamoxifen, contrast=c("Condition","Responsive","Resistant"))
tamoxifen
tamoxifen <- dba.analyze(tamoxifen)
dba.show(tamoxifen,bContrasts=TRUE)

# Add another contrast
tamoxifen <- dba.contrast(tamoxifen, contrast=c("Tissue","MCF7","BT474"))
dba.show(tamoxifen,bDesign=TRUE)

# Change design
tamoxifen <- dba.contrast(tamoxifen,design="~Tissue + Condition")
tamoxifen <- dba.analyze(tamoxifen)
tamoxifen

# Automatically add all contrasts between sample groups 
# where at least THREE samples have the same factor value
data(tamoxifen_counts)
tamoxifen <- dba.contrast(tamoxifen)
tamoxifen

# Automatically add all contrasts between sample groups 
# where at least TWO samples have the same factor value
tamoxifen <- dba.contrast(tamoxifen, minMembers=2)
dba.show(tamoxifen,bContrasts=TRUE)

### Use of complex contrasts                          
data(tamoxifen_counts)
tamoxifen <- dba.contrast(tamoxifen, contrast=c("Tissue","BT474","MCF7"))
dba.contrast(tamoxifen, bGetCoefficients=TRUE)

#Change design and factor ordering
tamoxifen <- dba.contrast(tamoxifen,design="~Tissue + Condition",
                          reorderMeta=list(Condition="Responsive",
                          Tissue=c("MCF7","ZR75","T47D","BT474")))
dba.contrast(tamoxifen, bGetCoefficients=TRUE)
tamoxifen <- dba.contrast(tamoxifen,contrast="Tissue_BT474_vs_MCF7")
tamoxifen <- dba.contrast(tamoxifen,contrast=list("Tissue_BT474_vs_MCF7"))
tamoxifen <- dba.contrast(tamoxifen,contrast=c(0,0,0,1,0))
tamoxifen <- dba.contrast(tamoxifen,
                          contrast=list("Tissue_BT474_vs_MCF7","Tissue_T47D_vs_MCF7"))
tamoxifen <- dba.contrast(tamoxifen,contrast=c(0,0,-1,1,0))
tamoxifen <- dba.contrast(tamoxifen,contrast=c(0,0,0,0,1))
dba.show(tamoxifen,bContrasts=TRUE)
tamoxifen <- dba.analyze(tamoxifen)
tamoxifen
tamoxifen <- dba.contrast(tamoxifen, 
                          contrast=c("Condition","Responsive","Resistant"))
tamoxifen <- dba.analyze(tamoxifen)
dba.show(tamoxifen,bContrasts=TRUE)[7:8,]
dba.plotVenn(tamoxifen, contrast=7:8, bDB=TRUE,          
             bAll=FALSE, bGain=TRUE, bLoss=TRUE)

## Explicit contrast, without design
data(tamoxifen_counts)
tamoxifen <- dba.contrast(tamoxifen, design=FALSE,
                          group1=tamoxifen$masks$Responsive, name1="Responsive",
                          group2=tamoxifen$masks$Resistant,  name2="Resistant",
                          block=DBA_TISSUE)
dba.show(tamoxifen, bContrasts=TRUE)
tamoxifen <- dba.analyze(tamoxifen)
dba.show(tamoxifen,bContrasts=TRUE)
dba.plotVenn(tamoxifen,contrast=1,method=c(DBA_DESEQ2,DBA_DESEQ2_BLOCK))