Package version: motifStack 1.20.1

Contents

1 Introduction

A sequence logo, based on information theory, has been widely used as a graphical representation of sequence conservation (aka motif) in multiple amino acid or nucleic acid sequences. Sequence motif represents conserved characteristics such as DNA binding sites, where transcription factors bind, and catalytic sites in enzymes. Although many tools, such as seqlogo, have been developed to create sequence motif and to represent it as individual sequence logo, software tools for depicting the relationship among multiple sequence motifs are still lacking. We developed a flexible and powerful open-source R/Bioconductor package, motifStack, for visualization of the alignment of multiple sequence motifs.

2 Prepare environment

You will need ghostscript. The full path to the executable can be set using the environment variable R_GSCMD. If this is unset, environment variable gs (Unix, Linux or Mac) or GSC (Window) will be searched by name on your path. If gs/GSC is unset, GhostScript executable “gswi64c.exe” and “gswin32c.exe” are tried sequentially.

Here is an example on Windows assuming that the gswin32c.exe is installed at C:\ Program Files\ gs\ gs9.06\ bin. In a R session, please try:

Sys.setenv(R_GSCMD=file.path("C:", "Program Files", "gs", 
                             "gs9.06", "bin", "gswin32c.exe"))

3 Examples of using motifStack

3.1 plot a DNA sequence logo with different fonts and colors

Users can select different fonts and colors to draw the sequence logo.

suppressPackageStartupMessages(library(motifStack))
pcm <- read.table(file.path(find.package("motifStack"), 
                            "extdata", "bin_SOLEXA.pcm"))
pcm <- pcm[,3:ncol(pcm)]
rownames(pcm) <- c("A","C","G","T")
motif <- new("pcm", mat=as.matrix(pcm), name="bin_SOLEXA")
##pfm object
#motif <- pcm2pfm(pcm)
#motif <- new("pfm", mat=motif, name="bin_SOLEXA")
opar<-par(mfrow=c(4,1))
plot(motif)
#plot the logo with same height
plot(motif, ic.scale=FALSE, ylab="probability")
#try a different font
plot(motif, font="mono,Courier")
#try a different font and a different color group
motif@color <- colorset(colorScheme='basepairing')
plot(motif,font="Times")

Plot a DNA sequence logo with different fonts and colors

par(opar)

3.4 plot sequence logo stack

To show multiple motifs on the same canvas as a sequence logo stack, the distance of motifs need to be calculated first. By default, MotIV::motifDistances ( R implementation of STAMP) is used to calculate the distance. After alignment, users can use plotMotifLogoStack, plotMotifLogoStackWithTree or plotMotifStackWithRadialPhylog to draw sequence logos in different layouts. To make it easy to use, we integrated different functionalities into one workflow function named as motifStack.

suppressPackageStartupMessages(library(motifStack))
#####Input#####
pcms<-readPCM(file.path(find.package("motifStack"), "extdata"),"pcm$")
motifs<-lapply(pcms,pcm2pfm)

## plot stacks
#motifStack(motifs, layout="stack", ncex=1.0)
## plot stacks with hierarchical tree
#motifStack(motifs, layout="tree")
## When the number of motifs is too much to be shown in a vertical stack, 
## motifStack can draw them in a radial style.
## random sample from MotifDb
library("MotifDb")
## See system.file("LICENSE", package="MotifDb") for use restrictions.
matrix.fly <- query(MotifDb, "Dmelanogaster")
motifs2 <- as.list(matrix.fly)
## use data from FlyFactorSurvey
motifs2 <- motifs2[grepl("Dmelanogaster\\-FlyFactorSurvey\\-",
                         names(motifs2))]
## format the names
names(motifs2) <- gsub("Dmelanogaster_FlyFactorSurvey_", "",
                       gsub("_FBgn\\d+$", "",
                            gsub("[^a-zA-Z0-9]","_",
                                 gsub("(_\\d+)+$", "", names(motifs2)))))
motifs2 <- motifs2[unique(names(motifs2))]
pfms <- sample(motifs2, 50)
## creat a list of object of pfm 
motifs2 <- lapply(names(pfms), 
                  function(.ele, pfms){new("pfm",mat=pfms[[.ele]], name=.ele)}
                  ,pfms)
