PWMEnrich (version 4.8.2)

motifDiffEnrichment: Differential motif enrichment

Description

Test for differential enrichment between two groups of sequences

Usage

motifDiffEnrichment(sequences1, sequences2, pwms, score = "autodetect", bg = "autodetect", cutoff = log2(exp(4)), verbose = TRUE, res1 = NULL, res2 = NULL)

Arguments

sequences1

First set of sequences. Can be either a single sequence (an object of class DNAString), or a list of DNAString objects, or a DNAStringSet object.

sequences2

Second set of sequences. Can be either a single sequence (an object of class DNAString), or a list of DNAString objects, or a DNAStringSet object.

pwms

this parameter can take multiple values depending on the scoring scheme and background correction used. When the method parameter is set to "autodetect", the following default algorithms are going to be used:

• if pwms is a list containing either frequency matrices or a list of PWM objects then the "affinity" algorithm is selected. If frequency matrices are given, they are converted to PWMs using uniform background. For best performance, convert frequency matrices to PWMs before calling this function using realistic genomic background.
• Otherwise, appropriate scoring scheme and background correction are selected based on the class of the object (see below).

score

this parameter determines which scoring scheme to use. Following scheme as available:

• "autodetect" - default value. Scoring method is determined based on the type of pwms parameter.
• "affinity" - use threshold-free affinity scores without a background. The pwms parameter can either be a list of frequency matrices, PWM objects, or a PWMLognBackground object.
• "cutoff" - use number of motif hits above a score cutoff as a measure of enrichment. No background correction is performed. The pwms parameter can either be a list of frequency matrices, PWM objects, or a PWMCutoffBackground object.

bg

this parameter determines which background correction to use, if any.

• "autodetect" - default value. Background correction is determined based on the type of the pwms parameter.
• "logn" - use a lognormal distribution background pre-computed for a set of PWMs. This requires pwms to be of class PWMLognBackground.
• "z" - use a z-score for the number of significant motif hits compared to background number of hits. This requires pwms to be of class PWMCutoffBackground.
• "none" - no background correction

cutoff

the score cutoff for a significant motif hit if scoring scheme "cutoff" is selected.

res1

the output of motifEnrichment if already calculated for sequences1

res2

the output of motifEnrichment if already calculated for sequences2

verbose

if to produce verbose output

Details

This function calls motifEnrichment on two groups of sequences and calculates the difference statistics when possible.

Examples

if(require("PWMEnrich.Dmelanogaster.background")){
  # load the background file for drosophila and lognormal correction
  data(PWMLogn.dm3.MotifDb.Dmel)

  # get the differential enrichment
  diff = motifDiffEnrichment(DNAString("TGCATCAAGTGTGTAGTGTGAGATTAGT"), DNAString("TGAACGAGTAGGACGATGAGAGATTGATG"), PWMLogn.dm3.MotifDb.Dmel, verbose=FALSE)

  # motifs differentially enriched in the first sequence (with lognormal background correction)
  head(sort(diff$group.bg, decreasing=TRUE))

  # motifs differentially enriched in the second sequence (with lognormal background correction)
  head(sort(diff$group.bg))
}