Installation

In order to perform the operations in this vignette, first install motifTestR.

if (!"BiocManager" %in% rownames(installed.packages()))
  install.packages("BiocManager")
BiocManager::install("motifTestR")

Once installed, we can load all required packages, set a default plotting theme and setup how many threads to use during the analysis.

library(motifTestR)
library(extraChIPs)
library(rtracklayer)
library(BSgenome.Hsapiens.UCSC.hg19)
library(parallel)
library(ggplot2)
library(patchwork)
library(universalmotif)
theme_set(theme_bw())
cores <- 1

Defining a Set of Peaks

The peaks used in this workflow were obtained from the bed files denoting binding sites of the Androgen Receptor and Estrogen Receptor along with H3K27ac marks, in ZR-75-1 cells under DHT treatment (Hickey et al. 2021). The object ar_er_peaks contains a subset of 849 peaks found within chromosome 1, with all peaks resized to 400bp

data("ar_er_peaks")
ar_er_peaks

## GRanges object with 849 ranges and 0 metadata columns:
##         seqnames              ranges strand
##            <Rle>           <IRanges>  <Rle>
##     [1]     chr1     1008982-1009381      *
##     [2]     chr1     1014775-1015174      *
##     [3]     chr1     1051296-1051695      *
##     [4]     chr1     1299561-1299960      *
##     [5]     chr1     2179886-2180285      *
##     ...      ...                 ...    ...
##   [845]     chr1 246771887-246772286      *
##   [846]     chr1 246868678-246869077      *
##   [847]     chr1 246873126-246873525      *
##   [848]     chr1 247095351-247095750      *
##   [849]     chr1 247267507-247267906      *
##   -------
##   seqinfo: 24 sequences from hg19 genome

sq <- seqinfo(ar_er_peaks)

Whilst the example dataset is small for the convenience of an R package, those wishing to work on the complete set of peaks (i.e. not just chromosome 1) may run the code provided in the final section to obtain all peaks. This will produce a greater number of significant results in subsequent analyses but will also increase running times for all functions.

Obtaining a Set of Sequences for Testing

Now that we have genomic co-ordinates as a set of peaks, we can obtain the sequences that are associated with each peak. The source ranges can optionally be added to the sequences as names by coercing the ranges to a character vector.

test_seq <- getSeq(BSgenome.Hsapiens.UCSC.hg19, ar_er_peaks)
names(test_seq) <- as.character(ar_er_peaks)

Obtaining a List of PWMs for Testing

A small list of Position Frequency Matrices (PFMs), obtained from MotifDb are provided with the package and these will be suitable for all downstream analysis. All functions will convert PFMs to PWMs internally.

data("ex_pfm")
names(ex_pfm)

## [1] "ESR1"  "ANDR"  "FOXA1" "ZN143" "ZN281"

ex_pfm$ESR1

##       1     2     3     4     5     6     7     8     9    10    11    12    13
## A 0.638 0.074 0.046 0.094 0.002 0.856 0.108 0.396 0.182 0.104 0.054 0.618 0.040
## C 0.048 0.006 0.018 0.072 0.888 0.006 0.442 0.604 0.376 0.078 0.034 0.198 0.884
## G 0.260 0.808 0.908 0.178 0.048 0.112 0.312 0.000 0.286 0.044 0.908 0.070 0.014
## T 0.054 0.112 0.028 0.656 0.062 0.026 0.138 0.000 0.156 0.774 0.004 0.114 0.062
##      14    15
## A 0.090 0.058
## C 0.822 0.330
## G 0.008 0.066
## T 0.080 0.546

Again, a larger set of motifs may be obtained using or modifying the example code at the end of the vignette

Finding PWM Matches

All PWM matches within the test sequences can be returned for any of the PWMs, with getPwmMatches() searching using the PWM and it’s reverse complement by default. Matches are returned showing their position within the sequence, as well as the distance from the centre of the sequence and the matching section within the larger sequence. Whilst there is no strict requirement for sequences of the same width, generally this is good practice for this type of analysis and is commonly a requirement for downstream statistical analysis.

score_thresh <- "70%"
getPwmMatches(ex_pfm$ESR1, test_seq, min_score = score_thresh)