## trim the motifs
motifs2 <- lapply(motifs2, trimMotif, t=0.4)
## setting colors
library(RColorBrewer)
color <- brewer.pal(12, "Set3")
## plot logo stack with radial style
motifStack(motifs2, layout="radialPhylog", 
           circle=0.3, cleaves = 0.2, 
           clabel.leaves = 0.5, 
           col.bg=rep(color, each=5), col.bg.alpha=0.3, 
           col.leaves=rep(color, each=5),
           col.inner.label.circle=rep(color, each=5), 
           inner.label.circle.width=0.05,
           col.outer.label.circle=rep(color, each=5), 
           outer.label.circle.width=0.02, 
           circle.motif=1.2,
           angle=350)

Plot motifs in a radial style when the number of motifs is too much to be shown in a vertical stack

3.5 plot a sequence logo cloud

We can also plot a sequence logo cloud for DNA motifs.

## assign groups for motifs
groups <- rep(paste("group",1:5,sep=""), each=10)
names(groups) <- names(pfms)
## assign group colors
group.col <- brewer.pal(5, "Set3")
names(group.col)<-paste("group",1:5,sep="")
## use MotIV to calculate the distances of motifs
jaspar.scores <- MotIV::readDBScores(file.path(find.package("MotIV"), 
                                               "extdata", 
                                               "jaspar2010_PCC_SWU.scores"))
d <- MotIV::motifDistances(lapply(pfms, pfm2pwm))
hc <- MotIV::motifHclust(d, method="average")
## convert the hclust to phylog object
phylog <- hclust2phylog(hc)
## reorder the pfms by the order of hclust
leaves <- names(phylog$leaves)
pfms <- pfms[leaves]
## create a list of pfm objects
pfms <- lapply(names(pfms), function(.ele, pfms){
                                new("pfm",mat=pfms[[.ele]], name=.ele)}
               ,pfms)
## extract the motif signatures
motifSig <- motifSignature(pfms, phylog, groupDistance=0.01, min.freq=1)
## draw the motifs with a tag-cloud style.
motifCloud(motifSig, scale=c(6, .5), 
           layout="rectangles", 
           group.col=group.col, 
           groups=groups, 
           draw.legend=TRUE)

Sequence logo cloud with rectangle packing layout

3.7 motifCircos

We can also plot it with circos style. In circos style, we can plot two group of motifs and with multiple color rings.

## plot the logo stack with radial style.
motifCircos(phylog=phylog, pfms=pfms, pfms2=sig, 
            col.tree.bg=rep(color, each=5), col.tree.bg.alpha=0.3, 
            col.leaves=rep(rev(color), each=5),
            col.inner.label.circle=gpCol, 
            inner.label.circle.width=0.03,
            col.outer.label.circle=gpCol, 
            outer.label.circle.width=0.03,
            r.rings=c(0.02, 0.03, 0.04), 
            col.rings=list(sample(colors(), 50), 
                           sample(colors(), 50), 
                           sample(colors(), 50)),
            angle=350, motifScale="logarithmic")

Grouped sequence logo with circos style layout

3.8 motifPiles

We can also plot the motifs in pile style. In pile style, we can plot two group of motifs with multiple types of annotation.

## plot the logo stack with radial style.
motifPiles(phylog=phylog, pfms=pfms, pfms2=sig, 
            col.tree=rep(color, each=5),
            col.leaves=rep(rev(color), each=5),
            col.pfms2=gpCol, 
            r.anno=c(0.02, 0.03, 0.04), 
            col.anno=list(sample(colors(), 50), 
                          sample(colors(), 50), 
                          sample(colors(), 50)),
            motifScale="logarithmic",
            plotIndex=TRUE,
            groupDistance=0.01)

Grouped sequence logo with piles style layout

4 plot motifs with d3.js

Interactive plot can be generated using browseMotifs function which leverages the d3.js library. All motifs on the plot are draggable and the plot can be easily exported as a Scalable Vector Graphics (SVG) file.

browseMotifs(pfms = pfms, phylog = phylog, layout="tree", yaxis = FALSE, baseWidth=6, baseHeight = 15)

Plot the motifs in radialPhylog layout.

browseMotifs(pfms = pfms, phylog = phylog, layout="radialPhylog", yaxis = FALSE, xaxis = FALSE, baseWidth=6, baseHeight = 15)

