1 derfinder basic results exploration

Project: derfinderReport-example.

2 Introduction

This report is meant to help explore the results of the derfinder (Collado-Torres, Nellore, Frazee, Wilks, Love, Langmead, Irizarry, Leek, and Jaffe, 2017) package using the single base-level approach and was generated using the regionReport (Collado-Torres, Jaffe, and Leek, 2016) package. While the report is rich, it is meant to just start the exploration of the results and exemplify some of the code used to do so. If you need a more in-depth analysis for your specific data set you might want to use the customCode argument.

Most plots were made with using ggplot2 (Wickham, 2016).

2.1 Code setup

## knitrBoostrap and device chunk options
library('knitr')
opts_chunk$set(bootstrap.show.code = FALSE, dev = device, crop = NULL)
if(!outputIsHTML) opts_chunk$set(bootstrap.show.code = FALSE, dev = device, echo = FALSE)

#### Libraries needed

## Bioconductor
library('IRanges')
library('GenomicRanges')
library('GenomeInfoDb')
library('derfinder')
library('derfinderPlot')
library('ggbio')

## Need specific help about ggbio? try mailing 
##  the maintainer or visit https://lawremi.github.io/ggbio/

## 
## Attaching package: 'ggbio'

## The following objects are masked from 'package:ggplot2':
## 
##     geom_bar, geom_rect, geom_segment, ggsave, stat_bin, stat_identity, xlim

if(hg19) {
    library('biovizBase')
    library('TxDb.Hsapiens.UCSC.hg19.knownGene')
}

## Loading required package: GenomicFeatures

## CRAN
library('ggplot2')
if(!is.null(theme)) theme_set(theme)
library('grid')
library('gridExtra')

## 
## Attaching package: 'gridExtra'

## The following object is masked from 'package:Biobase':
## 
##     combine

## The following object is masked from 'package:BiocGenerics':
## 
##     combine

library('knitr')
library('RColorBrewer')
library('mgcv')

## Loading required package: nlme

## 
## Attaching package: 'nlme'

## The following object is masked from 'package:IRanges':
## 
##     collapse

## This is mgcv 1.9-1. For overview type 'help("mgcv-package")'.

library('DT')
library('sessioninfo')

#### Code setup

## For ggplot
tmp <- fullRegions
names(tmp) <- seq_len(length(tmp))
regions.df <- as.data.frame(tmp)
regions.df$width <- width(tmp)
rm(tmp)
nulls.df <- as.data.frame(fullNullSummary)

## Special subsets: need at least 3 points for a density plot
keepChr <- table(regions.df$seqnames) > 2
regions.df.plot <- subset(regions.df, seqnames %in% names(keepChr[keepChr]))
finite.area <- finite.area[regions.df$seqnames %in% names(keepChr[keepChr])]

if(hasSig) {
    ## Keep only those sig
    regions.df.sig <- regions.df[idx.sig, ]
    keepChr <- table(regions.df.sig$seqnames) > 2
    regions.df.sig <- subset(regions.df.sig, seqnames %in% names(keepChr[keepChr]))
    
    if(nrow(regions.df.sig) > 0) {
        ## If there's any sig, keep those with finite areas
        if(hasArea) {
            regions.df.sig.area <- regions.df.sig[is.finite(regions.df.sig$area), ]
            keepChr <- table(regions.df.sig.area$seqnames) > 2
            regions.df.sig.area <- subset(regions.df.sig.area, seqnames %in%
                names(keepChr[keepChr]))
            
            ## Save the info
            hasArea <- nrow(regions.df.sig.area) > 0
        }
    } else {
        print('Not a single chromosome had 2 or more significant regions, so plots for significant regions will be skipped.')
        hasSig <- hasArea <- FALSE
    }
}

## Get chr lengths
if(hg19) {
    seqlengths(fullRegions) <- seqlengths(getChromInfoFromUCSC('hg19',
        as.Seqinfo = TRUE))[
          mapSeqlevels(names(seqlengths(fullRegions)), 'UCSC')]
}

## Find which chrs are present in the data set
chrs <- levels(seqnames(fullRegions))

## Subset the fullCoverage data in case that a subset was used
colsubset <- optionsStats$colsubset
if(!is.null(fullCov) & !is.null(colsubset)) {
    fullCov <- lapply(fullCov, function(x) { x[, colsubset] })
}