## DataFrame with 51 rows and 8 columns
##                        seq     score direction     start       end from_centre
##                <character> <numeric>  <factor> <integer> <integer>   <numeric>
## 1     chr1:1008982-1009381   17.3522         R       216       230          23
## 2     chr1:6543164-6543563   15.7958         R       176       190         -17
## 3   chr1:10010470-10010869   18.0880         F       193       207           0
## 4   chr1:11434290-11434689   20.8412         R       321       335         128
## 5   chr1:17855904-17856303   15.7429         F       195       209           2
## ...                    ...       ...       ...       ...       ...         ...
## 47  chr1:212731397-21273..   16.1154         R        88       102        -105
## 48  chr1:214500812-21450..   17.1325         R       186       200          -7
## 49  chr1:217979498-21797..   16.6438         F       186       200          -7
## 50  chr1:233243433-23324..   15.7178         F       201       215           8
## 51  chr1:247267507-24726..   16.8796         F       313       327         120
##     seq_width           match
##     <integer>  <DNAStringSet>
## 1         400 TGGTCACAGTGACCT
## 2         400 GGGTCATCCTGTCCC
## 3         400 AGGTCACCCTGGCCC
## 4         400 AGGTCACCGTGACCC
## 5         400 AGGGCAAAATGACCC
## ...       ...             ...
## 47        400 GTGTCACAGTGACCC
## 48        400 AGGTCACAATGACAT
## 49        400 GGGTCATCCTGCCCC
## 50        400 AGGTCATAAAGACCT
## 51        400 AGGTCAGAATGACCG

Many sequences will contain multiple matches, and we can subset our results to only the ‘best match’ by setting best_only = TRUE. The best match is chosen by the highest score returned for each match. If multiple matches return identical scores, all tied matches are returned by default and will be equally down-weighted during positional analysis. This can be further controlled by setting break_ties to any of c(“random”, “first”, “last”, “central”), which will choose randomly, by sequence order or proximity to centre.

getPwmMatches(ex_pfm$ESR1, test_seq, min_score = score_thresh, best_only = TRUE)

## DataFrame with 50 rows and 8 columns
##                        seq     score direction     start       end from_centre
##                <character> <numeric>  <factor> <integer> <integer>   <numeric>
## 1     chr1:1008982-1009381   17.3522         R       216       230          23
## 2     chr1:6543164-6543563   15.7958         R       176       190         -17
## 3   chr1:10010470-10010869   18.0880         F       193       207           0
## 4   chr1:11434290-11434689   20.8412         R       321       335         128
## 5   chr1:17855904-17856303   15.7429         F       195       209           2
## ...                    ...       ...       ...       ...       ...         ...
## 46  chr1:212731397-21273..   16.1154         R        88       102        -105
## 47  chr1:214500812-21450..   17.1325         R       186       200          -7
## 48  chr1:217979498-21797..   16.6438         F       186       200          -7
## 49  chr1:233243433-23324..   15.7178         F       201       215           8
## 50  chr1:247267507-24726..   16.8796         F       313       327         120
##     seq_width           match
##     <integer>  <DNAStringSet>
## 1         400 TGGTCACAGTGACCT
## 2         400 GGGTCATCCTGTCCC
## 3         400 AGGTCACCCTGGCCC
## 4         400 AGGTCACCGTGACCC
## 5         400 AGGGCAAAATGACCC
## ...       ...             ...
## 46        400 GTGTCACAGTGACCC
## 47        400 AGGTCACAATGACAT
## 48        400 GGGTCATCCTGCCCC
## 49        400 AGGTCATAAAGACCT
## 50        400 AGGTCAGAATGACCG

We can return all matches for a complete list of PWMs, as a list of DataFrame objects. This strategy allows for visualisation of results as well as testing for positional bias.

bm_all <- getPwmMatches(
  ex_pfm, test_seq, min_score = score_thresh, best_only = TRUE, break_ties = "all",
  mc.cores = cores
)

This same strategy of passing a single, or multiple PWMs can be applied even when simply wishing to count the total matches for each PWM. Counting may be useful for restricting downstream analysis to the set of motifs with more than a given number of matches.

countPwmMatches(ex_pfm, test_seq, min_score = score_thresh, mc.cores = cores)

##  ESR1  ANDR FOXA1 ZN143 ZN281 
##    51    36   292    43    46

Testing for Positional Bias

