PART1: Comparing sets of genomic regions with regioneR

Prepare the data. The Encyclopedia Of DNA Elements (ENCODE) consortium has compiled a registry of candidate cis-regulatory elements (cCREs) and classified them in many human cell types. These are available for download here. Download the full registry of human cCREs (GRCh38-cCREs.bed), then pick two cell types that interest you and download their bed files. Put all three files in this folder.

To analyze these sets of genomic regions, we’ll need regioneR, GenomicRanges, and the human genome hg38 packages. We’ll also use tidyverse for data wrangling, and set a random seed.

# Install packages if needed
if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

for (pkg in c("regioneR", "GenomicRanges", "BSgenome.Hsapiens.UCSC.hg38.masked")) {
  if (!requireNamespace(pkg, quietly = TRUE))
    BiocManager::install(pkg, ask = FALSE, update = FALSE)
}
if (!requireNamespace("tidyverse", quietly = TRUE))
  install.packages("tidyverse", repos = "https://cloud.r-project.org")

# Load packages
library(regioneR)
library(GenomicRanges)
library(tidyverse)

set.seed(10)

Look at the first few lines of one of your cell type bed files. What does each column contain?

all_file <- "GRCh38-cCREs.bed"
celltype_a_file <- "liver.noccl.cCREs.bed"
celltype_b_file <- "blood.noccl.cCREs.bed"
read_tsv(celltype_a_file, col_names = FALSE, n_max = 5)
## # A tibble: 5 × 11
##   X1       X2    X3 X4              X5 X6       X7    X8        X9 X10     X11  
##   <chr> <dbl> <dbl> <chr>        <dbl> <chr> <dbl> <dbl>     <dbl> <chr>   <chr>
## 1 chr1  10033 10250 EH38E2776516     0 .     10033 10250 225225225 Low-DN… Aggr…
## 2 chr1  10385 10713 EH38E2776517     0 .     10385 10713 225225225 Low-DN… Aggr…
## 3 chr1  16097 16381 EH38E3951272     0 .     16097 16381 225225225 Low-DN… Aggr…
## 4 chr1  17343 17642 EH38E3951273     0 .     17343 17642 225225225 Low-DN… Aggr…
## 5 chr1  29320 29517 EH38E3951274     0 .     29320 29517 225225225 Low-DN… Aggr…
Columns 1–3 are the chromosome, start, and end (BED starts are 0-based). Column 4 is the cCRE ID, column 10 is its class in this cell type (e.g. PLS, pELS, dELS, Low-DNase), and the rest are display fields (score, strand, thick start/end, color) and the biosample.


cCREs are not all enhancers. Based on their chromatin signals (DNase, H3K4me3, H3K27ac, CTCF), each one is classified as promoter-like (PLS), proximal or distal enhancer-like (pELS, dELS), chromatin-accessible with H3K4me3, CTCF, or a TF (CA-H3K4me3, CA-CTCF, CA-TF), chromatin-accessible only (CA), TF-bound (TF), or inactive (Low-DNase). Each cell type file lists every cCRE in the registry with its class in that cell type.

We’ll keep only the enhancer-like cCREs (pELS and dELS) in each cell type and call these sets enhancersA and enhancersB. Keep in mind these are candidate enhancers predicted from chromatin signals, not validated ones. We’ll also load the full registry as all. For each file, we select only the columns we need and convert to GRanges’ 1-based indexing.

all <- read_tsv(all_file, col_names = FALSE) |>
  select(chrom = X1, start = X2, end = X3) |>
  mutate(start = start + 1) |>
  as.data.frame() |>
  toGRanges()

enhancersA <- read_tsv(celltype_a_file, col_names = FALSE) |>
  select(chrom = X1, start = X2, end = X3, class = X10) |>
  filter(class == "dELS" | class == "pELS") |>
  mutate(start = start + 1) |>
  select(chrom, start, end) |>
  as.data.frame() |>
  toGRanges()

