enrich_motifs {universalmotif} | R Documentation

## Enrich for input motifs in a set of sequences.

### Description

Given a set of target and background sequences, test if the input motifs are significantly enriched in the targets sequences relative to the background sequences. See the "Sequence manipulation and scanning" vignette.

### Usage

    enrich_motifs(motifs, sequences, bkg.sequences, search.mode = "hits",
      max.p = 1e-05, max.q = 1e-05, max.e = 0.001, qval.method = "fdr",
      positional.test = "t.test", threshold = 0.001,
      threshold.type = "pvalue", verbose = 0, RC = FALSE, use.freq = 1,
      shuffle.k = 2, shuffle.method = "euler",
      return.scan.results = FALSE, progress = FALSE, BP = FALSE,
      nthreads = 1, rng.seed = sample.int(1e+09, 1), motif_pvalue.k = 8)

### Arguments

`motifs` | See `convert_motifs()` for acceptable motif formats.
`sequences` | `XStringSet` Sequences to scan. Alphabet should match motif.
`bkg.sequences` | `XStringSet` Optional; if missing, `shuffle_sequences()` is used to create background sequences from the input sequences.
`search.mode` | `character(1)` Deprecated. Only 'hits' is accepted.
`max.p` | `numeric(1)` P-value threshold.
`max.q` | `numeric(1)` Adjusted P-value threshold. This is only useful if multiple motifs are being enriched for.
`max.e` | `numeric(1)`. The E-value is calculated by multiplying the adjusted P-value with the number of input motifs times two (McLeay and Bailey 2010).
`qval.method` | `character(1)` See `stats::p.adjust()`.
`positional.test` | `character(1)` Deprecated. See `motif_peaks()`.
`threshold` | `numeric(1)` Between 0 and 1. See details.
`threshold.type` | `character(1)` One of `c('logodds', 'logodds.abs', 'pvalue')`. See details.
`verbose` | `numeric(1)` 0 for no output, 4 for max verbosity.
`RC` | `logical(1)` If `TRUE`, check reverse complement of input sequences.
`use.freq` | `numeric(1)` The default, 1, uses the motif matrix (from the `motif['motif']` slot) to search for sequences. If a higher number is used, then the matching k-let matrix from the `motif['multifreq']` slot is used. See `add_multifreq()`.
`shuffle.k` | `numeric(1)` The k-let size to use when shuffling input sequences. Only used if no background sequences are input. See `shuffle_sequences()`.
`shuffle.method` | `character(1)` One of `c('euler', 'markov', 'linear')`. See `shuffle_sequences()`.
`return.scan.results` | `logical(1)` Return output from `scan_sequences()`. For large jobs, leaving this as `FALSE` can save a small amount time by preventing construction of the complete results `data.frame` from `scan_sequences()`.
`progress` | `logical(1)` Deprecated. Does nothing.
`BP` | `logical(1)` Deprecated. See `nthreads`.
`nthreads` | `numeric(1)` Run `scan_sequences()` in parallel with `nthreads` threads. `nthreads = 0` uses all available threads. Note that no speed up will occur for jobs with only a single motif and sequence.
`rng.seed` | `numeric(1)` Set random number generator seed. Since shuffling can occur simultaneously in multiple threads using C++, it cannot communicate with the regular `R` random number generator state and thus requires an independent seed. Each individual sequence in an `XStringSet` object will be given the following seed: `rng.seed * index`. See `shuffle_sequences()`.
`motif_pvalue.k` | `numeric(1)` Control `motif_pvalue()` approximation. See `motif_pvalue()`.

### Details

To find enriched motifs, `scan_sequences()` is run on both target and background sequences. `stats::fisher.test()` is run to test for enrichment.

See `scan_sequences()` for more info on scanning parameters.

### Value

`DataFrame` Enrichment results in a `DataFrame`. Function args and (optionally) scan results are stored in the `metadata` slot.

### Author(s)

Benjamin Jean-Marie Tremblay b2tremblay@uwaterloo.ca

### References

McLeay R, Bailey T (2010). “Motif Enrichment Analysis: A unified framework and method evaluation.” BMC Bioinformatics, 11.

### See Also

`scan_sequences()`, `shuffle_sequences()`, `add_multifreq()`, `motif_pvalue()`

### Examples

    data(ArabidopsisPromoters)
    data(ArabidopsisMotif)
    enrich_motifs(ArabidopsisMotif, ArabidopsisPromoters, threshold = 0.01)

[Package universalmotif version 1.4.10 Index]