A general example

In this document, we will discuss the use of background regions. We first demonstrate it with a ChIP-seq TFBS dataset from UCSC table browser. Parameters are:

In the “Select dataset” section:

clade = Mammal
genome = Human
assembly = GRCh37/hg19
group = Regulation
track = ENCODE 3 TFBS
table: GM12878 MYB

And in the “Retrieve and display data” section:

output format = BED - browser extensible data

Then click the button “get output”.

We first read it as a GRanges object.

library(rGREAT)
df = read.table("data/tb_encTfChipPkENCFF215YWS_GM12878_MYB_hg19.bed")
df = df[df[, 1] %in% paste0("chr", c(1:22, "X", "Y")), ]
gr = GRanges(seqnames = df[, 1], ranges = IRanges(df[, 2] + 1, df[, 3]))

The next two GREAT analysis uses the whole genome as background and excludes gap regions.

res1 = great(gr, "GO:BP", "hg19", exclude = NULL)
res2 = great(gr, "GO:BP", "hg19", exclude = "gap")

And we compare the significant GO terms:

tb1 = getEnrichmentTable(res1)
tb2 = getEnrichmentTable(res2)

library(eulerr)
lt = list(
    genome = tb1$id[tb1$p_adjust < 0.001],
    exclude_gap = tb2$id[tb2$p_adjust < 0.001]
)
plot(euler(lt), quantities = TRUE)

We can see, when excluding gap regions, there are fewer significant terms left. In GREAT analysis where Binomial test is applied, denote following variables: \(N\) as total number of input regions, \(n\) as number of input regions that fall into the extended TSS regions (denote the corresponding random variable as \(X\)), and \(p\) as the fraction of extended TSS regions in the genome, then \(X \sim B(p, N)\).

When gap regions are removed from the analysis, \(N\) and \(n\) are most likely unchanged because the input regions will not overlap to the gap regions, but \(p\) gets higher because the coverage of extended TSS regions is most likely unchanged, but the background size (genome subtracting gap regions) becomes smaller. When \(p\) gets higher while \(N\) and \(n\) are unchanged, the p-value from Binomial test also gets higher (when \(p\) gets higher, the probability of obtaining \(n\) regions from \(N\) with a success rate of \(p\) increases), which decreases the number of significant terms.

The null assumption of the Binomial test is that input regions are uniformaly distributed in the genome. Since gap regions are not sequenced and input regions will never overlap to them, using whole genome as background will not be proper and it under-estimates the fraction of a function associated regions in the genome, i.e. the value of \(p\), which results more smaller p-values and possible more false positives.

This might happen for other scenations, e.g. when dealing with methylation-related regions (e.g. differentially methylated regions, DMRs), choosing a background showing similar CpG density might be more proper, which can decrease the false positives caused by the regions that will never be called as DMRs (e.g. CpG poor regions).

Set background by chromosomes

This scenario might be less used, but it is a good example to show the idea. In great(), arguments background and exclude can be set to a vector of chromosomes to keep or to remove certain chromosomes, then all analysis is restricted in the selected chromosomes. In the following example, we apply GREAT analysis only on one single chromosome at a time.

res_list = list()
for(chr in paste0("chr", 1:22)) {
    res_list[[chr]] = great(gr, "GO:BP", "hg19", background = chr)
}

Next we compare the signigicant GO terms. In the followig plot, each row is a GO term, the first heatmap shows whether the GO term is significant (red) in the corresponding chromosome and the right square heatmap shows the similarities of GO terms. GO terms are clustered into several groups by clustering the similarity matrix. Summaries of GO terms in clusters are represented as word clouds and they are attached to the heatmap.

sig_list = lapply(res_list, function(x) {
    tb = getEnrichmentTable(x)
    tb$id[tb$p_adjust < 0.01]
})

library(simplifyEnrichment)
simplifyGOFromMultipleLists(sig_list)

From the plot we can see there are some degrees of specificities of the enrichment on different chromosomes, which are mainly caused by the unequal distribution of genes on chromosomes in gene sets.

Set background as a set of genomic regions