enhancersB <- read_tsv(celltype_b_file, col_names = FALSE) |>
  select(chrom = X1, start = X2, end = X3, class = X10) |>
  filter(class == "dELS" | class == "pELS") |>
  mutate(start = start + 1) |>
  select(chrom, start, end) |>
  as.data.frame() |>
  toGRanges()


Q1. How many regions are in all? In enhancersA? In enhancersB?

length(all)
## [1] 2348854
length(enhancersA)
## [1] 76207
length(enhancersB)
## [1] 349133
2,348,854 cCREs total, 76,207 liver enhancers (enhancersA), 349,133 blood enhancers (enhancersB).


Q2. Are enhancersA and enhancersB subsets of all cCREs? Check how many of each set overlap a region in all.

numOverlaps(enhancersA, all, count.once=TRUE)
## [1] 76207
numOverlaps(enhancersB, all, count.once=TRUE)
## [1] 349133
Yes, every region in both sets is in all.


The next few questions explore the overlap of genomic regions in enhancersA and enhancersB.

Q3. How many regions overlap? How many regions are exactly identical?

numOverlaps(enhancersA, enhancersB, count.once=TRUE)
## [1] 48561
numOverlaps(enhancersB, enhancersA, count.once=TRUE)
## [1] 48561
sum(enhancersA %in% enhancersB)
## [1] 48561
48,561 overlap, and all of them are identical: both files come from the same cCRE registry.


Now we are interested in testing whether enhancers from these two contexts overlap more than expected. We will explore two different ways of defining a null distribution for this overlap. First, we will select random regions of the genome that match the enhancersA set’s length distribution and compute their overlap with enhancersB. Then we will randomly sample from all cCREs and evaluate their overlap with enhancersB.

Q4. Generate a set of random genomic regions of the same size as enhancersA. Match these to the mean and sd of the genomic length of the enhancersA regions.

mean(width(enhancersA))
## [1] 282.2833
sd(width(enhancersA))
## [1] 71.72962
random_enhancersA <- createRandomRegions(nregions=length(enhancersA), length.mean=mean(width(enhancersA)), length.sd=sd(width(enhancersA)), genome="hg38")
numOverlaps(random_enhancersA, enhancersB, count.once=TRUE)
## [1] 3905
Much less: 3,905 vs 48,561.


numOverlaps(random_enhancersA, all, count.once=TRUE) / length(random_enhancersA)
## [1] 0.3477371
About a third (35%).


pt = overlapPermTest(A=enhancersA, B=enhancersB, ntimes=100, genome="hg38")
pt
## $numOverlaps
## P-value: 0.0099009900990099
## Z-score: 569.1431
## Number of iterations: 100
## Alternative: greater
## Evaluation of the original region set: 48561
## Evaluation function: numOverlaps
## Randomization function: randomizeRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
plot(pt)

Expected ~4,670 overlaps vs 48,561 observed.


Rejected (p = 1/101).


1/(ntimes+1).


The z-score barely changes; more resamples only lower the minimum p-value.


Q5. Repeat Q4 switching the roles of enhancersA and enhancersB. Are conclusions similar?

pt2 = overlapPermTest(A=enhancersB, B=enhancersA, ntimes=25, genome="hg38")
## [1] "Note: The minimum p-value with only 25 permutations is 0.0384615384615385. You should consider increasing the number of permutations."
pt2
## $numOverlaps
## P-value: 0.0384615384615385
## Z-score: 629.1273
## Number of iterations: 25
## Alternative: greater
## Evaluation of the original region set: 48561
## Evaluation function: numOverlaps
## Randomization function: randomizeRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
Yes, still far above random (p = 1/26 with 25 permutations).


Q6. Create a random sample of cCREs from all, the same size as enhancersA.
- Do these random regions overlap enhancersB more or less than enhancersA does?
- How does this test differ from the one in Q4? Look at the z-score and p-value.

