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. Note that this can result in some comparisons failing if no alignment passes the mean IC threshold. Use `average_ic()` to filter out low IC motifs to get around this if you want to avoid getting `NA`s in your output.
`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, benjamin.tremblay@uwaterloo.ca

### References

Wickham H (2009). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. ISBN 978-0-387-98140-6, <URL: 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 (URL: https://doi.org/10.1111/2041-210X.12628), <URL: 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.10.2 Index]