It is more common to set background by a set of pre-defined genomic regions. In the following example, we use the chromatin states dataset from the same cell line as in the first example. Parameters for retrieving the data from UCSC table browser are:

clade = Mammal
genome = Human
assembly = GRCh37/hg19
group = Regulation
track = Broad ChromHMM
table: GM12878 ChromHMM

We read the chromatin states data and format it as a list where each element in the list corresponds to regions in one single chromatin state.

df = read.table("data/GM12878_chromHMM.bed.gz")
df = df[df[, 1] %in% paste0("chr", c(1:22, "X", "Y")), ]
all_states = GRanges(seqnames = df[, 1], ranges = IRanges(df[, 2] + 1, df[, 3]), 
    state = gsub("^\\d+_", "", df[, 4]))
all_states = split(all_states, all_states$state)
names(all_states)
##  [1] "Active_Promoter" "Heterochrom/lo"  "Insulator"       "Poised_Promoter"
##  [5] "Repetitive/CNV"  "Repressed"       "Strong_Enhancer" "Txn_Elongation" 
##  [9] "Txn_Transition"  "Weak_Enhancer"   "Weak_Promoter"   "Weak_Txn"

Each time, we set background to only one chromatin state:

res_list = lapply(all_states, function(bg) {
    great(gr, "GO:BP", "hg19", background = bg)
})

We compare the numbers of significant GO terms:

sig_list = lapply(res_list, function(x) {
    tb = getEnrichmentTable(x)
    tb$id[tb$p_adjust < 0.05]
})
sapply(sig_list, length)
## Active_Promoter  Heterochrom/lo       Insulator Poised_Promoter  Repetitive/CNV 
##              35             310               2               0               0 
##       Repressed Strong_Enhancer  Txn_Elongation  Txn_Transition   Weak_Enhancer 
##               0             208               0               0              32 
##   Weak_Promoter        Weak_Txn 
##              32               8

It is interesting to see there are a lot of GO terms enriched when using heterchromatin as background. In the following parts of this document, we only look at three chromatin states: active promoter, strong enhancer and heterochromatin:

res_list = res_list[c("Active_Promoter", "Strong_Enhancer", "Heterochrom/lo")]

Next two plots demonstrate total widths of background regions in different states, and numbers of TFBS peaks falling in different background.

par(mar = c(4, 8, 4, 1), mfrow = c(1, 2), xpd = NA)
w = sapply(res_list, function(x) {
    sum(width(x@background))
})
barplot(w, horiz = TRUE, las = 1, xlab = "Base pairs", xlim = c(1, 2e9),
    main = "Sum of widths / background width")
n_gr = sapply(res_list, function(x) {
    x@n_total
})
barplot(n_gr, horiz = TRUE, las = 1, xlab = "Number",
    main = "Number of gr in background")
text(n_gr, 1:3, n_gr)

It is quite astonishing that there are only 62 TFBS peaks in heterochromatin regions, but the heterochromatin regions cover more than 90% of the genome. We check the top most significant GO terms:

tb = getEnrichmentTable(res_list[["Heterochrom/lo"]])
head(tb)
##           id                        description genome_fraction
## 1 GO:0032940                  secretion by cell      0.08585423
## 2 GO:1903530    regulation of secretion by cell      0.06286739
## 3 GO:0140352                   export from cell      0.09121197
## 4 GO:0051046            regulation of secretion      0.06874861
## 5 GO:0046903                          secretion      0.09709812
## 6 GO:0032880 regulation of protein localization      0.08021046
##   observed_region_hits fold_enrichment      p_value    p_adjust mean_tss_dist
## 1                   18        3.381576 2.908187e-06 0.001418865        297080
## 2                   15        3.848346 5.165993e-06 0.001418865        292459
## 3                   18        3.182944 6.799673e-06 0.001418865        297080
## 4                   15        3.519133 1.505106e-05 0.002012737        292459
## 5                   18        2.989992 1.607618e-05 0.002012737        297080
## 6                   16        3.217343 2.228778e-05 0.002325358        394119
##   observed_gene_hits gene_set_size fold_enrichment_hyper p_value_hyper
## 1                 15           715              3.669960  1.211072e-05
## 2                 12           494              4.249428  2.388200e-05
## 3                 15           774              3.390209  3.063420e-05
## 4                 12           550              3.816759  6.766322e-05
## 5                 15           837              3.135032  7.478033e-05
## 6                 12           731              2.871706  9.100576e-04
##   p_adjust_hyper
## 1    0.001895328
## 2    0.002491689
## 3    0.002576789
## 4    0.002976669
## 5    0.002976669
## 6    0.008901501

