1 Introduction

As transcription factors (TFs) play a crucial role in regulating the transcription process through binding on the genome alone or in a combinatorial manner, TF enrichment analysis is an efficient and important procedure to locate the candidate functional TFs from a set of experimentally defined regulatory regions. While it is commonly accepted that structurally related TFs may have similar binding preference to sequences (i.e. motifs) and one TF may have multiple motifs, TF enrichment analysis is much more challenging than motif enrichment analysis. Here we present a R package for TF enrichment analysis which combine motif enrichment with the PECA model.

2 Quick Start

2.1 Download and Installation

The package enrichTF is part of Bioconductor project starting from Bioc 3.9 built on R 3.6. To install the latest version of enrichTF, please check your current Bioconductor version and R version first. The latest version of R is recommended, and then you can download and install enrichTF and all its dependencies as follows:

if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("enrichTF")

2.2 Loading

Similar with other R packages, please load enrichTF each time before using the package.

library(enrichTF)

2.3 Running with the default configuration

It is quite convenient to run the default pipeline.

Users only need to provide a region list in BED format which contains 3 columns (chr, start, end). It could be the peak calling result of sequencing data like ATAC-seq etc.

All required data and software will be installed automatically.

# Provide your region list in BED format with 3 columns.
foregroundBedPath <- system.file(package = "enrichTF", "extdata","testregion.bed")
# Call the whole pipeline
PECA_TF_enrich(inputForegroundBed = foregroundBedPath, genome = "testgenome") # change"testgenome" to one of "hg19", "hg38", "mm9", 'mm10' ! "testgenome" is only a test example.

## Configure bsgenome ...

## 
## Attaching package: 'BiocGenerics'

## The following objects are masked from 'package:parallel':
## 
##     clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
##     clusterExport, clusterMap, parApply, parCapply, parLapply,
##     parLapplyLB, parRapply, parSapply, parSapplyLB

## The following objects are masked from 'package:stats':
## 
##     IQR, mad, sd, var, xtabs

## The following objects are masked from 'package:base':
## 
##     Filter, Find, Map, Position, Reduce, anyDuplicated, append,
##     as.data.frame, basename, cbind, colnames, dirname, do.call,
##     duplicated, eval, evalq, get, grep, grepl, intersect, is.unsorted,
##     lapply, mapply, match, mget, order, paste, pmax, pmax.int, pmin,
##     pmin.int, rank, rbind, rownames, sapply, setdiff, sort, table,
##     tapply, union, unique, unsplit, which, which.max, which.min

## 
## Attaching package: 'S4Vectors'

## The following object is masked from 'package:base':
## 
##     expand.grid

## 
## Attaching package: 'Biostrings'

## The following object is masked from 'package:base':
## 
##     strsplit

## Configure bsgenome finished

## Configure motifpwm ...

## Configure motifpwm finished

## Configure motifPWMOBJ ...

## Configure motifPWMOBJ finished

## Configure RE_gene_corr ...

## Configure RE_gene_corr finished

## Configure Enhancer_RE_gene_corr ...

## Configure Enhancer_RE_gene_corr finished

## Configure MotifTFTable ...

## Configure MotifTFTable finished

## Configure MotifWeights ...

## Configure MotifWeights finished

## Configure TFgeneRelMtx ...

## Configure TFgeneRelMtx finished

## Configure SampleName ...

## Configure SampleName finished

## Configure OpenRegion ...

## Configure OpenRegion finished

## Configure ConserveRegion ...

## Configure ConserveRegion finished

## Configure HOMER ...

## Configure HOMER finished

## Configure OrgDb ...

## Loading required package: AnnotationDbi

## Loading required package: Biobase

## Welcome to Bioconductor
## 
##     Vignettes contain introductory material; view with
##     'browseVignettes()'. To cite Bioconductor, see
##     'citation("Biobase")', and for packages 'citation("pkgname")'.

##

## Configure OrgDb finished

## >>>>>>==========================================================

## Step Name:pipe_UnzipAndMergeBed

## All Parameters for This Step:

## |Input:

## |    bedInput:

