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.
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:
overlapsAny(ccres, ra) tells you which cCREs contain an RA
hit. Add it as a column, then group_by(class) and
summarize().)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.