A commonly used tool within the MEME-Suite is centrimo (Bailey and Machanick 2012) and motifTestR provides a simple, easily interpretable alternative approach using testMotifPos(). This function bins the distances from the centre of each sequence with the central bin being symmetrical around zero, and if no positional bias is expected (i.e. H₀), matches should be equally distributed between bins. Unlike centrimo, no assumption of centrality is made and any notable deviations from a discrete uniform distribution may be considered as significant.

A test within each bin is performed using binom.test() and a single, summarised p-value across all bins is returned using the asymptotically exact harmonic mean p-value (HMP) (Wilson 2019). By default, the binomial test is applied for the null hypothesis to detect matches in each bin which are greater than expected, however, this can also be set by the user. When using the harmonic-mean p-value however, choosing the alternate hypothesis as “greater” tends return a more conservative p-value across the entire set of bins.

res_pos <- testMotifPos(bm_all, mc.cores = cores)
head(res_pos)

##       start end centre width total_matches matches_in_region  expected
## ESR1      5  15     10    10            50                 8  1.291990
## ANDR    -25  -5    -15    20            34                12  1.770833
## FOXA1    -5  25     10    30           238                32 12.205128
## ZN143   -55  55      0   110            26                20  5.473684
## ZN281  -195 195      0   390            40                38 25.529716
##       enrichment prop_total           p         fdr consensus_motif
## ESR1    6.192000  0.1600000 0.001643146 0.008215728    35, 0, 1....
## ANDR    6.776471  0.3529412 0.004700634 0.011751585    0, 0, 0,....
## FOXA1   2.621849  0.1344538 0.010576124 0.017626873    0, 0, 0,....
## ZN143   3.653846  0.7692308 0.243171867 0.303964834    6, 1, 13....
## ZN281   1.488462  0.9500000 0.977504172 0.977504172    8, 6, 22....

The bins returned by the function represent the widest range of bins where the raw p-values were below the HMP. Wide ranges tend to be associated with lower significance for a specific PWM. This is a further point of divergence from centrimo in that results are dependent on the pre-determined bin-size and the region of enrichment is formed using p-values, instead of the adaptive methods of centrimo (Bailey and Machanick 2012).

Due to the two-stranded nature of DNA, the distance from zero can also be assessed by setting abs = TRUE and in this case the first bin begins at zero.

res_abs <- testMotifPos(bm_all, abs = TRUE, mc.cores = cores) 
head(res_abs)

##       start end centre width total_matches matches_in_region  expected
## ESR1     10  20     15    10            50                11  2.590674
## ANDR     10  20     15    10            34                 8  1.770833
## FOXA1     0  30     15    30           238                69 36.615385
## ZN143     0  50     25    50            26                20  6.842105
## ZN281     0 190     95   190            40                38 33.160622
##       enrichment prop_total            p         fdr consensus_motif
## ESR1    4.246000  0.2200000 0.0007907262 0.003953631    35, 0, 1....
## ANDR    4.517647  0.2352941 0.0057468643 0.014367161    0, 0, 0,....
## FOXA1   1.884454  0.2899160 0.0106210602 0.017701767    0, 0, 0,....
## ZN143   2.923077  0.7692308 0.1963203926 0.245400491    6, 1, 13....
## ZN281   1.145938  0.9500000 0.9173293626 0.917329363    8, 6, 22....

This approach is particularly helpful for detecting co-located transcription factors which can be any distance from the TF which was used to obtain and centre the test set of sequences.

Viewing Matches

The complete set of matches returned as a list above can be simply passed to ggplot2 (Wickham 2016) for visualisation, in order to asses whether any PWM appears to have a positional bias. By default, smoothed values across all motifs will be overlaid (Figure 1A), however, tailoring using ggplot is simple to produce a wide variety of outputs (Figure 1B)

topMotifs <- res_pos |>
    subset(fdr < 0.05) |>
    rownames()
A <- plotMatchPos(bm_all[topMotifs], binwidth = 10, se = FALSE)
B <- plotMatchPos(
    bm_all[topMotifs], binwidth = 10, geom = "col", use_totals = TRUE
) +
  geom_smooth(se = FALSE, show.legend = FALSE) +
  facet_wrap(~name)
A + B + plot_annotation(tag_levels = "A") & theme(legend.position = "bottom")

Distribution of motif matches around the centres of the set of peaks