## |        "/tmp/Rtmpawr6mV/Rinst46f9297fd120/enrichTF/extdata/testregion.bed"

## |Output:

## |    bedOutput:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_00_pipe_UnzipAndMergeBed/testregion.bed"

## |Other Parameters:

## __________________________________________

## Begin to check if it is finished...

## 2020-04-28 00:06:32

## New step. Start processing data:

## processing file:

## source:/tmp/Rtmpawr6mV/Rinst46f9297fd120/enrichTF/extdata/testregion.bed

## destination:/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_00_pipe_UnzipAndMergeBed/testregion.bed

## 2020-04-28 00:06:32

## processing finished

## [1] "2020-04-28 00:06:32 EDT"
## [1] "2020-04-28 00:06:32 EDT"
## [1] "2020-04-28 00:06:32 EDT"
## [1] "2020-04-28 00:06:32 EDT"
## [1] "2020-04-28 00:06:32 EDT"
## [1] "2020-04-28 00:06:32 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

## >>>>>>==========================================================

## Step Name:pipe_GenBackground

## All Parameters for This Step:

## |Input:

## |    inputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_00_pipe_UnzipAndMergeBed/testregion.bed"

## |Output:

## |    outputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.foreground.bed"

## |    outputBackgroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.background.bed"

## |    outputRegionBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.allregion.bed"

## |Other Parameters:

## |    bsgenome:

## |        An object of BSgenome

## |    regionLen:

## |        1000

## |    sampleNumb:

## |        0

## __________________________________________

## Begin to check if it is finished...

## 2020-04-28 00:06:32

## New step. Start processing data:

## 2020-04-28 00:06:33

## processing finished

## [1] "2020-04-28 00:06:33 EDT"
## [1] "2020-04-28 00:06:33 EDT"
## [1] "2020-04-28 00:06:33 EDT"
## [1] "2020-04-28 00:06:33 EDT"
## [1] "2020-04-28 00:06:33 EDT"
## [1] "2020-04-28 00:06:33 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

## >>>>>>==========================================================

## Step Name:pipe_RegionConnectTargetGene

## All Parameters for This Step:

## |Input:

## |    inputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.foreground.bed"

## |    inputBackgroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.background.bed"

## |Output:

## |    outputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.foreground.bed"

## |    ouputForgroundGeneTxt:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.foreground.txt"

## |    outputBackgroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.background.bed"

## |    regularGeneCorrBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/RE_gene_corr.bed"

## |    enhancerRegularGeneCorrBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/Enhancer_RE_gene_corr.bed"

## |Other Parameters:

## __________________________________________

## Begin to check if it is finished...

## 2020-04-28 00:06:33

## New step. Start processing data:

## 2020-04-28 00:06:34

## processing finished

## [1] "2020-04-28 00:06:34 EDT"
## [1] "2020-04-28 00:06:34 EDT"
## [1] "2020-04-28 00:06:34 EDT"
## [1] "2020-04-28 00:06:34 EDT"
## [1] "2020-04-28 00:06:34 EDT"
## [1] "2020-04-28 00:06:34 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

## >>>>>>==========================================================

## Step Name:pipe_FindMotifsInRegions

## All Parameters for This Step:

## |Input:

## |    inputRegionBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.allregion.bed"

## |Output:

## |    outputRegionMotifBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_03_pipe_FindMotifsInRegions/testregion.region.motif.bed"

## |    outputMotifBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_03_pipe_FindMotifsInRegions/testregion.motif.bed"

## |Other Parameters:

## |    motifRc:

## |        "integrate"

## |    pwmObj:

## |        An object of PWMatrixList

## |    genome:

## |        "hg19"

## |    threads:

## |        2

## __________________________________________

## Begin to check if it is finished...

## 2020-04-28 00:06:34

## New step. Start processing data:

## 2020-04-28 00:06:35

## processing finished

## [1] "2020-04-28 00:06:35 EDT"
## [1] "2020-04-28 00:06:35 EDT"
## [1] "2020-04-28 00:06:35 EDT"
## [1] "2020-04-28 00:06:35 EDT"
## [1] "2020-04-28 00:06:35 EDT"
## [1] "2020-04-28 00:06:35 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

