Guided Logolas Tutorial

Kushal Dey, Dongyue Xie, Matthew Stephens

2019-10-29

We present an elaborate guided tutorial of how to use the Logolas R package. A pdf version of this vignette can be found here.

Features of Logolas

Compared to the existing packages for plotting sequence logos (seqLogo, seq2Logo, motifStack etc), Logolas offers several new features that makes logo visualization a more generic tool with potential applications in a much wider scope of problems.

Installation

Logolas loads as dependencies the following CRAN-R package : grid, gridExtra, SQUAREM, LaplacesDemon, Matrix, RColorBrewer. To run this vignette, the user also would be required to install the ggseqlogo package.

The Bioc version of Logolas can be installed as follows

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

For installing the developmental version of Logolas from Github, the user is required to have the devtools package and then run the following command.

devtools::install_github('kkdey/Logolas')

Load the Logolas package.

library(Logolas)

Accepted Data Types

Data Format

Logolas accepts two data formats as input

String Data example

Consider aligned strings of characters

The logo plots (both standard and Enrichment Depletion Logo) can be plotted using the function.

Instead of DNA.RNA sequence as above, one can also use amino acid character sequences.

Positional Frequency (Weight) Matrix

We now see an example of positional weight matrix (PWM) as input to logomaker().

##     1   2   3   4   5   6   7   8
## A 0.0 0.0 0.0 0.3 0.2 0.0 0.0 0.0
## C 0.8 0.2 0.8 0.3 0.4 0.2 0.8 0.2
## G 0.2 0.8 0.2 0.4 0.3 0.8 0.2 0.8
## T 0.0 0.0 0.0 0.0 0.1 0.0 0.0 0.0

We plot the logo plots for this PWM matrix.

## [1] 1.2751513 1.2751513 1.2751513 0.4277256 0.1534290 1.2751513 1.2751513
## [8] 1.2751513

## $pos_ic
##         1         2         3         4         5         6         7 
## 6.3105144 6.3105144 6.3105144 0.4031197 0.9645379 6.3105144 6.3105144 
##         8 
## 6.3105144 
## 
## $neg_ic
##        1        2        3        4        5        6        7        8 
## 4.364040 4.364040 4.364040 4.925458 1.493007 4.364040 4.364040 4.364040 
## 
## $table_mat_pos_norm
##           1         2         3 4         5         6         7         8
## A 0.0000000 0.0000000 0.0000000 0 0.0000000 0.0000000 0.0000000 0.0000000
## C 0.6542247 0.3457753 0.6542247 0 0.7089704 0.3457753 0.6542247 0.3457753
## G 0.3457753 0.6542247 0.3457753 1 0.2910296 0.6542247 0.3457753 0.6542247
## T 0.0000000 0.0000000 0.0000000 0 0.0000000 0.0000000 0.0000000 0.0000000
## 
## $table_mat_neg_norm
##     1   2   3 4        5   6   7   8
## A 0.5 0.5 0.5 0 0.188016 0.5 0.5 0.5
## C 0.0 0.0 0.0 0 0.000000 0.0 0.0 0.0
## G 0.0 0.0 0.0 0 0.000000 0.0 0.0 0.0
## T 0.5 0.5 0.5 1 0.811984 0.5 0.5 0.5

The outputs the information content at each position for the standard logo plot (type = “Logo”) and the heights of the stacks along the positive and negative Y axis, along with the breakdown of the height due to different characters for the EDLogo plot (type = “EDLogo”).

Configuring Logos

Coloring schemes

The logomaker() function provides three arguments to set the colors for the logos, a color_type specifying the scheme of coloring used, colors denoting the cohort of colors used and a color_seed argument determining how sampling is done from this cohort.

The color_type argument can be of three types, per_row, per_column and per_symbol. colors element is a cohort of colors (chosen suitably large) from which distinct colors are chosen based on distinct color_type. The number of colors chosen is of same length as number of rows in table for per_row (assigning a color to each string), of same length as number of columns in table for per_column (assuming a color for each column), or a distinct color for a distinct symbol in per_symbol. The length of colors should be as large as the number of colors to be chosen in each scenario. % The default color_type is per-row and default colors comprises of a large cohort of nearly 70 distinct colors from which colors are sampled using the color_seed argument.

Styles of symbols

Besides the default style with filled symbols for each character, one can also use characters with border styles. For the standard logo plot, this is accomplished by the tofill control argument.