random_all = sample(all, length(enhancersA))
numOverlaps(random_all, enhancersB, count.once=TRUE)
## [1] 11206
pt_resample = permTest(A=enhancersA, B=enhancersB, ntimes=100, randomize.function=resampleRegions,
                   universe=all, evaluate.function=numOverlaps, count.once=TRUE)
pt_resample
## $numOverlaps
## P-value: 0.0099009900990099
## Z-score: 410.2878
## Number of iterations: 100
## Alternative: greater
## Evaluation of the original region set: 48561
## Evaluation function: numOverlaps
## Randomization function: resampleRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
More than random genome regions (~11,200 vs 3,905) but still far less than enhancersA. Same p-value, but the z-score is lower because the null is more realistic.


Q7. Repeat Q6 switching the role of enhancersA and enhancersB. Are conclusions similar?

pt_resample2 = permTest(A=enhancersB, B=enhancersA, ntimes=100, randomize.function=resampleRegions,
                    universe=all, evaluate.function=numOverlaps, count.once=TRUE)
pt_resample2
## $numOverlaps
## P-value: 0.0099009900990099
## Z-score: 427.5974
## Number of iterations: 100
## Alternative: greater
## Evaluation of the original region set: 48561
## Evaluation function: numOverlaps
## Randomization function: resampleRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
Yes, with a lower z-score than Q5.


When we generate random regions across the whole genome (Q4), we should exclude places where our regions of interest could never be found. This is called masking. By default, regioneR masks assembly gaps (unsequenced stretches of the reference genome), so random regions can’t land there.

Q8. Repeat the Q4 test without the mask (mask=NA). How do the expected overlap and z-score change? Should you mask?

pt_unmasked = overlapPermTest(A=enhancersA, B=enhancersB, ntimes=100, genome="hg38", mask=NA)
pt_unmasked
## $numOverlaps
## P-value: 0.0099009900990099
## Z-score: 592.8553
## Number of iterations: 100
## Alternative: greater
## Evaluation of the original region set: 48561
## Evaluation function: numOverlaps
## Randomization function: randomizeRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
mean(pt$numOverlaps$permuted)
## [1] 4663.83
mean(pt_unmasked$numOverlaps$permuted)
## [1] 4447.48
Without the mask, random regions land in gaps where no cCREs can exist, so the expected overlap drops (~4,450 vs ~4,670) and enrichment looks stronger than it is. The difference is small because gaps are only ~5% of the genome, but you should still mask.


Regions where reads map poorly or pile up artifactually (ENCODE blacklist: satellites, centromeres, telomeres), false duplications or contamination in the reference (GRC exclusions), and hard-to-align loci like the immune gene clusters. Real peaks can't be called reliably there, so random regions shouldn't land there either. Any of these can be passed as mask=.


Q9. Which null distribution would you use in your own research and why?

Resampling from all cCREs (Q6), since cCREs aren't randomly placed in the genome. Random genomic regions, even with a mask, fall in places where no cCRE could ever be, which makes any set of cCREs look enriched.



PART2: Multimodal analysis

The same tools work for any data with genomic coordinates: GWAS hits (like Lab 1), ChIP-seq or CUT&RUN peaks, ATAC-seq peaks, Hi-C contacts, SAMOSA, etc. Choose one of the two options below.

Option 1: Rheumatoid arthritis GWAS hits. We’ve provided the rheumatoid arthritis (RA) associations from the GWAS Catalog in this folder (MONDO_0008383_associations_export.tsv). Download cCREs from SCREEN for one cell type you think is involved in RA and one you think isn’t. Address the following:

We’ll keep genome-wide significant SNPs with a single location, and load all cCREs with their class.

gwas_file <- "MONDO_0008383_associations_export.tsv"
involved_file <- "blood.noccl.cCREs.bed"
control_file <- "liver.noccl.cCREs.bed"