## Get region coverage for the top regions
if(nBestRegions > 0) {
    regionCoverage <- getRegionCoverage(fullCov = fullCov, 
        regions = fullRegions[seq_len(nBestRegions)],
        chrsStyle = chrsStyle, species = species,
        currentStyle = currentStyle, verbose = FALSE)
    save(regionCoverage, file=file.path(workingDir, 'regionCoverage.Rdata'))
}

## Graphical setup: transcription database
if(hg19 & is.null(txdb)) {
    txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene::TxDb.Hsapiens.UCSC.hg19.knownGene
} else {
    stopifnot(!is.null(txdb))
}

3 Quality checks

3.1 P-values

Theoretically, the p-values should be uniformly distributed between 0 and 1.

p1 <- ggplot(regions.df.plot, aes(x=pvalues, colour=seqnames)) +
    geom_line(stat='density') + xlim(0, 1) +
    labs(title='Density of p-values') + xlab('p-values') +
    scale_colour_discrete(limits=chrs) + theme(legend.title=element_blank())
p1

## Compare the pvalues
summary(fullRegions$pvalues)

##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
## 0.01887 0.01887 0.62264 0.40652 0.62264 0.96226

This is the numerical summary of the distribution of the p-values.

3.2 Q-values

summary(fullRegions$qvalues)

##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
## 0.01626 0.01626 0.25005 0.16318 0.25005 0.30161

This is the numerical summary of the distribution of the q-values.

qtable <- lapply(c(1e-04, 0.001, 0.01, 0.025, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5,
    0.6, 0.7, 0.8, 0.9, 1), function(x) {
    data.frame('Cut' = x, 'Count' = sum(fullRegions$qvalues <= x))
})
qtable <- do.call(rbind, qtable)
if(outputIsHTML) {
    kable(qtable, format = 'markdown', align = c('c', 'c'))
} else {
    kable(qtable)
}

Cut	Count
0.0001	0
0.0010	0
0.0100	0
0.0250	12
0.0500	12
0.1000	12
0.2000	13
0.3000	32
0.4000	33
0.5000	33
0.6000	33
0.7000	33
0.8000	33
0.9000	33
1.0000	33

This table shows the number of candidate Differentially Expressed Regions (DERs) with q-value less or equal than some commonly used cutoff values.

3.3 FWER adjusted P-values

This is the numerical summary of the distribution of the FWER adjusted p-values. Skipped because there are no FWER-adjusted P-values.

This table shows the number of candidate Differentially Expressed Regions (DERs) with FWER adjusted p-values less or equal than some commonly used cutoff values. Skipped because there are no FWER-adjusted P-values.

3.4 Region width

xrange <- range(log10(regions.df.plot$width)) * c(0.95, 1.05)
p2a <- ggplot(regions.df.plot, aes(x=log10(width), colour=seqnames)) + 
    geom_line(stat='density') + labs(title='Density of region lengths') +
    xlab('Region width (log10)') + scale_colour_discrete(limits=chrs) +
    xlim(xrange) + theme(legend.title=element_blank())
p2b <- ggplot(regions.df.sig, aes(x=log10(width), colour=seqnames)) +
    geom_line(stat='density') +
    labs(title='Density of region lengths (significant only)') +
    xlab('Region width (log10)') + scale_colour_discrete(limits=chrs) +
    xlim(xrange) + theme(legend.title=element_blank())
grid.arrange(p2a, p2b)

This plot shows the density of the region lengths for all regions. The bottom panel is restricted to significant regions (FDR adjusted P-value < 0.1)

3.5 Region Area

xrange <- range(log10(regions.df.plot$area[finite.area])) * c(0.95, 1.05)
if(inf.area > 0) {
    print(paste('Dropping', inf.area, 'due to Inf values.'))
}
p3a <- ggplot(regions.df.plot[finite.area, ], aes(x=log10(area), colour=seqnames)) +
    geom_line(stat='density') + labs(title='Density of region areas') +
    xlab('Region area (log10)') + scale_colour_discrete(limits=chrs) +
    xlim(xrange) + theme(legend.title=element_blank())
p3b <- ggplot(regions.df.sig.area, aes(x=log10(area), colour=seqnames)) +
    geom_line(stat='density') +
    labs(title='Density of region areas (significant only)') +
    xlab('Region area (log10)') + scale_colour_discrete(limits=chrs) +
    xlim(xrange) + theme(legend.title=element_blank())
