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. 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 "Motif comparisons and P-values" vignette for such a workthrough. This function requires the ape and ggtree packages to be installed separately.

### Usage

    motif_tree(motifs, layout = "circular", linecol = "family",
      labels = "none", tipsize = "none", legend = TRUE,
      branch.length = "none", db.scores, method = "EUCL", use.type = "PPM",
      min.overlap = 6, min.position.ic = 0, tryRC = TRUE, min.mean.ic = 0,
      relative_entropy = FALSE, progress = FALSE, nthreads = 1,
      score.strat = "a.mean", ...)

### 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 PCC, EUCL, SW, KL, ALLR, BHAT, HELL, SEUCL, MAN, ALLR_LL, WEUCL, WPCC. See details.
`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 between 0 and 1, representing the minimum fraction that the motifs must overlap.
`min.position.ic` | `numeric(1)` Minimum information content required between individual alignment positions for it to be counted in the final alignment score. It is recommended to use this together with `normalise.scores = TRUE`, as this will help punish scores resulting from only a fraction of an alignment.
`tryRC` | `logical(1)` Try the reverse complement of the motifs as well, report the best score.
`min.mean.ic` | `numeric(1)` Minimum mean 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.
`relative_entropy` | `logical(1)` Change the ICM calculation affecting `min.position.ic` and `min.mean.ic`. See `convert_type()`.
`progress` | `logical(1)` Show message regarding current step.
`nthreads` | `numeric(1)` Run `compare_motifs()` in parallel with `nthreads` threads. `nthreads = 0` uses all available threads.
`score.strat` | `character(1)` How to handle column scores calculated from motif alignments. "sum": add up all scores. "a.mean": take the arithmetic mean. "g.mean": take the geometric mean. "median": take the median. "wa.mean", "wg.mean": weighted arithmetic/geometric mean. "fzt": Fisher Z-transform. Weights are the total information content shared between aligned columns.
`...` | ggtree params. See `ggtree::ggtree()`.

### Details

See `compare_motifs()` for more info on comparison parameters.

### 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(1), 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"))
    if (requireNamespace("ggtree", quietly = TRUE)) {
    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 = "PCC", score.strat = "a.mean")
    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.8.5 Index]