ra <- read_tsv(gwas_file) |>
  filter(pValue < 5e-8, str_count(locations, ":") == 1) |>
  separate(locations, into = c("chrom", "pos"), sep = ":") |>
  mutate(chrom = paste0("chr", chrom), start = as.numeric(pos), end = start) |>
  distinct(chrom, start, end) |>
  as.data.frame() |>
  toGRanges()

read_ccres <- function(file) {
  read_tsv(file, col_names = FALSE) |>
    select(chrom = X1, start = X2, end = X3, class = X10) |>
    mutate(start = start + 1) |>
    as.data.frame() |>
    toGRanges()
}
involved <- read_ccres(involved_file)
control <- read_ccres(control_file)


blood_els <- involved[involved$class %in% c("dELS", "pELS")]
liver_els <- control[control$class %in% c("dELS", "pELS")]

overlapPermTest(A = ra, B = blood_els, ntimes = 100, genome = "hg38")
## $numOverlaps
## P-value: 0.0099009900990099
## Z-score: 28.4908
## Number of iterations: 100
## Alternative: greater
## Evaluation of the original region set: 298
## Evaluation function: numOverlaps
## Randomization function: randomizeRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
overlapPermTest(A = ra, B = liver_els, ntimes = 100, genome = "hg38")
## $numOverlaps
## P-value: 0.0099009900990099
## Z-score: 7.0716
## Number of iterations: 100
## Alternative: greater
## Evaluation of the original region set: 44
## Evaluation function: numOverlaps
## Randomization function: randomizeRegions
## 
## attr(,"class")
## [1] "permTestResultsList"
Both are significant, but blood has a much higher z-score. GWAS hits are enriched in regulatory DNA in general, so the comparison between cell types matters more than either p-value.


hits_per_class <- function(ccres) {
  as.data.frame(ccres) |>
    mutate(has_hit = overlapsAny(ccres, ra)) |>
    group_by(class) |>
    summarize(hits = sum(has_hit), mb = sum(width) / 1e6) |>
    mutate(hits_per_mb = hits / mb)
}

results <- bind_rows(blood = hits_per_class(involved), liver = hits_per_class(control), .id = "cell_type")
results |> arrange(desc(hits_per_mb))
## # A tibble: 16 × 5
##    cell_type class       hits       mb hits_per_mb
##    <chr>     <chr>      <int>    <dbl>       <dbl>
##  1 blood     PLS           38   9.10         4.18 
##  2 liver     PLS           24   6.82         3.52 
##  3 blood     pELS          89  25.9          3.44 
##  4 liver     CA-H3K4me3     4   1.45         2.76 
##  5 blood     dELS         169  68.3          2.47 
##  6 liver     pELS          22   9.14         2.41 
##  7 liver     dELS          21  12.4          1.70 
##  8 liver     CA-only        9   5.43         1.66 
##  9 blood     CA-only       18  17.3          1.04 
## 10 liver     Low-DNase    600 588.           1.02 
## 11 blood     CA-CTCF        7   7.31         0.958
## 12 blood     CA-TF          4   4.89         0.818
## 13 blood     CA-H3K4me3     5   6.85         0.730
## 14 blood     Low-DNase    352 488.           0.721
## 15 liver     CA-CTCF        2   4.24         0.472
## 16 liver     CA-TF          0   0.0837       0
ggplot(results, aes(x = class, y = hits_per_mb, fill = cell_type)) +
  geom_col(position = "dodge") +
  coord_flip()

Blood promoters (PLS) have the most hits per Mb, followed by liver promoters and blood enhancers (pELS). Blood beats liver for promoters and enhancers, as expected for an immune disease. Promoters are high in both because many are shared across tissues.


Option 2: Your own question. Come up with your own question that combines two kinds of genomic data, and answer it with the tools from this lab. State your hypothesis, run a test, and interpret the result.