grid.arrange(p3a, p3b)

This plot shows the density of the region areas for all regions. The bottom panel is restricted to significant regions (FDR adjusted P-value < 0.1)

3.6 Null regions: width and area

p4 <- ggplot(nulls.df, aes(x=log10(width), colour=chr)) +
    geom_line(stat='density') + labs(title='Density of null region lengths') +
    xlab('Region width (log10)') + scale_colour_discrete(limits=chrs) +
    theme(legend.title=element_blank())
nulls.inf <- !is.finite(nulls.df$area)
if(sum(nulls.inf) > 0) {
    print(paste('Dropping', sum(nulls.inf), 'due to Inf values.'))
}
p5 <- ggplot(nulls.df[!nulls.inf, ], aes(x=log10(area), colour=chr)) +
    geom_line(stat='density') + labs(title='Density of null region areas') +
    xlab('Region area (log10)') + scale_colour_discrete(limits=chrs) +
    theme(legend.title=element_blank())
grid.arrange(p4, p5)

This plot shows the density of the null region lengths and areas. There were a total of 52 null regions.

3.7 Mean coverage

xrange <- range(log2(regions.df.plot$meanCoverage)) * c(0.95, 1.05)
p6a <- ggplot(regions.df.plot, aes(x=log2(meanCoverage), colour=seqnames)) +
    geom_line(stat='density') + labs(title='Density of region mean coverage') +
    xlab('Region mean coverage (log2)') + scale_colour_discrete(limits=chrs) +
    xlim(xrange) + theme(legend.title=element_blank())
p6b <- ggplot(regions.df.sig, aes(x=log2(meanCoverage), colour=seqnames)) +
    geom_line(stat='density') +
    labs(title='Density of region mean coverage (significant only)') +
    xlab('Region mean coverage (log2)') + scale_colour_discrete(limits=chrs) +
    xlim(xrange) + theme(legend.title=element_blank())
grid.arrange(p6a, p6b)

This plot shows the density of the region mean coverage for all regions. The bottom panel is restricted to significant regions (FDR adjusted P-value < 0.1)

3.8 Mean coverage vs fold change

The following plots are MA-style plots comparing each group vs the first one. The mean coverage is calculated using only two groups at a time and is weighted according to the number of samples on each group. Note that the mean coverage and fold change as calculated here do not taking into account the library sizes.

These plots are only shown when there are two or more groups. A total of 1 plot(s) were made.

for(j in grep('log2FoldChange', colnames(values(fullRegions)))) {
    ## Identify the groups
    groups <- strsplit(gsub('log2FoldChange', '',
        colnames(values(fullRegions))[j]), 'vs')[[1]]
    
    ## Calculate the mean coverage only using the 2 groups in question
    j.mean <- which(colnames(values(fullRegions)) %in% paste0('mean', groups))
    groups.n <- sapply(groups, function(x) { sum(optionsStats$groupInfo == x) })
    ma.mean.mat <- as.matrix(values(fullRegions)[, j.mean])
    ## Weighted means
    ma.mean <- drop(ma.mean.mat %*% groups.n) / sum(groups.n) +
        optionsStats$scalefac
    ma.fold2 <- drop(log2(ma.mean.mat + optionsStats$scalefac) %*% c(1, -1))
    
    ma <- data.frame(mean=ma.mean, log2FoldChange=ma.fold2)
    ma2 <- ma[is.finite(ma$log2FoldChange), ]
    fold.mean <- data.frame(foldMean=mean(ma2$log2FoldChange, na.rm=TRUE))
    
    p.ma <- ggplot(ma, aes(x=log2(mean), y=log2FoldChange)) +
        geom_point(size=1.5, alpha=1/5) + 
        ylab("Fold Change [log2(x + sf)]\nRed dashed line at mean; blue line is GAM fit: y ~ s(x, bs = 'cs')") +
        xlab(paste('Mean coverage [log2(x + sf)] using only groups', groups[1], 'and',
            groups[2])) + labs(title=paste('MA style plot:', groups[1], 'vs ', 
            groups[2])) + geom_hline(aes(yintercept=foldMean), data=fold.mean, 
            colour='#990000', linetype='dashed') +
        geom_smooth(aes(y=log2FoldChange, x=log2(mean)), data=subset(ma2,
            mean > 0), method = 'gam', formula = y ~ s(x, bs = 'cs'))
    print(p.ma)
}