## >>>>>>==========================================================

## Step Name:pipe_TFsEnrichInRegions

## All Parameters for This Step:

## |Input:

## |    inputRegionBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.allregion.bed"

## |    inputRegionMotifBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_03_pipe_FindMotifsInRegions/testregion.region.motif.bed"

## |    inputForegroundGeneBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.foreground.bed"

## |    inputBackgroundGeneBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.background.bed"

## |    inputMotifWeights:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/MotifWeights.RData"

## |    inputTFgeneRelMtx:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/TFgeneRelMtx.RData"

## |    inputMotifTFTable:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/MotifTFTable.RData"

## |Output:

## |    outputTFsEnrichTxt:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_04_pipe_TFsEnrichInRegions/testregion.PECA_TF_enrich.txt"

## |Other Parameters:

## __________________________________________

## Begin to check if it is finished...

## 2020-04-28 00:06:35

## New step. Start processing data:

## 2020-04-28 00:06:50

## processing finished

## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

3 How TF Enrichment Works

3.1 Basic Concept for Relations

In this work, we define four kinds of relations which will be introduced in detail. And we will show how to test on enriched TFs rather than enriched motifs.

3.1.1 Region-gene Relation Table

When users input a region list in BED format, the relations between regions and one gene can be obtained from two ways:

The regions which are overlapped with the functional region of this gene. This type of relation can be obtained from gene reference data.
The regions are enhancers or other distal regulatory elements of this gene. This type of relation can be derived from 3D genome sequencing experiments such as Hi-C and HiChIP.

As we have already integrated and organized the potential relations between regions and genes from both gene reference and experiment profiles, users can use this source to obtain region-gene relations for their input region list quite easily.

Moreover, users can also customize potential relations from their own work.

3.1.2 Gene-TF Relation Matrix

The correlation scores between genes and TFs come from our previous approach named PECA. These scores are scaled in the range [-1,1]. Users can also customize this relation matrix based on their own experiment data.

3.1.3 TF-motif Relation Table

As we know, one TF may relate to multiple motifs. Here, we manually annotated more than 700 motifs with their corresponding TFs.

3.1.4 Motif-region Relation Table

We scan all annotated motifs on each input region to check if there are some motifs located in this region. Then, the motif-region relation table can be generated.

3.2 Enrichment Test

Based on the foreground region list from users, this package can randomly sample the same number of regions from genome as background.

3.2.1 Enrichment t-test

Foreground and background region lists can both be connected with genes in Region-gene Relation Table, so both of them will get a gene list. We name them as the foreground gene list and background gene list, respectively.

For each TF, we will perform t-test and obtain p-values for TF-Gene scores of foreground vs those of background. These scores come from Gene-TF Relation Matrix.

3.2.2 Enrichment Fisher’s exact test without threshold

Each TF may be correlated with multiple motifs. For each motif, this package will do the following Fisher’s exact test to test if one motif is enriched in foreground regions.

	# with TF’s motif	# without TF’s motif
# Foreground regions
# Background regions

Finally, the package will select the motif with the most significant p-value to represent this TF and then compute p-values for all of the TFs.

3.2.3 Enrichment Fisher’s exact test with threshold

Similar to previous section, the package will perform Fisher’s exact test with TF-Gene relation matrix. Different thresholds ([-1,1] with interval 0.1) for TF-Gene relation scores are used to filter the connected genes with foreground and background. In this way, we select the most significant p-value to represent this TF and calculate the p-values for all of TFs.

3.2.4 FDR

Finally, false discover rate correction is applied on the results of Fisher’s exact test with threshold. We rank all of the TFs based on their enrichment significance.

4 Customized Workflow

There are 4 steps to customize the workflow. You can follow the order below:

printMap()

4.1 Prepare inputs

The function of genBackground is to generate random background regions based on the input regions and to set the length of input sequence regions. We try to select background sequence regions that match the GC-content distribution of the input sequence regions. The default length and number of background regions are 1000 and 10,000, respectively. The length of sequence regions used for motif finding is important. Here, we set 1000 as default value, which means for each region, we get sequences from -500 to +500 relative from center. For example,