Take the first term “GO:0032940” for example, we can actually see, although there are only 62 TFBS peaks, 20 of them are associated with “GO:0032940” and it is more than five times higher than the expected number: 62*0.0844 = 5.2.

However, the mean distance of “GO:0032940” associated TFBS peaks to TSS in the heterochormatin background is 290kb, and mean distance to TSS of all peaks in heterochromatin is around 350kb, which is very far from TSS. With larger distance to TSS, the more we need to be careful with the relaiblity of the associations.

par(mar = c(4, 8, 4, 1), xpd = NA)
dist_list = sapply(res_list, function(x) {
    gra = getRegionGeneAssociations(x)
    mean(abs(unlist(gra$dist_to_TSS)))
})
barplot(dist_list, horiz = TRUE, las = 1, xlab = "mean distance to TSS",
    main = "mean distance to TSS")

Therefore, we will not consider the category of heterochromatin in the analysis because although it generates many significant terms statistically, whether they make biological sense needs to be questioned.

In the end, we only compare the significant GO terms from TFBS peaks by taking promoters and enhancers as backgrounds. We use a loose cutoff for adjusted p-values (0.1) because more GO terms will give a better clustering.

sig_lt2 = lapply(res_list[1:2], function(x) {
    tb = getEnrichmentTable(x)
    tb$id[tb$p_adjust < 0.1]
})
simplifyGOFromMultipleLists(sig_lt2)

Session info

