motif_tree: Generate 'ggplot2' motif trees with 'ggtree'.
In universalmotif: Import, Modify, and Export Motifs with R

Description Usage Arguments Details Value Author(s) References See Also Examples

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.

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", ...)

`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()`.

See compare_motifs() for more info on comparison parameters.

ggplot object.

Benjamin Jean-Marie Tremblay, b2tremblay@uwaterloo.ca

\insertRef

ggplot2universalmotif

\insertRef

ggtreeuniversalmotif

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

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)