motif_tree {universalmotif}R Documentation

Generate ggplot2 motif trees with ggtree.

Description

For more powerful motif tree functions, see the motifStack package. The motif_tree() function compares motifs with compare_motifs() to create a distance matrix, which is used to generate a phylogeny via ape. This can be plotted with ggtree::ggtree(). The purpose of this function is simply to combine the compare_motifs() and ggtree::ggtree() steps into one. For more control over tree creation, it is recommend to do these steps separately. See the Advanced Usage vignette for such a workthrough.

Usage

motif_tree(motifs, layout = "circular", linecol = "family",
  labels = "none", tipsize = "none", legend = TRUE,
  branch.length = "none", db.scores, method = "MPCC",
  use.type = "PPM", min.overlap = 6, tryRC = TRUE,
  min.mean.ic = 0.5, relative_entropy = FALSE, progress = TRUE,
  BP = FALSE, ...)

Arguments

motifs

list, dist See convert_motifs() for available formats. Alternatively, the resulting comparison matrix from compare_motifs() (run as.dist(results) beforehand; if the comparison was performed with a similarity metric, make sure to convert to distances first).

layout

character(1) One of c('rectangular', 'slanted', 'fan', 'circular', 'radial', 'equal_angle', 'daylight'). See ggtree::ggtree().

linecol

character(1) universalmotif slot to use to colour lines (e.g. 'family'). Not available for dist input (see examples for how to add it manually). See ggtree::ggtree().

labels

character(1) universalmotif slot to use to label tips (e.g. 'name'). For dist input, only 'name' is available. See ggtree::ggtree().

tipsize

character(1) universalmotif slot to use to control tip size (e.g. 'icscore'). Not available for dist input (see examples for how to add it manually). See ggtree::ggtree().

legend

logical(1) Show legend for line colour and tip size. See ggtree::ggtree().

branch.length

character(1) If 'none', draw a cladogram. See ggtree::ggtree().

db.scores

data.frame See compare_motifs().

method

character(1) One of c('PCC', 'MPCC', 'EUCL', 'SW', 'MSW', 'KL', 'MKL'). See compare_motifs().

use.type

character(1)c('PPM', 'ICM'). The latter allows for taking into account the background frequencies (only if relative_entropy = TRUE'). See compare_motifs().

min.overlap

numeric(1) Minimum overlap required when aligning the motifs. Setting this to a number higher then the width of the motifs will not allow any overhangs. Can also be a number less than 1, representing the minimum fraction that the motifs must overlap. See compare_motifs().

tryRC

logical(1) Try the reverse complement of the motifs as well, report the best score. See compare_motifs().

min.mean.ic

numeric(1) Minimum information content between the two motifs for an alignment to be scored. This helps prevent scoring alignments between low information content regions of two motifs. See compare_motifs().

relative_entropy

logical(1) For ICM calculation. See convert_type().

progress

logical(1) Show progress of compare_motifs(). Not recommended if BP = TRUE.

BP

logical(1) Allows the use of BiocParallel within compare_motifs(). See BiocParallel::register() to change the default backend. Setting BP = TRUE is only recommended for comparing large numbers of motifs (>10,000). Furthermore, the behaviour of progress = TRUE is changed if BP = TRUE; the default BiocParallel progress bar will be shown (which unfortunately is much less informative).

...

ggtree params. See ggtree::ggtree().

Value

ggplot object.

Author(s)

Benjamin Jean-Marie Tremblay, b2tremblay@uwaterloo.ca

References

Wickham H (2009). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. ISBN 978-0-387-98140-6, http://ggplot2.org.

Yu G, Smith D, Zhu H, Guan Y, Lam TT (2017). “ggtree: an R package for visualization and annotation of phylogenetic trees with their covariates and other associated data.” Methods in Ecology and Evolution, 8, 28-36. doi: 10.1111/2041-210X.12628, http://onlinelibrary.wiley.com/doi/10.1111/2041-210X.12628/abstract.

See Also

motifStack::motifStack(), compare_motifs(), ggtree::ggtree(), ggplot2::ggplot()

Examples

jaspar <- read_jaspar(system.file("extdata", "jaspar.txt",
                                  package = "universalmotif"))
jaspar.tree <- motif_tree(jaspar, linecol = "none", labels = "name",
                          layout = "rectangular")

## Not run: 
## When inputting a dist object, the linecol and tipsize options are
## not available. To add these manually:

library(MotifDb)
library(ggtree)
library(ggplot2)

motifs <- filter_motifs(MotifDb, organism = "Athaliana")[1:50]
comparison <- compare_motifs(motifs, method = "MPCC")
comparison <- as.dist(1 - comparison)
mot.names <- attr(comparison, "Labels")
tree <- motif_tree(comparison)

annotations <- data.frame(label = mot.names,
                          icscore = sapply(motifs, function(x) x["icscore"]),
                          family = sapply(motifs, function(x) x["family"]))

tree <- tree %<+% annotations +
          geom_tippoint(aes(size = icscore)) +
          aes(colour = family) +
          theme(legend.position = "right",
                legend.title = element_blank())

## End(Not run)


[Package universalmotif version 1.2.1 Index]