4 Genomic overview

The following plots were made using ggbio (Yin, Cook, and Lawrence, 2012) which in turn uses ggplot2 (Wickham, 2016). For more details check plotOverview in derfinder (Collado-Torres, Nellore, Frazee et al., 2017).

4.1 FDR adjusted P-value

plotOverview(regions=fullRegions, type=pvalVar, base_size=overviewParams$base_size, areaRel=overviewParams$areaRel, legend.position=c(0.97, 0.12))

This plot shows the genomic locations of the candidate regions found in the analysis. The significant regions (FDR adjusted P-value less than 0.1) are highlighted and the area of the regions is shown on top of each chromosome. Note that the area is in a relative scale.

4.2 Annotation

plotOverview(regions=fullRegions, annotation=fullRegions, type='annotation', base_size=overviewParams$base_size, areaRel=overviewParams$areaRel, legend.position=c(0.97, 0.12))

This genomic overview plot shows the annotation region type for the candidate regions. Note that the regions are shown only if the annotation information is available. Below is a table of the actual number of results per annotation region type.

annoReg <- table(fullRegions$region, useNA='always')
annoReg.df <- data.frame(Region=names(annoReg), Count=as.vector(annoReg))
if(outputIsHTML) {
    kable(annoReg.df, format = 'markdown', align=rep('c', 3))
} else {
    kable(annoReg.df)
}

Region	Count
upstream	0
promoter	0
overlaps 5’	0
inside	33
overlaps 3’	0
close to 3’	0
downstream	0
covers	0
NA	0

4.3 Annotation (significant)

plotOverview(regions=fullRegions[idx.sig], annotation=fullRegions[idx.sig], type='annotation', base_size=overviewParams$base_size, areaRel=overviewParams$areaRel, legend.position=c(0.97, 0.12))

This genomic overview plot shows the annotation region type for the candidate regions that have a FDR adjusted P-valueless than 0.1. Note that the regions are shown only if the annotation information is available.

5 Best regions

5.1 Plots

Below are the plots for the top 15 candidate DERs as ranked by area. For each plot, annotation is shown if the candidate DER has a minimum overlap of 20 base pairs with annotation information (strand specific). If present, exons are collapsed and shown in blue. Introns are shown in light blue. The title of each plot is composed of the name of the nearest annotation element, the distance to it, and whether the region of the genome the DER falls into; all three pieces of information are based on bumphunter::matchGenes().

The annotation depends on the Genomic State used. For details on which one was used for this report check the call to mergeResults in the reproducibility details.

if(nBestRegions > 0) {
    plotRegionCoverage(regions = fullRegions, regionCoverage = regionCoverage,
        groupInfo = optionsStats$groupInfo, nearestAnnotation = regions.df,
        annotatedRegions = fullAnnotatedRegions, 
        whichRegions = seq_len(min(nBestRegions, length(fullRegions))),
        colors = NULL, scalefac = optionsStats$scalefac, ask = FALSE, 
        verbose = TRUE, txdb = txdb) 
}

## 2025-01-14 16:27:26.590254 plotRegionCoverage: extracting Tx info

## 2025-01-14 16:27:29.120173 plotRegionCoverage: getting Tx plot info

5.2 Genomic states

Below is a table summarizing the number of genomic states per region.

info <- do.call(rbind, lapply(fullAnnotatedRegions$countTable, function(x) { data.frame(table(x)) }))
colnames(info) <- c('Number of Overlapping States', 'Frequency')
info$State <- gsub('\\..*', '', rownames(info))
rownames(info) <- NULL
if(outputIsHTML) {
    kable(info, format = 'markdown', align=rep('c', 4))
} else {
    kable(info)
}

Number of Overlapping States	Frequency	State
0	22	exon
1	11	exon
0	33	intergenic
0	30	intron
1	3	intron

The following is a venn diagram showing how many regions overlap known exons, introns, and intergenic segments, none of them, or multiple of these groups.

## Venn diagram for all regions
venn <- vennRegions(fullAnnotatedRegions, counts.col = 'blue', 
    main = 'Regions overlapping genomic states')

The following plot is the genomic states venn diagram only for the significant regions.

## Venn diagram for all regions
vennSig <- vennRegions(fullAnnotatedRegions, counts.col = 'blue', 
    main = 'Significant regions overlapping genomic states',
    subsetIndex = idx.sig)