Whilst the above will produce figures showing the symmetrical distribution around the peak centres, the distance from the peak centre can also be shown as an absolute distance. In Figure 2 distances shown as a heatmap (A) or as a CDF (B). The latter makes it easy to see that 50% of ESR1 matches occur within a short distance of the centre (~25bp), whilst for ANDR and FOXA1, this distance is roughly doubled. Changing the binwidth argument can either smooth data or increase the fine resolution.

topMotifs <- res_abs |>
    subset(fdr < 0.05) |>
    rownames()
A <- plotMatchPos(bm_all[topMotifs], abs = TRUE, type = "heatmap") +
  scale_fill_viridis_c()
B <- plotMatchPos(
  bm_all[topMotifs], abs = TRUE, type = "cdf", geom = "line", binwidth = 5
)
A + B + plot_annotation(tag_levels = "A") & theme(legend.position = "bottom")

Distribution of motif matches shown as a distance from the centre of each sequence

Defining a Set of Control Sequences

Choosing a suitable set of control sequences can be undertaken by any number of methods. motifTestR enables a strategy of matching sequences by any number of given features. The data object zr75_enh contains the candidate enhancers for ZR-75-1 cells defined by v2.0 of the Enhancer Atlas (Gao and Qian 2019), for chromosome 1 only. A high proportion of our peaks are associated with these regions and choosing control sequences drawn from the same proportion of these regions may be a viable strategy.

data("zr75_enh")
mean(overlapsAny(ar_er_peaks, zr75_enh))

## [1] 0.6914016

First we can annotate each peak by whether there is any overlap with an enhancer, or whether the peak belongs to any other region. Next we can define two sets of GenomicRanges, one representing the enhancers and the other being the remainder of the genome, here restricted to chromosome 1 for consistency. Control regions can be drawn from each with proportions that match the test set of sequences.

ar_er_peaks$feature <- ifelse(
  overlapsAny(ar_er_peaks, zr75_enh), "enhancer", "other"
)
chr1 <- GRanges(sq)[1]
bg_ranges <- GRangesList(
  enhancer = zr75_enh,
  other = GenomicRanges::setdiff(chr1, zr75_enh)
)

The provided object hg19_mask contains regions of the genome which are rich in Ns, such as centromeres and telomeres. Sequences containing Ns produce warning messages when matching PWMs and avoiding these regions may be wise, without introducing any sequence bias. These are then passed to makeRMRanges() as ranges to be excluded, whilst sampling multiple random, size-matched ranges corresponding to our test set of ranges with sequences being analysed, and drawn proportionally from matching genomic regions. Whilst our example only used candidate enhancers, any type and number of genomic regions can be used, with a limitless number of classification strategies being possible.

data("hg19_mask")
set.seed(305)
rm_ranges <- makeRMRanges(
  splitAsList(ar_er_peaks, ar_er_peaks$feature),
  bg_ranges, exclude = hg19_mask,
  n_iter = 100
)

This has now returned a set of control ranges which are randomly-selected (R) size-matched (M) to our peaks and are drawn from a similar distribution of genomic features. By setting n_iter = 100, this set will be 100 times larger than our test set and typically this value can be set to 1000 or even 5000 for better estimates of parameters under the null distribution. However, this will increase the computational burden for analysis.

If not choosing an iterative strategy, a total number of sampled ranges can also be specified. In this case the column iteration will not be added to the returned ranges.

In order to perform the analysis, we can now extract the genomic sequences corresponding to our randomly selected control ranges. Passing the mcols element ensure the iteration numbers are passed to the sequences, as these are required for this approach.

rm_seq <- getSeq(BSgenome.Hsapiens.UCSC.hg19, rm_ranges)
mcols(rm_seq) <- mcols(rm_ranges)

If choosing strategies for enrichment testing outside of motifTestR, these sequences can be exported as a fasta file using writeXStringSet from the Biostrings package.

Testing For Enrichment

Testing for overall motif enrichment is implemented using multiple strategies, using Poisson, QuasiPoisson or pure Iterative approaches. Whilst some PWMs may closely follow a Poisson distribution under H₀, others may be over-dispersed and more suited to a Quasi-Poisson approach. Each approach has unique advantages and weaknesses as summarised below:

• Poisson
  • Can use any number of BG Sequences, unrelated to the test set
  • Modelling is performed based on the expected number of matches per sequence
  • The fastest approach
  • Anti-conservative p-values where counts are over-dispersed
  • Appropriate for “quick & dirty” checks for expected discoveries