For an EDLogo plot, the arguments tofill_pos and tofill_neg represent the coloring scheme for the positive and the negative axes in an EDLogo plot.

Background Info

Logolas allows the user to scale the data based on a specified background information. The background information can be incorporated in the argument bg. The default value is NULL, in which case equal probability is assigned to each symbol. The user can however specify a vector (equal to in length to the number of symbols) which specifies the background probability for each symbol and assumes this background probability to be the same across the columns (sites), or a matrix, whose each cell specifies the background probability of the symbols for each position.

First example with bg as a vector.

Second example with bg as a matrix.

Adaptive scaling of logos (dash)

Logolas allows the user to perform adaptive scaling of the stack heights in a logo plot based on the number of aligned sequences, using the use_dash argument. This scaling is performed only when the data input into the logomaker() function is a vector of sequences or a position frequency (PFM) matrix. We show an example with and without the use_dash argument.

The adaptive scaling is performed by the Dirichlet Adaptive Shrinkage method, the details of which can be viewed at our dashr package.

String symbols

Logolas allows the user to plot symbols not just for characters as we saw in previous examples, but for any alphanumeric string. We present two examples - one for representing mutation signature and another for representing histone marks composition.

Histone marks string symbols example

Mutation signature string and character mix example.

The user may want to have distinct colors for distinct symbols. This is where we use the per_symbol option for color_type.

The corresponding EDLogo

Extras

Consensus Sequence

Logolas provides a new nomenclature to geneerate consensus sequence from a positional frequency (weight) matrix or from a vector of aligned sequences. This is performed by the GetConsensusSeq() function.

## [1] "C T (Ag) T T (Ac) (TA)"

In the sequence, a position represented by (Ag) would mean enrichment in A and depletion in G at that position. One can input a PWM or PFM matrix with A, C, G and T as row names in the GetConsensusSeq() function as well.

Multiple panels plots}

Logolas plots can be plotted in multiple panels, as depicted below.

In the same way, ggplot2 graphics can also be combined with Logolas plots.

PSSM logos

While logomaker() takes a PFM, PWM or a set of aligned sequences as input, sometimes, some position specific scores are only available to the user. In this case, one can use the logo_pssm() in Logolas to plot the scoring matrix.

The round_off comtrol argument specifies the number of points after decimal allowed in the axes of the plot.

Acknowledgements

The authors would like to acknowledge Oliver Bembom, the author of seqLogo for acting as an inspiration and providing the foundation on which this package is created. We also thank Peter Carbonetto, Edward Wallace and John Blischak for helpful feedback and discussions.

sessionInfo()
## R version 3.6.1 (2019-07-05)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.3 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.10-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.10-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] grid      stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
## [1] ggseqlogo_0.1  Logolas_1.10.0
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_1.0.2           RColorBrewer_1.1-2   XVector_0.26.0      
##  [4] pillar_1.4.2         compiler_3.6.1       zlibbioc_1.32.0     
##  [7] tools_3.6.1          digest_0.6.22        evaluate_0.14       
## [10] tibble_2.1.3         gtable_0.3.0         gridBase_0.4-7      
## [13] pkgconfig_2.0.3      rlang_0.4.1          yaml_2.2.0          
## [16] parallel_3.6.1       LaplacesDemon_16.1.1 xfun_0.10           
## [19] stringr_1.4.0        dplyr_0.8.3          knitr_1.25          
## [22] IRanges_2.20.0       Biostrings_2.54.0    S4Vectors_0.24.0    
## [25] stats4_3.6.1         tidyselect_0.2.5     glue_1.3.1          
## [28] R6_2.4.0             rmarkdown_1.16       ggplot2_3.2.1       
## [31] purrr_0.3.3          magrittr_1.5         scales_1.0.0        
## [34] htmltools_0.4.0      BiocGenerics_0.32.0  assertthat_0.2.1    
## [37] colorspace_1.4-1     stringi_1.4.3        lazyeval_0.2.2      
## [40] munsell_0.5.0        SQUAREM_2017.10-1    crayon_1.3.4

Thank you for using Logolas !

If you have any questions, you can either open an issue in our Github page or write to Kushal K Dey (kkdey@uchicago.edu). Also please feel free to contribute to the package. You can contribute by submitting a pull request or by communicating with the said person.