setGenome("testgenome")

## Configure bsgenome ...

## Configure bsgenome finished

## Configure motifpwm ...

## Configure motifpwm finished

## Configure motifPWMOBJ ...

## Configure motifPWMOBJ finished

## Configure RE_gene_corr ...

## Configure RE_gene_corr finished

## Configure Enhancer_RE_gene_corr ...

## Configure Enhancer_RE_gene_corr finished

## Configure MotifTFTable ...

## Configure MotifTFTable finished

## Configure MotifWeights ...

## Configure MotifWeights finished

## Configure TFgeneRelMtx ...

## Configure TFgeneRelMtx finished

## Configure SampleName ...

## Configure SampleName finished

## Configure OpenRegion ...

## Configure OpenRegion finished

## Configure ConserveRegion ...

## Configure ConserveRegion finished

## Configure HOMER ...

## Configure HOMER finished

## Configure OrgDb ...

## Configure OrgDb finished

foregroundBedPath <- system.file(package = "enrichTF", "extdata","testregion.bed")
gen <- genBackground(inputForegroundBed = foregroundBedPath)

## >>>>>>==========================================================

## Step Name:pipe_GenBackground

## All Parameters for This Step:

## |Input:

## |    inputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rinst46f9297fd120/enrichTF/extdata/testregion.bed"

## |Output:

## |    outputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.foreground.bed"

## |    outputBackgroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.background.bed"

## |    outputRegionBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.allregion.bed"

## |Other Parameters:

## |    bsgenome:

## |        An object of BSgenome

## |    regionLen:

## |        1000

## |    sampleNumb:

## |        0

## __________________________________________

## Begin to check if it is finished...

## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"

## 2020-04-28 00:06:50

## New step. Start processing data:

## 2020-04-28 00:06:50

## processing finished

## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"
## [1] "2020-04-28 00:06:50 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

4.2 Motifscan

The function of regionConnectTargetGene is to connect foreground and background regions to their target genes, which are predicted from PECA model.

For example,

conTG <- enrichRegionConnectTargetGene(gen)

## >>>>>>==========================================================

## Step Name:pipe_RegionConnectTargetGene

## All Parameters for This Step:

## |Input:

## |    inputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.foreground.bed"

## |    inputBackgroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_01_pipe_GenBackground/testregion.background.bed"

## |Output:

## |    outputForegroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.foreground.bed"

## |    ouputForgroundGeneTxt:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.foreground.txt"

## |    outputBackgroundBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/enrichTF-pipeline/Step_02_pipe_RegionConnectTargetGene/testregion.gene.background.bed"

## |    regularGeneCorrBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/RE_gene_corr.bed"

## |    enhancerRegularGeneCorrBed:

## |        "/tmp/Rtmpawr6mV/Rbuild46f95a0d7415/enrichTF/vignettes/refdir/testgenome/Enhancer_RE_gene_corr.bed"

## |Other Parameters:

## __________________________________________

## Begin to check if it is finished...

## [1] "2020-04-28 00:06:51 EDT"
## [1] "2020-04-28 00:06:51 EDT"
## [1] "2020-04-28 00:06:51 EDT"
## [1] "2020-04-28 00:06:51 EDT"
## [1] "2020-04-28 00:06:51 EDT"
## [1] "2020-04-28 00:06:51 EDT"

## 2020-04-28 00:06:51

## New step. Start processing data:

## 2020-04-28 00:06:52

## processing finished

## [1] "2020-04-28 00:06:52 EDT"
## [1] "2020-04-28 00:06:52 EDT"
## [1] "2020-04-28 00:06:52 EDT"
## [1] "2020-04-28 00:06:52 EDT"
## [1] "2020-04-28 00:06:52 EDT"
## [1] "2020-04-28 00:06:52 EDT"

## All results have been saved.

## ==========================================================<<<<<<

##

4.3 Connect regions with target genes

The function MotifsInRegions is to scan for motif occurrences using the prepared PWMs and obtain the promising candidate motifs in these regions.