• QuasiPoisson
  • Modelling is performed per set of sequences (of identical size to the test set)
  • Requires BG Sequences to be in ‘iterative’ blocks
  • Fewer ‘iterative blocks’ can still model over-dispersion reasonably well
• Iterative
  • No model assumptions
  • Requires BG Sequences to be in ‘iterative’ blocks
  • P-Values derived from Z-scores (using the Central Limit Theorem)
  • Sampled p-values from iterations can be used if preferred
  • Requires the largest number of iterative blocks (>1000)
  • Slowest, but most reliable approach

From a per iteration perspective there is little difference between the Iterative and the modelled QuasiPoisson approaches, however the modelled approaches can still return reliable results from a lower number of iterative blocks, lending a clear speed advantage. Z-scores returned are only used for statistical testing under the iterative approach and are for indicative purposes only under all other models model.

Whilst no guidelines have been developed for an optimal number of sequences, a control set which is orders of magnitude larger than the test set may be prudent. A larger set of control sequences clearly leads to longer analytic time-frames and larger computational resources, so this is left to what is considered appropriate by the researcher, nothing that here, we chose a control set which is 100x larger than our test sequences. If choosing an iterative approach and using the iteration-derived p-values, setting a number of iterations based on the resolution required for these values may be important, noting that the lowest possible p-value is 1/n_iterations.

enrich_res <- testMotifEnrich(
  ex_pfm, test_seq, rm_seq, min_score = score_thresh, model = "quasi", mc.cores = cores
)
head(enrich_res)

##       sequences matches expected enrichment          Z            p
## ZN143       849      43     0.19 226.315789 102.144041 2.355850e-37
## ESR1        849      51     4.41  11.564626  21.469841 3.071728e-29
## FOXA1       849     292   125.64   2.324101  13.345825 9.782504e-23
## ANDR        849      36    11.53   3.122290   7.014137 2.621038e-09
## ZN281       849      46    19.53   2.355351   5.186250 2.777006e-06
##                fdr n_iter     sd_bg
## ZN143 1.177925e-36    100  0.419114
## ESR1  7.679321e-29    100  2.170021
## FOXA1 1.630417e-22    100 12.465322
## ANDR  3.276298e-09    100  3.488669
## ZN281 2.777006e-06    100  5.103880

Setting the model to “iteration” instead uses a classical iterative approach to define the null distributions of counts and Z-scores are calculated from these values. The returned p-values from this test are taken from the Z-scores directly, with p-values derived from the sampled iterations also returned if preferred for use in results by the researcher. Whilst requiring greater computational effort, fewer statistical assumptions are made and results may be more conservative than under modelling approaches.

iter_res <- testMotifEnrich(
  ex_pfm, test_seq, rm_seq, min_score = score_thresh, mc.cores = cores, model = "iteration"
)
head(iter_res)

##       sequences matches expected enrichment          Z            p
## ESR1        849      51     4.41  11.564626  21.469841 0.000000e+00
## FOXA1       849     292   125.64   2.324101  13.345825 0.000000e+00
## ZN143       849      43     0.19 226.315789 102.144041 0.000000e+00
## ANDR        849      36    11.53   3.122290   7.014137 2.313705e-12
## ZN281       849      46    19.53   2.355351   5.186250 2.145708e-07
##                fdr iter_p n_iter     sd_bg
## ESR1  0.000000e+00   0.01    100  2.170021
## FOXA1 0.000000e+00   0.01    100 12.465322
## ZN143 0.000000e+00   0.01    100  0.419114
## ANDR  2.892131e-12   0.01    100  3.488669
## ZN281 2.145708e-07   0.01    100  5.103880

Once we have selected our motifs of interest, sequences with matches can be compared to easily assess co-occurrence, using plotOverlaps() from extraChIPs. In our test set, peaks were selected based on co-detection of ESR1 and ANDR, however the rate of co-occurrence is low, revealing key insights into the binding dynamics of these two TFs.

ex_pfm |>
  getPwmMatches(test_seq, min_score = score_thresh, mc.cores = cores) |>
  lapply(\(x) x$seq) |>
  plotOverlaps(type = "upset")

Distribution of select PWM matches within sequences. Each sequence is only considered once and as such, match numbers may be below those returned during testing, which includes multiple matches within a sequence.