| Title: | Dendrograms for Evolutionary Analysis |
|---|---|
| Description: | Contains functions for developing phylogenetic trees as deeply-nested lists ("dendrogram" objects). Enables bi-directional conversion between dendrogram and "phylo" objects (see Paradis et al (2004) <doi:10.1093/bioinformatics/btg412>), and features several tools for command-line tree manipulation and import/export via Newick parenthetic text. |
| Authors: | Shaun Wilkinson [aut, cre] (ORCID: <https://orcid.org/0000-0002-7332-7931>), Simon Davy [aut] (ORCID: <https://orcid.org/0000-0003-3584-5356>) |
| Maintainer: | Shaun Wilkinson <[email protected]> |
| License: | GPL-3 |
| Version: | 2.1.0.9000 |
| Built: | 2025-11-25 07:08:35 UTC |
| Source: | https://github.com/ropensci/phylogram |
This function sets the 'height' attributes of all leaf nodes to zero and progressively resets the heights of the inner nodes by single incremental units in a bottom-up fashion.
as.cladogram(x)as.cladogram(x)
x |
an object of class |
an object of class "dendrogram".
Shaun Wilkinson
x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- as.cladogram(x) plot(x, horiz = TRUE)x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- as.cladogram(x) plot(x, horiz = TRUE)
This function converts a "phylo" object (Paradis et al 2004) to a dendrogram.
## S3 method for class 'phylo' as.dendrogram(object, ...)## S3 method for class 'phylo' as.dendrogram(object, ...)
object |
an object of class "phylo". |
... |
further arguments to be passed between methods. |
an object of class "dendrogram".
Shaun Wilkinson
Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.
Paradis E (2008) Definition of Formats for Coding Phylogenetic Trees in R. http://ape-package.ird.fr/misc/FormatTreeR_24Oct2012.pdf
Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.
newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);" x <- read.dendrogram(text = newick) y <- as.phylo(x) z <- as.dendrogram(y) identical(x, z)newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);" x <- read.dendrogram(text = newick) y <- as.phylo(x) z <- as.dendrogram(y) identical(x, z)
This function converts a dendrogram into an object of class "phylo" (see Paradis et al 2004).
## S3 method for class 'dendrogram' as.phylo(x, ...)## S3 method for class 'dendrogram' as.phylo(x, ...)
x |
a dendrogram. |
... |
further arguments to be passed between methods. |
an object of class "phylo".
Shaun Wilkinson
Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.
Paradis E (2008) Definition of Formats for Coding Phylogenetic Trees in R. http://ape-package.ird.fr/misc/FormatTreeR_24Oct2012.pdf
Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.
newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);" x <- read.dendrogram(text = newick) y <- as.phylo(x) z <- as.dendrogram(y)newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);" x <- read.dendrogram(text = newick) y <- as.phylo(x) z <- as.dendrogram(y)
This function ladderizes the branches of a dendrogram object
to aid in visual interpretation.
ladder(x, decreasing = FALSE)ladder(x, decreasing = FALSE)
x |
an object of class |
decreasing |
logical indicating whether the tree should be ladderized upwards or downwards. Defaults to FALSE (downwards). |
This function is the dendrogram analogue of the
ladderize function in the ape
package (Paradis et al 2004, 2012).
Returns an object of class dendrogram.
Shaun Wilkinson
Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.
Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.
The ladderize function in the
ape package performs a similar operation for objects
of class "phylo".
x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- ladder(x, decreasing = TRUE) plot(x, horiz = TRUE)x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- ladder(x, decreasing = TRUE) plot(x, horiz = TRUE)
The phylogram R package is a tool for for developing phylogenetic trees as deeply-nested lists known as "dendrogram" objects. It provides functions for conversion between "dendrogram" and "phylo" class objects, as well as several tools for command-line tree manipulation and import/export via Newick parenthetic text. This improves accessibility to the comprehensive range of object-specific analytical and tree-visualization functions found across a wide array of bioinformatic R packages.
A brief description of the primary phylogram functions are provided with links to their help pages below.
read.dendrogram reads a Newick
parenthetic text string from a file or text connection
and creates an object of class "dendrogram"
write.dendrogram outputs an object of class
"dendrogram" to a text string or file in Newick
format
as.phylo.dendrogram converts a dendrogram to
an object of class "phylo"
"dendrogram"
as.dendrogram.phylo converts a "phylo" object
to a dendrogram
prune remove branches from a dendrogram object
based on regular expression pattern matching
ladder reorders the branches of a dendrogram
object to aid visualization
remidpoint recursively sets "midpoint" and "members"
attributes for a nested list/dendrogram object
reposition shifts a dendrogram object up or
down (or sideways if plotted horizontally)
as.cladogram modifies the "height" attributes of the
nodes such that all leaves terminate at zero
"prune" takes an object of class "dendrogram" and
removes all branches whose branch labels match a given regular
expression.
prune(tree, pattern, keep = FALSE, ...)prune(tree, pattern, keep = FALSE, ...)
tree |
an object of class |
pattern |
a regular expression. |
keep |
logical indicating whether the nodes whose labels match the regular expression provided in "pattern" should be kept and the remainder discarded. Defaults to FALSE. Note that nodes without "label" attributes are ignored. |
... |
further arguments to be passed to |
This function recursively tests the "label" attribute of each dendrogram node (including non-leaf inner nodes if applicable) for the specified pattern, removing those that register a positive hit. Note that positive matching inner nodes are removed along with all of their sub-nodes, regardless of whether the "label" attributes of the sub-nodes match the pattern.
Returns an object of class "dendrogram".
Shaun Wilkinson
The drop.tip function in the
ape package performs a similar operation for objects
of class "phylo". See regex for help with
compiling regular expressions.
x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- prune(x, pattern = "^A$") plot(x, horiz = TRUE)x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- prune(x, pattern = "^A$") plot(x, horiz = TRUE)
This function wraps the read.tree parser from the
ape package to read a phylogenetic tree from
parenthetic text in the Newick/New Hampshire format, and
converts it to object of class "dendrogram".
read.dendrogram(file = "", text = NULL, ...)read.dendrogram(file = "", text = NULL, ...)
file |
character string giving a valid path to the file from which to read the data. |
text |
optional character string in lieu of a "file" argument. If a text argument is provided instead of a file path, the data are read via a text connection. |
... |
further arguments to be passed to
|
an object of class "dendrogram".
Shaun Wilkinson
Felsenstein J (1986) The Newick tree format. http://evolution.genetics.washington.edu/phylip/newicktree.html
Olsen G (1990) Interpretation of the "Newick's 8:45" tree format standard. http://evolution.genetics.washington.edu/phylip/newick_doc.html
Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.
Paradis E (2008) Definition of Formats for Coding Phylogenetic Trees in R. http://ape-package.ird.fr/misc/FormatTreeR_24Oct2012.pdf
Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.
write.dendrogram writes an object of
class "dendrogram" to a Newick text string.
The read.tree function in the
ape package parses objects
of class "phylo" and "multiPhylo".
x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE)x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE)
remidpoint is a helper function used for manually creating
"dendrogram" objects from nested lists. The function
recursively assigns the necessary 'midpoint', 'members', and
'leaf' attributes at each node.
remidpoint(x)remidpoint(x)
x |
a nested list, possibly of class |
returns a nested list, or an object of class "dendrogram"
depending on the class of the input object.
Shaun Wilkinson
## manually create a small dendrogram with three members, A, B and C x <- list("A", list("B", "C")) attr(x[[1]], "leaf") <- TRUE attr(x[[2]][[1]], "leaf") <- TRUE attr(x[[2]][[2]], "leaf") <- TRUE attr(x[[1]], "label") <- "A" attr(x[[2]][[1]], "label") <- "B" attr(x[[2]][[2]], "label") <- "C" attr(x, "height") <- 1 attr(x[[1]], "height") <- 0 attr(x[[2]], "height") <- 0.5 attr(x[[2]][[1]], "height") <- 0 attr(x[[2]][[2]], "height") <- 0 x <- remidpoint(x) class(x) <- "dendrogram" plot(x, horiz = TRUE)## manually create a small dendrogram with three members, A, B and C x <- list("A", list("B", "C")) attr(x[[1]], "leaf") <- TRUE attr(x[[2]][[1]], "leaf") <- TRUE attr(x[[2]][[2]], "leaf") <- TRUE attr(x[[1]], "label") <- "A" attr(x[[2]][[1]], "label") <- "B" attr(x[[2]][[2]], "label") <- "C" attr(x, "height") <- 1 attr(x[[1]], "height") <- 0 attr(x[[2]], "height") <- 0.5 attr(x[[2]][[1]], "height") <- 0 attr(x[[2]][[2]], "height") <- 0 x <- remidpoint(x) class(x) <- "dendrogram" plot(x, horiz = TRUE)
reposition is a helper function used for manually creating
"dendrogram" objects from nested lists. The function
recursively reassigns the 'height' attributes at each node by
a given constant.
reposition(x, shift = "reset")reposition(x, shift = "reset")
x |
an object of class |
shift |
either the character string "reset" (shift the graph so that the height of the farthest leaf from the root is zero), or a numeric value giving the amount to shift the graph along the primary axis. |
Returns an object of class "dendrogram".
Shaun Wilkinson
x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- reposition(x) plot(x, horiz = TRUE)x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);") plot(x, horiz = TRUE) x <- reposition(x) plot(x, horiz = TRUE)
This function exports a dendrogram object as a Newick/New Hampshire text string.
write.dendrogram(x, file = "", append = FALSE, edges = TRUE, ...)write.dendrogram(x, file = "", append = FALSE, edges = TRUE, ...)
x |
an object of class |
file |
a character string naming a file or connection to write the
output to. If no file path is specified or |
append |
logical indicating whether the output should be
appended to the file. If |
edges |
logical indicating whether edge weights should be included in the output string. |
... |
further arguments to be passed to |
Felsenstein J (1986) The Newick tree format. http://evolution.genetics.washington.edu/phylip/newicktree.html
Olsen G (1990) Interpretation of the "Newick's 8:45" tree format standard. http://evolution.genetics.washington.edu/phylip/newick_doc.html
read.dendrogram to parse a "dendrogram"
object from a text file.
The write.tree function in the ape
package performs a similar operation for "phylo"
and "multiPhylo" objects.
newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);" x <- read.dendrogram(text = newick) write.dendrogram(x, edges = TRUE)newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);" x <- read.dendrogram(text = newick) write.dendrogram(x, edges = TRUE)