5 docker container for motifStack

Docker container allows software to be packaged into containers which can be run in any platform using a virtual machine called boot2docker. Users can download the motifStack docker image using the following code snippet.

docker pull jianhong/motifstack_1.13.6
cd ~ ## in windows, please try cd c:\\ Users\\ username
mkdir tmp4motifstack ## this will be the share folder for your host and container.
docker run -ti --rm -v ${PWD}/tmp4motifstack:/volume/data jianhong/motifstack_1.13.6 R
## in R
setwd("/tmp")
library(motifStack)
packageVersion("motifStack")
pcmpath <- "pcmsDatasetFly"
pcms <- readPCM(pcmpath)
pfms <- lapply(pcms, pcm2pfm)
matalign_path <- "/usr/bin/matalign"
neighbor_path <- "/usr/bin/phylip/neighbor"
outpath <- "output"
system(paste("perl MatAlign2tree.pl --in . --pcmpath", pcmpath, "--out", outpath,
    "--matalign", matalign_path, "--neighbor", neighbor_path, "--tree","UPGMA"))
newickstrUPGMA <- readLines(con=file.path(outpath, "NJ.matalign.distMX.nwk"))
phylog <- newick2phylog(newickstrUPGMA, FALSE)
leaves <- names(phylog$leaves)
motifs <- pfms[leaves]
motifSig <- motifSignature(motifs, phylog, groupDistance=2, min.freq=1, trim=.2)
sig <- signatures(motifSig)
gpCol <- sigColor(motifSig)
leaveNames <- gsub("^Dm_", "", leaves)
pdf("/volume/data/test.pdf", width=8, height=11)
motifPiles(phylog=phylog, DNAmotifAlignment(motifs), sig, 
    col.pfms=gpCol, col.pfms.width=.01, 
    col.pfms2=gpCol, col.pfms2.width=.01, 
    labels.leaves=leaveNames, 
    plotIndex=c(FALSE, TRUE), IndexCex=1, 
    groupDistance=2, clabel.leaves=1)
dev.off()

You will see the test.pdf file in the folder of tmp4motifstack.

6 Session Info

sessionInfo()
## R version 3.4.1 (2017-06-30)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 16.04.2 LTS
## 
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.5-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.5-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
##  [1] stats4    parallel  grid      stats     graphics  grDevices utils    
##  [8] datasets  methods   base     
## 
## other attached packages:
##  [1] RColorBrewer_1.1-2  MotifDb_1.18.0      motifStack_1.20.1  
##  [4] Biostrings_2.44.1   XVector_0.16.0      IRanges_2.10.2     
##  [7] S4Vectors_0.14.3    ade4_1.7-6          MotIV_1.32.0       
## [10] BiocGenerics_0.22.0 grImport_0.9-0      XML_3.98-1.9       
## [13] BiocStyle_2.4.0    
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_0.12.11               highr_0.6                 
##  [3] plyr_1.8.4                 compiler_3.4.1            
##  [5] GenomeInfoDb_1.12.2        bitops_1.0-6              
##  [7] tools_3.4.1                zlibbioc_1.22.0           
##  [9] digest_0.6.12              jsonlite_1.5              
## [11] evaluate_0.10.1            lattice_0.20-35           
## [13] BSgenome_1.44.0            Matrix_1.2-10             
## [15] DelayedArray_0.2.7         yaml_2.1.14               
## [17] seqLogo_1.42.0             GenomeInfoDbData_0.99.0   
## [19] rtracklayer_1.36.3         stringr_1.2.0             
## [21] knitr_1.16                 htmlwidgets_0.8           
## [23] rprojroot_1.2              Biobase_2.36.2            
## [25] BiocParallel_1.10.1        rGADEM_2.24.0             
## [27] rmarkdown_1.6              magrittr_1.5              
## [29] scales_0.4.1               backports_1.1.0           
## [31] Rsamtools_1.28.0           htmltools_0.3.6           
## [33] matrixStats_0.52.2         GenomicRanges_1.28.3      
## [35] GenomicAlignments_1.12.1   SummarizedExperiment_1.6.3
## [37] colorspace_1.3-2           stringi_1.1.5             
## [39] munsell_0.4.3              RCurl_1.95-4.8