## R version 4.3.1 (2023-06-16)
## Platform: x86_64-apple-darwin20 (64-bit)
## Running under: macOS Ventura 13.2.1
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
## 
## locale:
## [1] C/UTF-8/C/C/C/C
## 
## time zone: Europe/Berlin
## tzcode source: internal
## 
## attached base packages:
## [1] grid      stats4    stats     graphics  grDevices utils     datasets 
## [8] methods   base     
## 
## other attached packages:
## [1] simplifyEnrichment_1.11.1 eulerr_7.0.0             
## [3] rGREAT_2.5.4              GenomicRanges_1.52.1     
## [5] GenomeInfoDb_1.36.4       IRanges_2.36.0           
## [7] S4Vectors_0.40.2          BiocGenerics_0.48.1      
## [9] knitr_1.44               
## 
## loaded via a namespace (and not attached):
##   [1] RColorBrewer_1.1-3                      
##   [2] jsonlite_1.8.8                          
##   [3] shape_1.4.6                             
##   [4] magrittr_2.0.3                          
##   [5] magick_2.8.0                            
##   [6] GenomicFeatures_1.52.2                  
##   [7] rmarkdown_2.25                          
##   [8] GlobalOptions_0.1.2                     
##   [9] fs_1.6.3                                
##  [10] BiocIO_1.10.0                           
##  [11] zlibbioc_1.46.0                         
##  [12] ragg_1.2.6                              
##  [13] vctrs_0.6.4                             
##  [14] Cairo_1.6-2                             
##  [15] memoise_2.0.1                           
##  [16] Rsamtools_2.16.0                        
##  [17] RCurl_1.98-1.12                         
##  [18] htmltools_0.5.7                         
##  [19] S4Arrays_1.0.6                          
##  [20] TxDb.Hsapiens.UCSC.hg19.knownGene_3.2.2 
##  [21] progress_1.2.2                          
##  [22] curl_5.1.0                              
##  [23] sass_0.4.8                              
##  [24] bslib_0.6.1                             
##  [25] htmlwidgets_1.6.2                       
##  [26] desc_1.4.2                              
##  [27] cachem_1.0.8                            
##  [28] GenomicAlignments_1.36.0                
##  [29] mime_0.12                               
##  [30] lifecycle_1.0.4                         
##  [31] iterators_1.0.14                        
##  [32] pkgconfig_2.0.3                         
##  [33] Matrix_1.6-1.1                          
##  [34] R6_2.5.1                                
##  [35] fastmap_1.1.1                           
##  [36] GenomeInfoDbData_1.2.10                 
##  [37] MatrixGenerics_1.12.3                   
##  [38] shiny_1.8.0                             
##  [39] clue_0.3-65                             
##  [40] digest_0.6.33                           
##  [41] colorspace_2.1-0                        
##  [42] AnnotationDbi_1.62.2                    
##  [43] rprojroot_2.0.3                         
##  [44] textshaping_0.3.7                       
##  [45] RSQLite_2.3.1                           
##  [46] org.Hs.eg.db_3.17.0                     
##  [47] filelock_1.0.2                          
##  [48] fansi_1.0.5                             
##  [49] httr_1.4.7                              
##  [50] polyclip_1.10-6                         
##  [51] abind_1.4-5                             
##  [52] compiler_4.3.1                          
##  [53] bit64_4.0.5                             
##  [54] doParallel_1.0.17                       
##  [55] BiocParallel_1.34.2                     
##  [56] DBI_1.1.3                               
##  [57] biomaRt_2.56.1                          
##  [58] rappdirs_0.3.3                          
##  [59] proxyC_0.3.3                            
##  [60] DelayedArray_0.26.7                     
##  [61] rjson_0.2.21                            
##  [62] tools_4.3.1                             
##  [63] httpuv_1.6.13                           
##  [64] glue_1.6.2                              
##  [65] restfulr_0.0.15                         
##  [66] GOSemSim_2.26.1                         
##  [67] promises_1.2.1                          
##  [68] polylabelr_0.2.0                        
##  [69] cluster_2.1.4                           
##  [70] generics_0.1.3                          
##  [71] hms_1.1.3                               
##  [72] xml2_1.3.6                              
##  [73] utf8_1.2.3                              
##  [74] XVector_0.40.0                          
##  [75] foreach_1.5.2                           
##  [76] pillar_1.9.0                            
##  [77] stringr_1.5.0                           
##  [78] later_1.3.2                             
##  [79] circlize_0.4.15                         
##  [80] dplyr_1.1.3                             
##  [81] BiocFileCache_2.8.0                     
##  [82] lattice_0.21-9                          
##  [83] rtracklayer_1.60.1                      
##  [84] bit_4.0.5                               
##  [85] tidyselect_1.2.0                        
##  [86] GO.db_3.17.0                            
##  [87] ComplexHeatmap_2.18.0                   
##  [88] tm_0.7-11                               
##  [89] Biostrings_2.68.1                       
##  [90] NLP_0.2-1                               
##  [91] SummarizedExperiment_1.30.2             
##  [92] xfun_0.40                               
##  [93] Biobase_2.60.0                          
##  [94] matrixStats_1.2.0                       
##  [95] DT_0.30                                 
##  [96] stringi_1.7.12                          
##  [97] yaml_2.3.7                              
##  [98] TxDb.Hsapiens.UCSC.hg38.knownGene_3.17.0
##  [99] evaluate_0.22                           
## [100] codetools_0.2-19                        
## [101] tibble_3.2.1                            
## [102] cli_3.6.2                               
## [103] RcppParallel_5.1.7                      
## [104] xtable_1.8-4                            
## [105] systemfonts_1.0.5                       
## [106] jquerylib_0.1.4                         
## [107] Rcpp_1.0.11                             
## [108] dbplyr_2.3.4                            
## [109] png_0.1-8                               
## [110] XML_3.99-0.14                           
## [111] parallel_4.3.1                          
## [112] ellipsis_0.3.2                          
## [113] pkgdown_2.0.7                           
## [114] blob_1.2.4                              
## [115] prettyunits_1.2.0                       
## [116] bitops_1.0-7                            
## [117] slam_0.1-50                             
## [118] purrr_1.0.2                             
## [119] crayon_1.5.2                            
## [120] GetoptLong_1.0.5                        
## [121] rlang_1.1.2                             
## [122] KEGGREST_1.40.1