Find over-represented motifs in genomic regions

Identify DNA sequence motifs that are over-represented in a set of genomic features (for example, a set of differentially accessible peaks) relative to a background set of features. Enrichment is quantified with a one-sided hypergeometric test.

Usage

FindMotifs(
  object,
  features,
  background = 40000,
  assay = NULL,
  verbose = TRUE,
  p.adjust.method = "BH",
  ...
)

Arguments

object: A Seurat object
features: A vector of features to test for enrichment over the background set. These should be present in the motifs data of the assay.
background: Either a vector of features to use as the background set, or a number specifying the number of features to select as a background set. If a number is provided, regions will be selected to match the sequence characteristics of the query features. To match the sequence characteristics, these characteristics must be stored in the feature metadata for the assay. This can be added using the RegionStats() function. If NULL, use all features in the assay.
assay: Which assay to use. Default is the active assay
verbose: Display messages
p.adjust.method: Multiple testing correction method to be applied. Passed to stats::p.adjust().
...: Arguments passed to MatchRegionStats().

Value

Returns a data frame with one row per motif and the following columns:

motif: the motif ID
observed: number of query features containing the motif
background: number of background features containing the motif
percent.observed: percentage of query features containing the motif
percent.background: percentage of background features containing the motif
fold.enrichment: percent.observed divided by percent.background
pvalue: the hypergeometric enrichment p-value
motif.name: the motif name
p.adjust: the p-value adjusted for multiple testing

Rows are ordered by increasing pvalue, breaking ties by decreasing fold.enrichment.

Details

For each motif, FindMotifs compares how often the motif occurs in the query features to how often it occurs in a background set of features. The motif occurrences themselves are taken from the motifs data of the assay (a binary feature-by-motif matrix created with AddMotifs()). The procedure is:

Restrict to scored features. Query and background features that are not present in the motif matrix are dropped, since motif occurrences are only known for the features that were scored.
Select the background set. If background is a single number, that many features are selected to match the sequence characteristics (by default GC content) of the query using MatchRegionStats(), drawn from features other than the query. If background is a vector of feature names it is used directly; if it is NULL, all features in the assay are used. Matching the background to the query's sequence composition is important, since a motif can appear enriched simply because the query features differ in base composition from the genomic average (for example, a GC-rich query will appear enriched for GC-rich motifs) rather than because of genuine biological enrichment.
Count motif occurrences. For every motif the function counts the number of query features containing it (observed) and the number of background features containing it (background).
Compute the enrichment p-value. The query and background features together define a population of features (their union). For each motif, let q be the number of query features containing the motif, k the number of query features, m the number of features in the population containing the motif, and N the total number of features in the population. The one-sided hypergeometric p-value is phyper(q - 1, m, N - m, k, lower.tail = FALSE), the probability of observing at least q motif-containing features when k features are drawn at random from the population. Defining the population as the union of the query and background guarantees that m >= q and N >= k, so the test is always well defined whether or not the background overlaps the query.
Summarize and correct for multiple testing. A fold enrichment is reported as the percentage of query features containing the motif divided by the percentage of background features containing the motif, and the p-values are adjusted across motifs with stats::p.adjust() using p.adjust.method. Results are ordered by increasing p-value, breaking ties by decreasing fold enrichment.

Examples

de.motif <- head(rownames(atac_small))
bg.peaks <- tail(rownames(atac_small))
FindMotifs(
  object = atac_small,
  features = de.motif,
  background = bg.peaks
)
#> Testing motif enrichment in 6 regions
#> Warning: Testing motif enrichment using a small number of regions is not recommended
#>             motif observed background percent.observed percent.background
#> MA0040.1 MA0040.1        2          0         33.33333            0.00000
#> MA0041.1 MA0041.1        1          0         16.66667            0.00000
#> MA0029.1 MA0029.1        2          2         33.33333           33.33333
#> MA0006.1 MA0006.1        0          2          0.00000           33.33333
#> MA0057.1 MA0057.1        0          1          0.00000           16.66667
#> MA0004.1 MA0004.1        0          0          0.00000            0.00000
#> MA0019.1 MA0019.1        0          0          0.00000            0.00000
#> MA0030.1 MA0030.1        0          0          0.00000            0.00000
#> MA0031.1 MA0031.1        0          0          0.00000            0.00000
#> MA0051.1 MA0051.1        0          0          0.00000            0.00000
#>          fold.enrichment    pvalue   motif.name p.adjust
#> MA0040.1             Inf 0.2272727        Foxq1        1
#> MA0041.1             Inf 0.5000000        Foxd3        1
#> MA0029.1               1 0.7272727        Mecom        1
#> MA0006.1               0 1.0000000    Ahr::Arnt        1
#> MA0057.1               0 1.0000000  MZF1(var.2)        1
#> MA0004.1             NaN 1.0000000         Arnt        1
#> MA0019.1             NaN 1.0000000 Ddit3::Cebpa        1
#> MA0030.1             NaN 1.0000000        FOXF2        1
#> MA0031.1             NaN 1.0000000        FOXD1        1
#> MA0051.1             NaN 1.0000000         IRF2        1