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]