Title: | Create, Modify and Analyse Phylogenetic Trees |
---|---|
Description: | Efficient implementations of functions for the creation, modification and analysis of phylogenetic trees. Applications include: generation of trees with specified shapes; tree rearrangement; analysis of tree shape; rooting of trees and extraction of subtrees; calculation and depiction of split support; plotting the position of rogue taxa (Klopfstein & Spasojevic 2019) <doi:10.1371/journal.pone.0212942>; calculation of ancestor-descendant relationships, of 'stemwardness' (Asher & Smith, 2022) <doi:10.1093/sysbio/syab072>, and of tree balance (Mir et al. 2013, Lemant et al. 2022) <doi:10.1016/j.mbs.2012.10.005>, <doi:10.1093/sysbio/syac027>; artificial extinction (Asher & Smith, 2022) <doi:10.1093/sysbio/syab072>; import and export of trees from Newick, Nexus (Maddison et al. 1997) <doi:10.1093/sysbio/46.4.590>, and TNT <https://www.lillo.org.ar/phylogeny/tnt/> formats; and analysis of splits and cladistic information. |
Authors: | Martin R. Smith [aut, cre, cph] , Emmanuel Paradis [cph] , Robert Noble [cph] |
Maintainer: | Martin R. Smith <[email protected]> |
License: | GPL (>= 3) |
Version: | 1.12.0.9000 |
Built: | 2024-10-31 10:17:39 UTC |
Source: | https://github.com/ms609/TreeTools |
AddTip()
adds a tip to a phylogenetic tree at a specified location.
AddTip( tree, where = sample.int(tree[["Nnode"]] * 2 + 2L, size = 1) - 1L, label = "New tip", nodeLabel = "", edgeLength = 0, lengthBelow = NULL, nTip = NTip(tree), nNode = tree[["Nnode"]], rootNode = RootNode(tree) ) AddTipEverywhere(tree, label = "New tip", includeRoot = FALSE)
AddTip( tree, where = sample.int(tree[["Nnode"]] * 2 + 2L, size = 1) - 1L, label = "New tip", nodeLabel = "", edgeLength = 0, lengthBelow = NULL, nTip = NTip(tree), nNode = tree[["Nnode"]], rootNode = RootNode(tree) ) AddTipEverywhere(tree, label = "New tip", includeRoot = FALSE)
tree |
A tree of class |
where |
The node or tip that should form the sister taxon to the new
node. To add a new tip at the root, use |
label |
Character string providing the label to apply to the new tip. |
nodeLabel |
Character string providing a label to apply to the newly
created node, if |
edgeLength |
Numeric specifying length of new edge. If |
lengthBelow |
Numeric specifying length below neighbour at which to
graft new edge. Values greater than the length of the edge will result
in negative edge lengths. If |
nTip , nNode , rootNode
|
Optional integer vectors specifying number of tips
and nodes in |
includeRoot |
Logical; if |
AddTip()
extends bind.tree
, which cannot handle
single-taxon trees.
AddTipEverywhere()
adds a tip to each edge in turn.
AddTip()
returns a tree of class phylo
with an additional tip
at the desired location.
AddTipEverywhere()
returns a list of class multiPhylo
containing
the trees produced by adding label
to each edge of tree
in turn.
Martin R. Smith ([email protected])
Add one tree to another: bind.tree()
Other tree manipulation:
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
tree <- BalancedTree(10) # Add a leaf below an internal node plot(tree) ape::nodelabels() node <- 15 ape::nodelabels(bg = ifelse(NodeNumbers(tree) == node, "green", "grey")) plot(AddTip(tree, 15, "NEW_TIP")) # Add edge lengths for an ultrametric tree tree$edge.length <- rep(c(rep(1, 5), 2, 1, 2, 2), 2) # Add a leaf to an external edge leaf <- 5 plot(tree) ape::tiplabels(bg = ifelse(seq_len(NTip(tree)) == leaf, "green", "grey")) plot(AddTip(tree, 5, "NEW_TIP", edgeLength = NULL)) # Set up multi-panel plot oldPar <- par(mfrow = c(2, 4), mar = rep(0.3, 4), cex = 0.9) # Add leaf to each edge on a tree in turn backbone <- BalancedTree(4) # Treating the position of the root as instructive: additions <- AddTipEverywhere(backbone, includeRoot = TRUE) xx <- lapply(additions, plot) par(mfrow = c(2, 3)) # Don't treat root edges as distinct: additions <- AddTipEverywhere(backbone, includeRoot = FALSE) xx <- lapply(additions, plot) # Restore original plotting parameters par(oldPar)
tree <- BalancedTree(10) # Add a leaf below an internal node plot(tree) ape::nodelabels() node <- 15 ape::nodelabels(bg = ifelse(NodeNumbers(tree) == node, "green", "grey")) plot(AddTip(tree, 15, "NEW_TIP")) # Add edge lengths for an ultrametric tree tree$edge.length <- rep(c(rep(1, 5), 2, 1, 2, 2), 2) # Add a leaf to an external edge leaf <- 5 plot(tree) ape::tiplabels(bg = ifelse(seq_len(NTip(tree)) == leaf, "green", "grey")) plot(AddTip(tree, 5, "NEW_TIP", edgeLength = NULL)) # Set up multi-panel plot oldPar <- par(mfrow = c(2, 4), mar = rep(0.3, 4), cex = 0.9) # Add leaf to each edge on a tree in turn backbone <- BalancedTree(4) # Treating the position of the root as instructive: additions <- AddTipEverywhere(backbone, includeRoot = TRUE) xx <- lapply(additions, plot) par(mfrow = c(2, 3)) # Don't treat root edges as distinct: additions <- AddTipEverywhere(backbone, includeRoot = FALSE) xx <- lapply(additions, plot) # Restore original plotting parameters par(oldPar)
ApeTime()
reads the time that a tree written with "ape" was modified,
based on the comment in the Nexus file.
ApeTime(filepath, format = "double")
ApeTime(filepath, format = "double")
filepath |
Character string specifying path to the file. |
format |
Format in which to return the time: "double" as a sortable numeric;
any other value to return a string in the format
|
ApeTime()
returns the time that the specified file was created by
ape, in the format specified by format
.
Martin R. Smith ([email protected])
Remove tokens that do not occur in a fossil "template" taxon from a living taxon, to simulate the process of fossilization in removing data from a phylogenetic dataset.
ArtificialExtinction( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL ) ## S3 method for class 'matrix' ArtificialExtinction( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL ) ## S3 method for class 'phyDat' ArtificialExtinction( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL ) ArtEx( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL )
ArtificialExtinction( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL ) ## S3 method for class 'matrix' ArtificialExtinction( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL ) ## S3 method for class 'phyDat' ArtificialExtinction( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL ) ArtEx( dataset, subject, template, replaceAmbiguous = "ambig", replaceCoded = "original", replaceAll = TRUE, sampleFrom = NULL )
dataset |
Phylogenetic dataset of class |
subject |
Vector identifying subject taxa, by name or index. |
template |
Character or integer identifying taxon to use as a template. |
replaceAmbiguous , replaceCoded
|
Character specifying whether tokens
that are ambiguous (
|
replaceAll |
Logical: if |
sampleFrom |
Vector identifying a subset of characters from which to
sample replacement tokens.
If |
Further details are provided in Asher and Smith (2022).
Note: this simple implementation does not account for character contingency, e.g. characters whose absence imposes inapplicable or absent tokens on dependent characters.
A dataset with the same class as dataset
in which entries that
are ambiguous in template
are made ambiguous in subject
.
Martin R. Smith ([email protected])
Asher R, Smith MR (2022). “Phylogenetic signal and bias in paleontology.” Systematic Biology, 71(4), 986–1008. doi:10.1093/sysbio/syab072.
set.seed(1) dataset <- matrix(c(sample(0:2, 4 * 8, TRUE), "0", "0", rep("?", 6)), nrow = 5, dimnames = list(c(LETTERS[1:4], "FOSSIL"), paste("char", 1:8)), byrow = TRUE) artex <- ArtificialExtinction(dataset, c("A", "C"), "FOSSIL")
set.seed(1) dataset <- matrix(c(sample(0:2, 4 * 8, TRUE), "0", "0", rep("?", 6)), nrow = 5, dimnames = list(c(LETTERS[1:4], "FOSSIL"), paste("char", 1:8)), byrow = TRUE) artex <- ArtificialExtinction(dataset, c("A", "C"), "FOSSIL")
multiPhylo
classConverts representations of phylogenetic trees to an object of the "ape"
class multiPhylo
.
as.multiPhylo(x) ## S3 method for class 'phylo' as.multiPhylo(x) ## S3 method for class 'list' as.multiPhylo(x) ## S3 method for class 'phyDat' as.multiPhylo(x) ## S3 method for class 'Splits' as.multiPhylo(x)
as.multiPhylo(x) ## S3 method for class 'phylo' as.multiPhylo(x) ## S3 method for class 'list' as.multiPhylo(x) ## S3 method for class 'phyDat' as.multiPhylo(x) ## S3 method for class 'Splits' as.multiPhylo(x)
x |
Object to be converted |
as.multiPhylo
returns an object of class multiPhylo
as.multiPhylo.phyDat()
returns a list of trees, each corresponding
to the partitions implied by each non-ambiguous character in x
.
as.multiPhylo(BalancedTree(8)) as.multiPhylo(list(BalancedTree(8), PectinateTree(8))) data("Lobo") as.multiPhylo(Lobo.phy)
as.multiPhylo(BalancedTree(8)) as.multiPhylo(list(BalancedTree(8), PectinateTree(8))) data("Lobo") as.multiPhylo(Lobo.phy)
as.Newick()
creates a character string representation of a phylogenetic
tree, in the Newick format, using R's internal tip numbering.
Use RenumberTips()
to ensure that the internal numbering follows the
order you expect.
as.Newick(x) ## S3 method for class 'phylo' as.Newick(x) ## S3 method for class 'list' as.Newick(x) ## S3 method for class 'multiPhylo' as.Newick(x)
as.Newick(x) ## S3 method for class 'phylo' as.Newick(x) ## S3 method for class 'list' as.Newick(x) ## S3 method for class 'multiPhylo' as.Newick(x)
x |
Object to convert to Newick format. See Usage section for supported classes. |
as.Newick()
returns a character string representing tree
in Newick
format.
Martin R. Smith ([email protected])
Retain leaf labels: NewickTree()
Change R's internal numbering of leaves: RenumberTips()
Write tree to text or file: ape::write.tree()
trees <- list(BalancedTree(1:8), PectinateTree(8:1)) trees <- lapply(trees, RenumberTips, 1:8) as.Newick(trees)
trees <- list(BalancedTree(1:8), PectinateTree(8:1)) trees <- lapply(trees, RenumberTips, 1:8) as.Newick(trees)
A list of eleven Brewer palettes containing one to eleven colours that are readily distinguished by colourblind viewers, followed by a twelfth 12-colour palette adapted for colour blindness.
brewer
brewer
An object of class list
of length 12.
data("brewer", package="TreeTools") plot(0, type="n", xlim=c(1, 12), ylim=c(12, 1), xlab = "Colour", ylab="Palette") for (i in seq_along(brewer)) text(seq_len(i), i, col=brewer[[i]])
data("brewer", package="TreeTools") plot(0, type="n", xlim=c(1, 12), ylim=c(12, 1), xlab = "Colour", ylab="Palette") for (i in seq_along(brewer)) text(seq_len(i), i, col=brewer[[i]])
CharacterInformation()
calculates the cladistic information content
(Steel and Penny 2006) of a given character, in bits.
The total information in all characters gives a measure of the potential
utility of a dataset (Cotton and Wilkinson 2008), which can be
compared with a profile parsimony score (Faith and Trueman 2001) to
evaluate the degree of homoplasy within a dataset.
CharacterInformation(tokens)
CharacterInformation(tokens)
tokens |
Character vector specifying the tokens assigned to each taxon for
a character. Example: Note that ambiguous tokens such as |
CharacterInformation()
returns a numeric specifying the
phylogenetic information content of the character
(sensu Steel and Penny 2006), in bits.
Martin R. Smith ([email protected])
Cotton JA, Wilkinson M (2008).
“Quantifying the potential utility of phylogenetic characters.”
Taxon, 57(1), 131–136.
Faith DP, Trueman JWH (2001).
“Towards an inclusive philosophy for phylogenetic inference.”
Systematic Biology, 50(3), 331–350.
doi:10.1080/10635150118627.
Steel MA, Penny D (2006).
“Maximum parsimony and the phylogenetic information in multistate characters.”
In Albert VA (ed.), Parsimony, Phylogeny, and Genomics, 163–178.
Oxford University Press, Oxford.
Other split information functions:
SplitInformation()
,
SplitMatchProbability()
,
TreesMatchingSplit()
,
UnrootedTreesMatchingSplit()
CladeSizes()
reports the number of nodes in each clade in a tree.
CladeSizes(tree, internal = FALSE, nodes = NULL)
CladeSizes(tree, internal = FALSE, nodes = NULL)
tree |
A tree of class |
internal |
Logical specifying whether internal nodes should be counted towards the size of each clade. |
nodes |
Integer specifying indices of nodes at the base of clades whose sizes should be returned. If unspecified, counts will be provided for all nodes (including leaves). |
CladeSizes()
returns the number of nodes (including leaves) that
are descended from each node, not including the node itself.
Other tree navigation:
AncestorEdge()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- BalancedTree(6) plot(tree) ape::nodelabels() CladeSizes(tree, nodes = c(1, 8, 9))
tree <- BalancedTree(6) plot(tree) ape::nodelabels() CladeSizes(tree, nodes = c(1, 8, 9))
CladisticInfo()
calculates the cladistic (phylogenetic) information
content of a phylogenetic object, sensu Thorley et al. (1998).
CladisticInfo(x) PhylogeneticInfo(x) ## S3 method for class 'phylo' CladisticInfo(x) ## S3 method for class 'Splits' CladisticInfo(x) ## S3 method for class 'list' CladisticInfo(x) ## S3 method for class 'multiPhylo' CladisticInfo(x) PhylogeneticInformation(x) CladisticInformation(x)
CladisticInfo(x) PhylogeneticInfo(x) ## S3 method for class 'phylo' CladisticInfo(x) ## S3 method for class 'Splits' CladisticInfo(x) ## S3 method for class 'list' CladisticInfo(x) ## S3 method for class 'multiPhylo' CladisticInfo(x) PhylogeneticInformation(x) CladisticInformation(x)
x |
Tree of class |
The CIC is the logarithm of the number of binary trees that include the specified topology. A base two logarithm gives an information content in bits.
The CIC was originally proposed by Rohlf (1982), and formalised, with an information-theoretic justification, by Thorley et al. (1998). Steel and Penny (2006) term the equivalent quantity "phylogenetic information content" in the context of individual characters.
The number of binary trees consistent with a cladogram provides a more satisfactory measure of the resolution of a tree than simply counting the number of edges resolved (Page 1992).
CladisticInfo()
returns a numeric giving the cladistic information
content of the input tree(s), in bits.
If passed a Splits
object, it returns the information content of each
split in turn.
Martin R. Smith ([email protected])
Page RD (1992).
“Comments on the information content of classifications.”
Cladistics, 8(1), 87–95.
doi:10.1111/j.1096-0031.1992.tb00054.x.
Rohlf FJ (1982).
“Consensus indices for comparing classifications.”
Mathematical Biosciences, 59(1), 131–144.
doi:10.1016/0025-5564(82)90112-2.
Steel MA, Penny D (2006).
“Maximum parsimony and the phylogenetic information in multistate characters.”
In Albert VA (ed.), Parsimony, Phylogeny, and Genomics, 163–178.
Oxford University Press, Oxford.
Thorley JL, Wilkinson M, Charleston M (1998).
“The information content of consensus trees.”
In Rizzi A, Vichi M, Bock H (eds.), Advances in Data Science and Classification, 91–98.
Springer, Berlin.
ISBN 978-3-540-64641-9, doi:10.1007/978-3-642-72253-0.
Other tree information functions:
NRooted()
,
TreesMatchingTree()
Other tree characterization functions:
Consensus()
,
J1Index()
,
Stemwardness
,
TotalCopheneticIndex()
ClusterTable
as.ClusterTable()
converts a phylogenetic tree to a ClusterTable
object,
which is an internal representation of its splits suitable for rapid tree
distance calculation (per Day, 1985).
as.ClusterTable(x, tipLabels = NULL, ...) ## S3 method for class 'phylo' as.ClusterTable(x, tipLabels = NULL, ...) ## S3 method for class 'list' as.ClusterTable(x, tipLabels = NULL, ...) ## S3 method for class 'multiPhylo' as.ClusterTable(x, tipLabels = NULL, ...)
as.ClusterTable(x, tipLabels = NULL, ...) ## S3 method for class 'phylo' as.ClusterTable(x, tipLabels = NULL, ...) ## S3 method for class 'list' as.ClusterTable(x, tipLabels = NULL, ...) ## S3 method for class 'multiPhylo' as.ClusterTable(x, tipLabels = NULL, ...)
x |
Object to convert into |
tipLabels |
Character vector specifying sequence in which to order tip labels. |
... |
Presently unused. |
Each row of a cluster table relates to a clade on a tree rooted on tip 1.
Tips are numbered according to the order in which they are visited in
preorder: i.e., if plotted using plot(x)
, from the top of the page
downwards. A clade containing the tips 2 .. 5 would be denoted by the
entry 2, 5
, in either row 2 or row 5 of the cluster table.
as.ClusterTable()
returns an object of class ClusterTable
.
Martin R. Smith ([email protected])
Day WHE (1985). “Optimal algorithms for comparing trees with labeled leaves.” Journal of Classification, 2(1), 7–28. doi:10.1007/BF01908061.
S3 methods for ClusterTable
objects.
tree1 <- ape::read.tree(text = "(A, (B, (C, (D, E))));"); tree2 <- ape::read.tree(text = "(A, (B, (D, (C, E))));"); ct1 <- as.ClusterTable(tree1) summary(ct1) as.matrix(ct1) # Tip label order must match ct1 to allow comparison ct2 <- as.ClusterTable(tree2, tipLabels = LETTERS[1:5])
tree1 <- ape::read.tree(text = "(A, (B, (C, (D, E))));"); tree2 <- ape::read.tree(text = "(A, (B, (D, (C, E))));"); ct1 <- as.ClusterTable(tree1) summary(ct1) as.matrix(ct1) # Tip label order must match ct1 to allow comparison ct2 <- as.ClusterTable(tree2, tipLabels = LETTERS[1:5])
ClusterTable
objectsS3 methods for ClusterTable
objects.
## S3 method for class 'ClusterTable' as.matrix(x, ...) ## S3 method for class 'ClusterTable' print(x, ...) ## S3 method for class 'ClusterTable' summary(object, ...)
## S3 method for class 'ClusterTable' as.matrix(x, ...) ## S3 method for class 'ClusterTable' print(x, ...) ## S3 method for class 'ClusterTable' summary(object, ...)
x , object
|
Object of class |
... |
Additional arguments for consistency with S3 methods. |
Martin R. Smith ([email protected])
clustab <- as.ClusterTable(TreeTools::BalancedTree(6)) as.matrix(clustab) print(clustab) summary(clustab)
clustab <- as.ClusterTable(TreeTools::BalancedTree(6)) as.matrix(clustab) print(clustab) summary(clustab)
Collapses specified nodes or edges on a phylogenetic tree, resulting in polytomies.
CollapseNode(tree, nodes) ## S3 method for class 'phylo' CollapseNode(tree, nodes) CollapseEdge(tree, edges)
CollapseNode(tree, nodes) ## S3 method for class 'phylo' CollapseNode(tree, nodes) CollapseEdge(tree, edges)
tree |
A tree of class |
nodes , edges
|
Integer vector specifying the nodes or edges in the tree
to be dropped.
(Use |
CollapseNode()
and CollapseEdge()
return a tree of class phylo
,
corresponding to tree
with the specified nodes or edges collapsed.
The length of each dropped edge will (naively) be added to each descendant
edge.
Martin R. Smith
Other tree manipulation:
AddTip()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
oldPar <- par(mfrow = c(3, 1), mar = rep(0.5, 4)) tree <- as.phylo(898, 7) tree$edge.length <- 11:22 plot(tree) nodelabels() edgelabels() edgelabels(round(tree$edge.length, 2), cex = 0.6, frame = "n", adj = c(1, -1)) # Collapse by node number newTree <- CollapseNode(tree, c(12, 13)) plot(newTree) nodelabels() edgelabels(round(newTree$edge.length, 2), cex = 0.6, frame = "n", adj = c(1, -1)) # Collapse by edge number newTree <- CollapseEdge(tree, c(2, 4)) plot(newTree) par(oldPar)
oldPar <- par(mfrow = c(3, 1), mar = rep(0.5, 4)) tree <- as.phylo(898, 7) tree$edge.length <- 11:22 plot(tree) nodelabels() edgelabels() edgelabels(round(tree$edge.length, 2), cex = 0.6, frame = "n", adj = c(1, -1)) # Collapse by node number newTree <- CollapseNode(tree, c(12, 13)) plot(newTree) nodelabels() edgelabels(round(newTree$edge.length, 2), cex = 0.6, frame = "n", adj = c(1, -1)) # Collapse by edge number newTree <- CollapseEdge(tree, c(2, 4)) plot(newTree) par(oldPar)
Consensus()
calculates the consensus of a set of trees, using the
algorithm of (Day 1985).
Consensus(trees, p = 1, check.labels = TRUE)
Consensus(trees, p = 1, check.labels = TRUE)
trees |
List of trees, optionally of class |
p |
Proportion of trees that must contain a split for it to be reported
in the consensus. |
check.labels |
Logical specifying whether to check that all trees have
identical labels. Defaults to |
Consensus()
returns an object of class phylo
, rooted as in the
first entry of trees
.
Martin R. Smith ([email protected])
Day WHE (1985). “Optimal algorithms for comparing trees with labeled leaves.” Journal of Classification, 2(1), 7–28. doi:10.1007/BF01908061.
TreeDist::ConsensusInfo()
calculates the information content of a consensus
tree.
Other consensus tree functions:
ConsensusWithout()
,
RoguePlot()
Other tree characterization functions:
CladisticInfo()
,
J1Index()
,
Stemwardness
,
TotalCopheneticIndex()
Consensus(as.phylo(0:2, 8))
Consensus(as.phylo(0:2, 8))
ConsensusWithout()
displays a consensus plot with specified taxa excluded,
which can be a useful way to increase the resolution of a consensus tree
when a few wildcard taxa obscure a consistent set of relationships.
MarkMissing()
adds missing taxa as loose leaves on the plot.
ConsensusWithout(trees, tip = character(0), ...) ## S3 method for class 'phylo' ConsensusWithout(trees, tip = character(0), ...) ## S3 method for class 'multiPhylo' ConsensusWithout(trees, tip = character(0), ...) ## S3 method for class 'list' ConsensusWithout(trees, tip = character(0), ...) MarkMissing(tip, position = "bottomleft", ...)
ConsensusWithout(trees, tip = character(0), ...) ## S3 method for class 'phylo' ConsensusWithout(trees, tip = character(0), ...) ## S3 method for class 'multiPhylo' ConsensusWithout(trees, tip = character(0), ...) ## S3 method for class 'list' ConsensusWithout(trees, tip = character(0), ...) MarkMissing(tip, position = "bottomleft", ...)
trees |
A list of phylogenetic trees, of class |
tip |
A character vector specifying the names (or numbers) of tips to
drop (using |
... |
Additional parameters to pass on to |
position |
Where to plot the missing taxa.
See |
ConsensusWithout()
returns a consensus tree (of class phylo
)
without the excluded taxa.
MarkMissing()
provides a null return, after plotting the specified
tip
s as a legend.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
Other tree properties:
MatchEdges()
,
NSplits()
,
NTip()
,
NodeNumbers()
,
PathLengths()
,
SplitsInBinaryTree()
,
TipLabels()
,
TreeIsRooted()
Other consensus tree functions:
Consensus()
,
RoguePlot()
oldPar <- par(mfrow = c(1, 2), mar = rep(0.5, 4)) # Two trees differing only in placement of tip 2: trees <- as.phylo(c(0, 53), 6) plot(trees[[1]]) plot(trees[[2]]) # Strict consensus (left panel) lacks resolution: plot(ape::consensus(trees)) # But omitting tip two (right panel) reveals shared structure in common: plot(ConsensusWithout(trees, "t2")) MarkMissing("t2") par(oldPar)
oldPar <- par(mfrow = c(1, 2), mar = rep(0.5, 4)) # Two trees differing only in placement of tip 2: trees <- as.phylo(c(0, 53), 6) plot(trees[[1]]) plot(trees[[2]]) # Strict consensus (left panel) lacks resolution: plot(ape::consensus(trees)) # But omitting tip two (right panel) reveals shared structure in common: plot(ConsensusWithout(trees, "t2")) MarkMissing("t2") par(oldPar)
Constructs an approximation to a neighbour-joining tree, modified in order to be consistent with a constraint. Zero-length branches are collapsed at random.
ConstrainedNJ(dataset, constraint, weight = 1L, ratio = TRUE, ambig = "mean")
ConstrainedNJ(dataset, constraint, weight = 1L, ratio = TRUE, ambig = "mean")
dataset |
A phylogenetic data matrix of phangorn class |
constraint |
Either an object of class |
weight |
Numeric specifying degree to up-weight characters in
|
ambig , ratio
|
Settings of |
ConstrainedNJ()
returns a tree of class phylo
.
Martin R. Smith ([email protected])
Other tree generation functions:
GenerateTree
,
NJTree()
,
TreeNumber
,
TrivialTree
dataset <- MatrixToPhyDat(matrix( c(0, 1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 1), ncol = 2, dimnames = list(letters[1:6], NULL))) constraint <- MatrixToPhyDat( c(a = 0, b = 0, c = 0, d = 0, e = 1, f = 1)) plot(ConstrainedNJ(dataset, constraint))
dataset <- MatrixToPhyDat(matrix( c(0, 1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 1), ncol = 2, dimnames = list(letters[1:6], NULL))) constraint <- MatrixToPhyDat( c(a = 0, b = 0, c = 0, d = 0, e = 1, f = 1)) plot(ConstrainedNJ(dataset, constraint))
Decompose()
decomposes additive characters into a series of binary
characters, which is mathematically equivalent when analysed under
equal weights parsimony. (This equivalence is not exact
under implied weights or under probabilistic tree inference methods.)
Decompose(dataset, indices)
Decompose(dataset, indices)
dataset |
A phylogenetic data matrix of phangorn class |
indices |
Integer or logical vector specifying indices of characters that should be decomposed |
An ordered (additive) character can be rewritten as a mathematically equivalent hierarchy of binary neomorphic characters (Farris et al. 1970). Two reasons to prefer the latter approach are:
It makes explicit the evolutionary assumptions underlying an ordered character, whether the underlying ordering is linear, reticulate or branched (Mabee 1989).
It avoids having to identify characters requiring special treatment to phylogenetic software, which requires the maintenance of an up-to-date log of which characters are treated as additive and which sequence their states occur in, a step that may be overlooked by re-users of the data.
Careful consideration is warranted when evaluating whether a group of related characteristics ought to be treated as ordered (Wilkinson 1992). On the one hand, the 'principle of indifference' states that we should treat all transformations as equally probable (/ surprising / informative); ordered characters fail this test, as larger changes are treated as less probable than smaller ones. On the other hand, ordered characters allow more opportunities for homology of different character states, and might thus be defended under the auspices of Hennig’s Auxiliary Principle (Wilkinson 1992).
For a case study of how ordering phylogenetic characters can affect phylogenetic outcomes in practice, see Brady et al. (2024).
Decompose()
returns a phyDat
object in which the specified
ordered characters have been decomposed into binary characters.
The attribute originalIndex
lists the index of the character in
dataset
to which each element corresponds.
Martin R. Smith ([email protected])
Brady PL, Castrellon Arteaga A, López-Torres S, Springer MS (2024).
“The Effects of Ordered Multistate Morphological Characters on Phylogenetic Analyses of Eutherian Mammals.”
Journal of Mammalian Evolution, 31(3), 28.
doi:10.1007/s10914-024-09727-2.
Farris JS, Kluge AG, Eckardt MJ (1970).
“A Numerical Approach to Phylogenetic Systematics.”
Systematic Biology, 19(2), 172–189.
doi:10.2307/2412452.
Mabee PM (1989).
“Assumptions Underlying the Use of Ontogenetic Sequences for Determining Character State Order.”
Transactions of the American Fisheries Society, 118(2), 151–158.
doi:10.1577/1548-8659(1989)118<0151:AUTUOO>2.3.CO;2.
Wilkinson M (1992).
“Ordered versus Unordered Characters.”
Cladistics, 8(4), 375–385.
doi:10.1111/j.1096-0031.1992.tb00079.x.
Other phylogenetic matrix conversion functions:
MatrixToPhyDat()
,
StringToPhyDat()
data("Lobo") # Identify character 11 as additive # Character 11 will be replaced with two characters # The present codings 0, 1 and 2 will be replaced with 00, 10, and 11. decomposed <- Decompose(Lobo.phy, 11) NumberOfChars <- function(x) sum(attr(x, "weight")) NumberOfChars(Lobo.phy) # 115 characters in original NumberOfChars(decomposed) # 116 characters in decomposed
data("Lobo") # Identify character 11 as additive # Character 11 will be replaced with two characters # The present codings 0, 1 and 2 will be replaced with 00, 10, and 11. decomposed <- Decompose(Lobo.phy, 11) NumberOfChars <- function(x) sum(attr(x, "weight")) NumberOfChars(Lobo.phy) # 115 characters in original NumberOfChars(decomposed) # 116 characters in decomposed
DescendantEdges()
efficiently identifies edges that are "descended" from
edges in a tree.
DescendantTips()
efficiently identifies leaves (external nodes) that are
"descended" from edges in a tree.
DescendantEdges( parent, child, edge = NULL, node = NULL, nEdge = length(parent), includeSelf = TRUE ) DescendantTips(parent, child, edge = NULL, node = NULL, nEdge = length(parent)) AllDescendantEdges(parent, child, nEdge = length(parent))
DescendantEdges( parent, child, edge = NULL, node = NULL, nEdge = length(parent), includeSelf = TRUE ) DescendantTips(parent, child, edge = NULL, node = NULL, nEdge = length(parent)) AllDescendantEdges(parent, child, nEdge = length(parent))
parent |
Integer vector corresponding to the first column of the edge
matrix of a tree of class |
child |
Integer vector corresponding to the second column of the edge
matrix of a tree of class |
edge |
Integer specifying the number of the edge whose children are
required (see |
node |
Integer specifying the number(s) of nodes whose children are
required. Specify |
nEdge |
number of edges (calculated from |
includeSelf |
Logical specifying whether to mark |
DescendantEdges()
returns a logical vector stating whether each
edge in turn is the specified edge (if includeSelf = TRUE
)
or one of its descendants.
DescendantTips()
returns a logical vector stating whether each
leaf in turn is a descendant of the specified edge.
AllDescendantEdges()
is deprecated; use DescendantEdges()
instead.
It returns a matrix of class logical, with row N specifying whether each
edge is a descendant of edge N (or the edge itself).
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- as.phylo(0, 6) plot(tree) desc <- DescendantEdges(tree$edge[, 1], tree$edge[, 2], edge = 5) which(desc) ape::edgelabels(bg = 3 + desc) tips <- DescendantTips(tree$edge[, 1], tree$edge[, 2], edge = 5) which(tips) tiplabels(bg = 3 + tips)
tree <- as.phylo(0, 6) plot(tree) desc <- DescendantEdges(tree$edge[, 1], tree$edge[, 2], edge = 5) which(desc) ape::edgelabels(bg = 3 + desc) tips <- DescendantTips(tree$edge[, 1], tree$edge[, 2], edge = 5) which(tips) tiplabels(bg = 3 + tips)
Calculate the double factorial of a number, or its logarithm.
DoubleFactorial(n) DoubleFactorial64(n) LnDoubleFactorial(n) Log2DoubleFactorial(n) LogDoubleFactorial(n) LnDoubleFactorial.int(n) LogDoubleFactorial.int(n)
DoubleFactorial(n) DoubleFactorial64(n) LnDoubleFactorial(n) Log2DoubleFactorial(n) LogDoubleFactorial(n) LnDoubleFactorial.int(n) LogDoubleFactorial.int(n)
n |
Vector of integers. |
Returns the double factorial, n * (n - 2) * (n - 4) * (n - 6) * ...
DoubleFactorial64()
: Returns the exact double factorial as a 64-bit
integer64
, for n
< 34.
LnDoubleFactorial()
: Returns the logarithm of the double factorial.
Log2DoubleFactorial()
: Returns the logarithm of the double factorial.
LnDoubleFactorial.int()
: Slightly faster, when x is known to be length one
and below 50001
Martin R. Smith ([email protected])
Other double factorials:
doubleFactorials
,
logDoubleFactorials
DoubleFactorial (-4:0) # Return 1 if n < 2 DoubleFactorial (2) # 2 DoubleFactorial (5) # 1 * 3 * 5 exp(LnDoubleFactorial.int (8)) # log(2 * 4 * 6 * 8) DoubleFactorial64(31)
DoubleFactorial (-4:0) # Return 1 if n < 2 DoubleFactorial (2) # 2 DoubleFactorial (5) # 1 * 3 * 5 exp(LnDoubleFactorial.int (8)) # log(2 * 4 * 6 * 8) DoubleFactorial64(31)
A vector with pre-calculated values of double factorials up to 300!!, and the logarithms of double factorials up to 50 000!!.
doubleFactorials
doubleFactorials
An object of class numeric
of length 300.
301!! is too large to store as an integer; use logDoubleFactorials
instead.
Other double factorials:
DoubleFactorial()
,
logDoubleFactorials
DropTip()
removes specified leaves from a phylogenetic tree, collapsing
incident branches.
DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'phylo' DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'Splits' DropTip(tree, tip, preorder, check = TRUE) DropTipPhylo(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'multiPhylo' DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'list' DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class ''NULL'' DropTip(tree, tip, preorder = TRUE, check = TRUE) KeepTipPreorder(tree, tip) KeepTipPostorder(tree, tip) KeepTip(tree, tip, preorder = TRUE, check = TRUE)
DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'phylo' DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'Splits' DropTip(tree, tip, preorder, check = TRUE) DropTipPhylo(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'multiPhylo' DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class 'list' DropTip(tree, tip, preorder = TRUE, check = TRUE) ## S3 method for class ''NULL'' DropTip(tree, tip, preorder = TRUE, check = TRUE) KeepTipPreorder(tree, tip) KeepTipPostorder(tree, tip) KeepTip(tree, tip, preorder = TRUE, check = TRUE)
tree |
A tree of class |
tip |
Character vector specifying labels of leaves in tree to be dropped, or integer vector specifying the indices of leaves to be dropped. Specifying the index of an internal node will drop all descendants of that node. |
preorder |
Logical specifying whether to Preorder |
check |
Logical specifying whether to check validity of |
This function differs from ape::drop.tip()
, which roots unrooted trees,
and which can crash when trees' internal numbering follows unexpected schema.
DropTip()
returns a tree of class phylo
, with the requested
leaves removed. The edges of the tree will be numbered in preorder,
but their sequence may not conform to the conventions of Preorder()
.
KeepTip()
returns tree
with all leaves not in tip
removed,
in preorder.
DropTipPhylo()
: Direct call to DropTip.phylo()
, to avoid overhead of
querying object's class.
KeepTipPreorder()
: Faster version with no checks.
Does not retain labels or edge weights.
Edges must be listed in preorder.
May crash if improper input is specified.
KeepTipPostorder()
: Faster version with no checks.
Does not retain labels or edge weights.
Edges must be listed in postorder.
May crash if improper input is specified.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
Other split manipulation functions:
Subsplit()
,
TrivialSplits()
tree <- BalancedTree(9) plot(tree) plot(DropTip(tree, c("t5", "t6"))) unrooted <- UnrootTree(tree) plot(unrooted) plot(DropTip(unrooted, 4:5)) summary(DropTip(as.Splits(tree), 4:5))
tree <- BalancedTree(9) plot(tree) plot(DropTip(tree, c("t5", "t6"))) unrooted <- UnrootTree(tree) plot(unrooted) plot(DropTip(unrooted, 4:5)) summary(DropTip(as.Splits(tree), 4:5))
Wrapper for internal C++ function for maximum efficiency. Improper input may crash R. Behaviour not guaranteed. It is advisable to contact the package maintainers before relying on this function.
edge_to_splits( edge, edgeOrder, tipLabels = NULL, asSplits = TRUE, nTip = NTip(edge), ... )
edge_to_splits( edge, edgeOrder, tipLabels = NULL, asSplits = TRUE, nTip = NTip(edge), ... )
edge |
A matrix with two columns, with each row listing the parent and
child node of an edge in a phylogenetic tree. Property |
edgeOrder |
Integer vector such that |
tipLabels |
Character vector specifying sequence in which to order
tip labels. Label order must (currently) match to combine or compare separate
|
asSplits |
Logical specifying whether to return a |
nTip |
Integer specifying number of leaves in tree. |
... |
Presently unused. |
edge_to_splits()
uses the same return format as as.Splits()
.
as.Splits()
offers a safe access point to this
function that should be suitable for most users.
Quickly identify edges that are "ancestral" to a particular edge in a tree.
EdgeAncestry(edge, parent, child, stopAt = (parent == min(parent)))
EdgeAncestry(edge, parent, child, stopAt = (parent == min(parent)))
edge |
Integer specifying the number of the edge whose child edges should be returned. |
parent |
Integer vector corresponding to the first column of the edge
matrix of a tree of class |
child |
Integer vector corresponding to the second column of the edge
matrix of a tree of class |
stopAt |
Integer or logical vector specifying the edge(s) at which to terminate the search; defaults to the edges with the smallest parent, which will be the root edges if nodes are numbered Cladewise or in Preorder. |
EdgeAncestry()
returns a logical vector stating whether each edge
in turn is a descendant of the specified edge.
Martin R. Smith ([email protected])
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- PectinateTree(6) plot(tree) ape::edgelabels() parent <- tree$edge[, 1] child <- tree$edge[, 2] EdgeAncestry(7, parent, child) which(EdgeAncestry(7, parent, child, stopAt = 4))
tree <- PectinateTree(6) plot(tree) ape::edgelabels() parent <- tree$edge[, 1] child <- tree$edge[, 2] EdgeAncestry(7, parent, child) which(EdgeAncestry(7, parent, child, stopAt = 4))
Number of nodes that must be traversed to navigate from each edge to each other edge within a tree
EdgeDistances(tree)
EdgeDistances(tree)
tree |
A tree of class |
EdgeDistances()
returns a symmetrical matrix listing the number
of edges that must be traversed to travel from each numbered edge to each
other.
The two edges straddling the root of a rooted tree
are treated as a single edge. Add a "root" tip using AddTip()
if the
position of the root is significant.
Martin R. Smith ([email protected])
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- BalancedTree(5) plot(tree) ape::edgelabels() EdgeDistances(tree)
tree <- BalancedTree(5) plot(tree) ape::edgelabels() EdgeDistances(tree)
Add full stop to end of a sentence
EndSentence(string)
EndSentence(string)
string |
Input string |
EndSentence()
returns string
, punctuated with a final full stop
(period).'
Martin R. Smith
Other string parsing functions:
MorphoBankDecode()
,
RightmostCharacter()
,
Unquote()
EndSentence("Hello World") # "Hello World."
EndSentence("Hello World") # "Hello World."
Deprecated. This function will be removed in a future version of
TreeTools.
Use RootTree()
instead.
EnforceOutgroup(tree, outgroup) ## S3 method for class 'phylo' EnforceOutgroup(tree, outgroup) ## S3 method for class 'character' EnforceOutgroup(tree, outgroup)
EnforceOutgroup(tree, outgroup) ## S3 method for class 'phylo' EnforceOutgroup(tree, outgroup) ## S3 method for class 'character' EnforceOutgroup(tree, outgroup)
tree |
Either a tree of class |
outgroup |
Character vector containing the names of taxa to include in the outgroup. |
Given a tree or a list of taxa, EnforceOutgroup()
rearranged the ingroup
and outgroup taxa such that the two are sister taxa across the root, without
changing the relationships within the ingroup or within the outgroup.
EnforceOutgroup()
returned a tree of class phylo
where all
outgroup taxa are sister to all remaining taxa, without modifying the
ingroup topology.
Martin R. Smith ([email protected])
For a more robust implementation, see RootTree()
, which will
eventually replace this function
(#30).
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
RandomTree()
, PectinateTree()
, BalancedTree()
and StarTree()
generate trees with the specified shapes and leaf labels.
RandomTree(tips, root = FALSE, nodes) YuleTree(tips, addInTurn = FALSE, root = TRUE) PectinateTree(tips) BalancedTree(tips) StarTree(tips)
RandomTree(tips, root = FALSE, nodes) YuleTree(tips, addInTurn = FALSE, root = TRUE) PectinateTree(tips) BalancedTree(tips) StarTree(tips)
tips |
An integer specifying the number of tips, or a character vector
naming the tips, or any other object from which |
root |
Character or integer specifying tip to use as root;
or |
nodes |
Number of nodes to generate. The default and maximum,
|
addInTurn |
Logical specifying whether to add leaves in the order of
|
Each function returns an unweighted binary tree of class phylo
with
the specified leaf labels. Trees are rooted unless root = FALSE
.
RandomTree()
returns a topology drawn at random from the uniform
distribution (i.e. each binary tree is drawn with equal probability).
Trees are generated by inserting
each tip in term at a randomly selected edge in the tree.
Random numbers are generated using a Mersenne Twister.
If root = FALSE
, the tree will be unrooted, with the first tip in a
basal position. Otherwise, the tree will be rooted on root
.
YuleTree()
returns a topology generated by the Yule process
(Steel and McKenzie 2001),
i.e. adding leaves in turn adjacent to a randomly-chosen existing leaf.
PectinateTree()
returns a pectinate (caterpillar) tree.
BalancedTree()
returns a balanced (symmetrical) tree, in preorder.
StarTree()
returns a completely unresolved (star) tree.
Martin R. Smith ([email protected])
Steel MA, McKenzie A (2001). “Properties of Phylogenetic Trees Generated by Yule-type Speciation Models.” Mathematical Biosciences, 170(1), 91–112. doi:10.1016/S0025-5564(00)00061-4.()
Other tree generation functions:
ConstrainedNJ()
,
NJTree()
,
TreeNumber
,
TrivialTree
RandomTree(LETTERS[1:10]) data("Lobo") RandomTree(Lobo.phy) YuleTree(LETTERS[1:10]) plot(PectinateTree(LETTERS[1:10])) plot(BalancedTree(LETTERS[1:10])) plot(StarTree(LETTERS[1:10]))
RandomTree(LETTERS[1:10]) data("Lobo") RandomTree(Lobo.phy) YuleTree(LETTERS[1:10]) plot(PectinateTree(LETTERS[1:10])) plot(BalancedTree(LETTERS[1:10])) plot(StarTree(LETTERS[1:10]))
The Hamming distance between a pair of taxa is the number of characters with a different coding, i.e. the smallest number of evolutionary steps that must have occurred since their common ancestor.
Hamming( dataset, ratio = TRUE, ambig = c("median", "mean", "zero", "one", "na", "nan") )
Hamming( dataset, ratio = TRUE, ambig = c("median", "mean", "zero", "one", "na", "nan") )
dataset |
Object of class |
ratio |
Logical specifying whether to weight distance against maximum possible, given that a token that is ambiguous in either of two taxa cannot contribute to the total distance between the pair. |
ambig |
Character specifying value to return when a pair of taxa
have a zero maximum distance (perhaps due to a preponderance of ambiguous
tokens).
"median", the default, take the median of all other distance values;
"mean", the mean;
"zero" sets to zero; "one" to one;
"NA" to |
Tokens that contain the inapplicable state are treated as requiring no steps to transform into any applicable token.
Hamming()
returns an object of class dist
listing the Hamming
distance between each pair of taxa.
Martin R. Smith ([email protected])
Used to construct neighbour joining trees in NJTree()
.
dist.hamming()
in the phangorn package provides an alternative
implementation.
tokens <- matrix(c(0, 0, "0", 0, "?", 0, 0, "1", 0, 1, 0, 0, "1", 0, 1, 0, 0, "2", 0, 1, 1, 1, "-", "?", 0, 1, 1, "2", 1, "{01}"), nrow = 6, ncol = 5, byrow = TRUE, dimnames = list( paste0("Taxon_", LETTERS[1:6]), paste0("Char_", 1:5))) dataset <- MatrixToPhyDat(tokens) Hamming(dataset)
tokens <- matrix(c(0, 0, "0", 0, "?", 0, 0, "1", 0, 1, 0, 0, "1", 0, 1, 0, 0, "2", 0, 1, 1, 1, "-", "?", 0, 1, 1, "2", 1, "{01}"), nrow = 6, ncol = 5, byrow = TRUE, dimnames = list( paste0("Taxon_", LETTERS[1:6]), paste0("Char_", 1:5))) dataset <- MatrixToPhyDat(tokens) Hamming(dataset)
Modify a tree such that it matches a specified constraint.
This is at present a somewhat crude implementation that attempts to retain
much of the structure of tree
whilst guaranteeing compatibility with
each entry in constraint
.
ImposeConstraint(tree, constraint) AddUnconstrained(constraint, toAdd, asPhyDat = TRUE)
ImposeConstraint(tree, constraint) AddUnconstrained(constraint, toAdd, asPhyDat = TRUE)
tree |
A tree of class |
constraint |
Either an object of class |
toAdd |
Character vector specifying taxa to add to constraint. |
asPhyDat |
Logical: if |
ImposeConstraint()
returns a tree of class phylo
, consistent
with constraint
.
AddUnconstrained()
: Expand a constraint to include unconstrained
taxa.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
tips <- letters[1:9] tree <- as.phylo(1, 9, tips) plot(tree) constraint <- StringToPhyDat("0000?1111 000111111 0000??110", tips, FALSE) plot(ImposeConstraint(tree, constraint))
tips <- letters[1:9] tree <- as.phylo(1, 9, tips) plot(tree) constraint <- StringToPhyDat("0000?1111 000111111 0000??110", tips, FALSE) plot(ImposeConstraint(tree, constraint))
TreeNumber
object?Is an object a TreeNumber
object?
is.TreeNumber(x)
is.TreeNumber(x)
x |
R object. |
is.TreeNumber()
returns a logical vector of length one specifying
whether x
inherits the class "TreeNumber"
.
Martin R. Smith ([email protected])
Other 'TreeNumber' utilities:
TreeNumber
,
print.TreeNumber()
is.TreeNumber(FALSE) # FALSE is.TreeNumber(as.TreeNumber(BalancedTree(5))) # TRUE
is.TreeNumber(FALSE) # FALSE is.TreeNumber(as.TreeNumber(BalancedTree(5))) # TRUE
Calculate tree balance index J1
(when nonRootDominance = FALSE
) or
J1c
(when nonRootDominance = TRUE
) from Lemant J, Le Sueur C, Manojlović V, Noble R (2022).
“Robust, Universal Tree Balance Indices.”
Systematic Biology, 71(5), 1210–1224.
doi:10.1093/sysbio/syac027..
J1Index(tree, q = 1, nonRootDominance = FALSE) JQIndex(tree, q = 1, nonRootDominance = FALSE)
J1Index(tree, q = 1, nonRootDominance = FALSE) JQIndex(tree, q = 1, nonRootDominance = FALSE)
tree |
Either an object of class 'phylo', or a dataframe with column
names Parent, Identity and (optionally) Population.
The latter is similar to |
q |
Numeric between zero and one specifying sensitivity to type
frequencies. If |
nonRootDominance |
Logical specifying whether to use non-root dominance factor. |
If population sizes are not provided, then the function assigns size 0 to internal nodes, and size 1 to leaves.
Rob Noble, adapted by Martin R. Smith
Lemant J, Le Sueur C, Manojlović V, Noble R (2022). “Robust, Universal Tree Balance Indices.” Systematic Biology, 71(5), 1210–1224. doi:10.1093/sysbio/syac027.
Other tree characterization functions:
CladisticInfo()
,
Consensus()
,
Stemwardness
,
TotalCopheneticIndex()
# Using phylo object as input: phylo_tree <- read.tree(text="((a:0.1)A:0.5,(b1:0.2,b2:0.1)B:0.2);") J1Index(phylo_tree) phylo_tree2 <- read.tree(text='((A, B), ((C, D), (E, F)));') J1Index(phylo_tree2) # Using edges lists as input: tree1 <- data.frame(Parent = c(1, 1, 1, 1, 2, 3, 4), Identity = 1:7, Population = c(1, rep(5, 6))) J1Index(tree1) tree2 <- data.frame(Parent = c(1, 1, 1, 1, 2, 3, 4), Identity = 1:7, Population = c(rep(0, 4), rep(1, 3))) J1Index(tree2) tree3 <- data.frame(Parent = c(1, 1, 1, 1, 2, 3, 4), Identity = 1:7, Population = c(0, rep(1, 3), rep(0, 3))) J1Index(tree3) cat_tree <- data.frame(Parent = c(1, 1:14, 1:15, 15), Identity = 1:31, Population = c(rep(0, 15), rep(1, 16))) J1Index(cat_tree) # If population sizes are omitted then internal nodes are assigned population # size zero and leaves are assigned population size one: sym_tree1 <- data.frame(Parent = c(1, rep(1:15, each = 2)), Identity = 1:31, Population = c(rep(0, 15), rep(1, 16))) # Equivalently: sym_tree2 <- data.frame(Parent = c(1, rep(1:15, each = 2)), Identity = 1:31) J1Index(sym_tree1) J1Index(sym_tree2)
# Using phylo object as input: phylo_tree <- read.tree(text="((a:0.1)A:0.5,(b1:0.2,b2:0.1)B:0.2);") J1Index(phylo_tree) phylo_tree2 <- read.tree(text='((A, B), ((C, D), (E, F)));') J1Index(phylo_tree2) # Using edges lists as input: tree1 <- data.frame(Parent = c(1, 1, 1, 1, 2, 3, 4), Identity = 1:7, Population = c(1, rep(5, 6))) J1Index(tree1) tree2 <- data.frame(Parent = c(1, 1, 1, 1, 2, 3, 4), Identity = 1:7, Population = c(rep(0, 4), rep(1, 3))) J1Index(tree2) tree3 <- data.frame(Parent = c(1, 1, 1, 1, 2, 3, 4), Identity = 1:7, Population = c(0, rep(1, 3), rep(0, 3))) J1Index(tree3) cat_tree <- data.frame(Parent = c(1, 1:14, 1:15, 15), Identity = 1:31, Population = c(rep(0, 15), rep(1, 16))) J1Index(cat_tree) # If population sizes are omitted then internal nodes are assigned population # size zero and leaves are assigned population size one: sym_tree1 <- data.frame(Parent = c(1, rep(1:15, each = 2)), Identity = 1:31, Population = c(rep(0, 15), rep(1, 16))) # Equivalently: sym_tree2 <- data.frame(Parent = c(1, rep(1:15, each = 2)), Identity = 1:31) J1Index(sym_tree1) J1Index(sym_tree2)
Lists which paths present in a master tree are present when leaves are dropped.
KeptPaths(paths, keptVerts, all = TRUE) ## S3 method for class 'data.frame' KeptPaths(paths, keptVerts, all = TRUE) ## S3 method for class 'matrix' KeptPaths(paths, keptVerts, all = TRUE)
KeptPaths(paths, keptVerts, all = TRUE) ## S3 method for class 'data.frame' KeptPaths(paths, keptVerts, all = TRUE) ## S3 method for class 'matrix' KeptPaths(paths, keptVerts, all = TRUE)
paths |
|
keptVerts |
Logical specifying whether each entry is retained in the
reduced tree, perhaps generated using |
all |
Logical: if |
KeptPaths()
returns a logical vector specifying whether each path
in paths
occurs when keptVerts
vertices are retained.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
master <- BalancedTree(9) paths <- PathLengths(master) keptTips <- c(1, 5, 7, 9) keptVerts <- KeptVerts(master, keptTips) KeptPaths(paths, keptVerts) paths[KeptPaths(paths, keptVerts, all = FALSE), ]
master <- BalancedTree(9) paths <- PathLengths(master) keptTips <- c(1, 5, 7, 9) keptVerts <- KeptVerts(master, keptTips) KeptPaths(paths, keptVerts) paths[KeptPaths(paths, keptVerts, all = FALSE), ]
Identify vertices retained when leaves are dropped
KeptVerts(tree, keptTips, tipLabels = TipLabels(tree)) ## S3 method for class 'phylo' KeptVerts(tree, keptTips, tipLabels = TipLabels(tree)) ## S3 method for class 'numeric' KeptVerts(tree, keptTips, tipLabels = TipLabels(tree))
KeptVerts(tree, keptTips, tipLabels = TipLabels(tree)) ## S3 method for class 'phylo' KeptVerts(tree, keptTips, tipLabels = TipLabels(tree)) ## S3 method for class 'numeric' KeptVerts(tree, keptTips, tipLabels = TipLabels(tree))
tree |
Original tree of class |
keptTips |
Either:
|
tipLabels |
Optional character vector naming the leaves of |
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
master <- BalancedTree(12) master <- Preorder(master) # Nodes must be listed in Preorder sequence plot(master) nodelabels() allTips <- master[["tip.label"]] keptTips <- sample(allTips, 8) plot(KeepTip(master, keptTips)) kept <- KeptVerts(master, allTips %in% keptTips) map <- which(kept) # Node `i` in the reduced tree corresponds to node `map[i]` in the original.
master <- BalancedTree(12) master <- Preorder(master) # Nodes must be listed in Preorder sequence plot(master) nodelabels() allTips <- master[["tip.label"]] keptTips <- sample(allTips, 8) plot(KeepTip(master, keptTips)) kept <- KeptVerts(master, allTips %in% keptTips) map <- which(kept) # Node `i` in the reduced tree corresponds to node `map[i]` in the original.
Labels the edges associated with each split on a plotted tree.
LabelSplits(tree, labels = NULL, unit = "", ...)
LabelSplits(tree, labels = NULL, unit = "", ...)
tree |
A tree of class |
labels |
Named vector listing annotations for each split. Names
should correspond to the node associated with each split; see
|
unit |
Character specifying units of |
... |
Additional parameters to |
As the two root edges of a rooted tree denote the same split, only the
rightmost (plotted at the bottom, by default) edge will be labelled.
If the position of the root is significant, add a tip at the root using
AddTip()
.
LabelSplits()
returns invisible()
, after plotting labels
on
each relevant edge of a plot (which should already have been produced using
plot(tree)
).
Calculate split support: SplitFrequency()
Colour labels according to value: SupportColour()
Other Splits operations:
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
tree <- BalancedTree(LETTERS[1:5]) splits <- as.Splits(tree) plot(tree) LabelSplits(tree, as.character(splits), frame = "none", pos = 3L) LabelSplits(tree, TipsInSplits(splits), unit = " tips", frame = "none", pos = 1L) # An example forest of 100 trees, some identical forest <- as.phylo(c(1, rep(10, 79), rep(100, 15), rep(1000, 5)), nTip = 9) # Generate an 80% consensus tree cons <- ape::consensus(forest, p = 0.8) plot(cons) # Calculate split frequencies splitFreqs <- SplitFrequency(cons, forest) # Optionally, colour edges by corresponding frequency. # Note that not all edges are associated with a unique split # (and two root edges may be associated with one split - not handled here) edgeSupport <- rep(1, nrow(cons$edge)) # Initialize trivial splits to 1 childNode <- cons$edge[, 2] edgeSupport[match(names(splitFreqs), childNode)] <- splitFreqs / 100 plot(cons, edge.col = SupportColour(edgeSupport), edge.width = 3) # Annotate nodes by frequency LabelSplits(cons, splitFreqs, unit = "%", col = SupportColor(splitFreqs / 100), frame = "none", pos = 3L)
tree <- BalancedTree(LETTERS[1:5]) splits <- as.Splits(tree) plot(tree) LabelSplits(tree, as.character(splits), frame = "none", pos = 3L) LabelSplits(tree, TipsInSplits(splits), unit = " tips", frame = "none", pos = 1L) # An example forest of 100 trees, some identical forest <- as.phylo(c(1, rep(10, 79), rep(100, 15), rep(1000, 5)), nTip = 9) # Generate an 80% consensus tree cons <- ape::consensus(forest, p = 0.8) plot(cons) # Calculate split frequencies splitFreqs <- SplitFrequency(cons, forest) # Optionally, colour edges by corresponding frequency. # Note that not all edges are associated with a unique split # (and two root edges may be associated with one split - not handled here) edgeSupport <- rep(1, nrow(cons$edge)) # Initialize trivial splits to 1 childNode <- cons$edge[, 2] edgeSupport[match(names(splitFreqs), childNode)] <- splitFreqs / 100 plot(cons, edge.col = SupportColour(edgeSupport), edge.width = 3) # Annotate nodes by frequency LabelSplits(cons, splitFreqs, unit = "%", col = SupportColor(splitFreqs / 100), frame = "none", pos = 3L)
LeafLabelInterchange()
exchanges the position of leaves within a tree.
LeafLabelInterchange(tree, n = 2L)
LeafLabelInterchange(tree, n = 2L)
tree |
A tree of class |
n |
Integer specifying number of leaves whose positions should be exchanged. |
Modifies a tree by switching the positions of n leaves. To avoid later swaps undoing earlier exchanges, all n leaves are guaranteed to change position. Note, however, that no attempt is made to avoid swapping equivalent leaves, for example, a pair that are each others' closest relatives. As such, the relationships within a tree are not guaranteed to be changed.
LeafLabelInterchange()
returns a tree of class phylo
on which
the position of n
leaves have been exchanged.
The tree's internal topology will not change.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
tree <- PectinateTree(8) plot(LeafLabelInterchange(tree, 3L))
tree <- PectinateTree(8) plot(LeafLabelInterchange(tree, 3L))
ListAncestors()
reports all ancestors of a given node.
ListAncestors(parent, child, node = NULL) AllAncestors(parent, child)
ListAncestors(parent, child, node = NULL) AllAncestors(parent, child)
parent |
Integer vector corresponding to the first column of the edge
matrix of a tree of class |
child |
Integer vector corresponding to the second column of the edge
matrix of a tree of class |
node |
Integer giving the index of the node or tip whose ancestors are
required, or |
Note that if node = NULL
, the tree's edges must be listed such that each
internal node (except the root) is listed as a child before it is listed
as a parent, i.e. its index in child
is less than its index in parent
.
This will be true of trees listed in Preorder.
If node = NULL
, ListAncestors()
returns a list. Each entry i contains
a vector containing, in order, the nodes encountered when traversing the tree
from node i to the root node.
The last entry of each member of the list is therefore the root node,
with the exception of the entry for the root node itself, which is a
zero-length integer.
If node
is an integer, ListAncestors()
returns a vector of the numbers of
the nodes ancestral to the given node
, including the root node.
AllAncestors()
: Alias for ListAncestors(node = NULL)
.
Martin R. Smith ([email protected])
Implemented less efficiently in phangorn:::Ancestors
, on which this
code is based.
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- PectinateTree(5) edge <- tree[["edge"]] # Identify desired node with: plot(tree) nodelabels() tiplabels() # Ancestors of specific nodes: ListAncestors(edge[, 1], edge[, 2], 4L) ListAncestors(edge[, 1], edge[, 2], 8L) # Ancestors of each node, if tree numbering system is uncertain: lapply(seq_len(max(edge)), ListAncestors, parent = edge[, 1], child = edge[, 2]) # Ancestors of each node, if tree is in preorder: ListAncestors(edge[, 1], edge[, 2]) # Alias: AllAncestors(edge[, 1], edge[, 2])
tree <- PectinateTree(5) edge <- tree[["edge"]] # Identify desired node with: plot(tree) nodelabels() tiplabels() # Ancestors of specific nodes: ListAncestors(edge[, 1], edge[, 2], 4L) ListAncestors(edge[, 1], edge[, 2], 8L) # Ancestors of each node, if tree numbering system is uncertain: lapply(seq_len(max(edge)), ListAncestors, parent = edge[, 1], child = edge[, 2]) # Ancestors of each node, if tree is in preorder: ListAncestors(edge[, 1], edge[, 2]) # Alias: AllAncestors(edge[, 1], edge[, 2])
Phylogenetic data from Zhang et al. (2016) in raw
(Lobo.data
) and phyDat
(Lobo.phy
) formats.
Lobo.data Lobo.phy
Lobo.data Lobo.phy
An object of class list
of length 48.
An object of class phyDat
of length 48.
Zhang et al. (2016)
Zhang X, Smith MR, Yang J, Hou J (2016). “Onychophoran-like musculature in a phosphatized Cambrian lobopodian.” Biology Letters, 12(9), 20160492. doi:10.1098/rsbl.2016.0492.
data("Lobo", package = "TreeTools") Lobo.data Lobo.phy
data("Lobo", package = "TreeTools") Lobo.data Lobo.phy
logDoubleFactorials
is a numeric vector with pre-calculated values of
double factorials up to 50 000!!.
logDoubleFactorials
logDoubleFactorials
An object of class numeric
of length 50000.
Other double factorials:
DoubleFactorial()
,
doubleFactorials
MakeTreeBinary()
resolves, at random, all polytomies in a tree or set of
trees, such that all trees compatible with the input topology are drawn
with equal probability.
MakeTreeBinary(tree)
MakeTreeBinary(tree)
tree |
A tree of class |
MakeTreeBinary()
returns a rooted binary tree of class phylo
,
corresponding to tree uniformly selected from all those compatible with
the input tree topologies.
Martin R. Smith ([email protected])
Since ape v5.5, this functionality is available through
ape::multi2di()
; previous versions of "ape" did not return topologies
in equal frequencies.
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
MakeTreeBinary(CollapseNode(PectinateTree(7), c(9, 11, 13))) UnrootTree(MakeTreeBinary(StarTree(5)))
MakeTreeBinary(CollapseNode(PectinateTree(7), c(9, 11, 13))) UnrootTree(MakeTreeBinary(StarTree(5)))
match()
returns a vector of the positions of (first) matches of splits in
its first argument in its second.
%in%
is a more intuitive interface as a binary operator, which returns
a logical vector indicating whether there is a match or not for each
split in its left operand.
## S4 method for signature 'Splits,Splits' match(x, table, nomatch = NA_integer_, incomparables = NULL) in.Splits(x, table) match(x, table, nomatch = NA_integer_, incomparables = NULL) ## S4 method for signature 'Splits,Splits' x %in% table
## S4 method for signature 'Splits,Splits' match(x, table, nomatch = NA_integer_, incomparables = NULL) in.Splits(x, table) match(x, table, nomatch = NA_integer_, incomparables = NULL) ## S4 method for signature 'Splits,Splits' x %in% table
x , table
|
Object of class |
nomatch |
Integer value that will be used in place of |
incomparables |
Ignored. (Included for consistency with generic.) |
in.Splits()
is an alias for %in%
, included for backwards compatibility.
It is deprecated and will be removed in a future release.
match()
returns an integer vector specifying the position in
table
that matches each element in x
, or nomatch
if no match is found.
Corresponding base functions are documented in
match()
.
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
xor()
splits1 <- as.Splits(BalancedTree(7)) splits2 <- as.Splits(PectinateTree(7)) match(splits1, splits2)
splits1 <- as.Splits(BalancedTree(7)) splits2 <- as.Splits(PectinateTree(7)) match(splits1, splits2)
MatchNodes()
and MatchEdges()
matches nodes or edges in one tree to
entries in the second that denote a clade with identical tip labels.
MatchEdges(x, table, nomatch = NA_integer_) MatchNodes(x, table, nomatch = NA_integer_, tips = FALSE)
MatchEdges(x, table, nomatch = NA_integer_) MatchNodes(x, table, nomatch = NA_integer_, tips = FALSE)
x |
Tree whose nodes are to be matched. |
table |
Tree containing nodes to be matched against. |
nomatch |
Integer value that will be used in place of |
tips |
Logical specifying whether to return matches for tips;
unless |
The current implementation is potentially inefficient. Please contact the maintainer to request a more efficient implementation if this function is proving a bottleneck.
Martin R. Smith ([email protected])
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
Other tree properties:
ConsensusWithout()
,
NSplits()
,
NTip()
,
NodeNumbers()
,
PathLengths()
,
SplitsInBinaryTree()
,
TipLabels()
,
TreeIsRooted()
MatchNodes(BalancedTree(8), RootTree(BalancedTree(8)))
MatchNodes(BalancedTree(8), RootTree(BalancedTree(8)))
phyDat
objectsMatrixToPhyDat()
converts a matrix of tokens to a phyDat
object;
PhyDatToMatrix()
converts a phyDat
object to a matrix of tokens.
MatrixToPhyDat(tokens) PhyDatToMatrix( dataset, ambigNA = FALSE, inappNA = ambigNA, parentheses = c("{", "}"), sep = "" )
MatrixToPhyDat(tokens) PhyDatToMatrix( dataset, ambigNA = FALSE, inappNA = ambigNA, parentheses = c("{", "}"), sep = "" )
tokens |
Matrix of tokens, possibly created with |
dataset |
A dataset of class |
ambigNA , inappNA
|
Logical specifying whether to denote ambiguous /
inapplicable characters as |
parentheses |
Character vector specifying style of parentheses
with which to enclose ambiguous characters. |
sep |
Character with which to separate ambiguous tokens, e.g. |
MatrixToPhyDat()
returns an object of class phyDat
.
PhyDatToMatrix()
returns a matrix corresponding to the
uncompressed character states within a phyDat
object.
Martin R. Smith ([email protected])
Other phylogenetic matrix conversion functions:
Decompose()
,
StringToPhyDat()
tokens <- matrix(c(0, 0, "0", 0, 0, 0, 0, "1", 0, 1, 0, 0, "1", 0, 1, 0, 0, "2", 0, 1, 1, 1, "-", 1, 0, 1, 1, "2", 1, "{01}"), nrow = 6, ncol = 5, byrow = TRUE, dimnames = list( paste0("Taxon_", LETTERS[1:6]), paste0("Char_", 1:5))) MatrixToPhyDat(tokens) data("Lobo", package = "TreeTools") head(PhyDatToMatrix(Lobo.phy)[, 91:93])
tokens <- matrix(c(0, 0, "0", 0, 0, 0, 0, "1", 0, 1, 0, 0, "1", 0, 1, 0, 0, "2", 0, 1, 1, 1, "-", 1, 0, 1, 1, "2", 1, "{01}"), nrow = 6, ncol = 5, byrow = TRUE, dimnames = list( paste0("Taxon_", LETTERS[1:6]), paste0("Char_", 1:5))) MatrixToPhyDat(tokens) data("Lobo", package = "TreeTools") head(PhyDatToMatrix(Lobo.phy)[, 91:93])
Converts strings from MorphoBank notes into a Latex-compatible format.
MorphoBankDecode(string)
MorphoBankDecode(string)
string |
String to process |
MorphoBankDecode()
returns a string with new lines and punctuation
reformatted.
Martin R. Smith
Other string parsing functions:
EndSentence()
,
RightmostCharacter()
,
Unquote()
MRCA()
calculates the last common ancestor of specified nodes.
MRCA(x1, x2, ancestors)
MRCA(x1, x2, ancestors)
x1 , x2
|
Integer specifying index of leaves or nodes whose most recent common ancestor should be found. |
ancestors |
List of ancestors for each node in a tree. Perhaps
produced by |
MRCA()
requires that node values within a tree increase away from the root,
which will be true of trees listed in Preorder
.
No warnings will be given if trees do not fulfil this requirement.
MRCA()
returns an integer specifying the node number of the last
common ancestor of x1
and x2
.
Martin R. Smith ([email protected])
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- BalancedTree(7) # Verify that node numbering increases away from root plot(tree) nodelabels() # ListAncestors expects a tree in Preorder tree <- Preorder(tree) edge <- tree$edge ancestors <- ListAncestors(edge[, 1], edge[, 2]) MRCA(1, 4, ancestors) # If a tree must be in postorder, use: tree <- Postorder(tree) edge <- tree$edge ancestors <- lapply(seq_len(max(edge)), ListAncestors, parent = edge[, 1], child = edge[, 2])
tree <- BalancedTree(7) # Verify that node numbering increases away from root plot(tree) nodelabels() # ListAncestors expects a tree in Preorder tree <- Preorder(tree) edge <- tree$edge ancestors <- ListAncestors(edge[, 1], edge[, 2]) MRCA(1, 4, ancestors) # If a tree must be in postorder, use: tree <- Postorder(tree) edge <- tree$edge ancestors <- lapply(seq_len(max(edge)), ListAncestors, parent = edge[, 1], child = edge[, 2])
Calculate or plot the minimum spanning tree (Gower and Ross 1969) of a distance matrix.
MSTEdges(distances, plot = FALSE, x = NULL, y = NULL, ...) MSTLength(distances, mst = NULL)
MSTEdges(distances, plot = FALSE, x = NULL, y = NULL, ...) MSTLength(distances, mst = NULL)
distances |
Either a matrix that can be interpreted as a distance
matrix, or an object of class |
plot |
Logical specifying whether to add the minimum spanning tree to an existing plot. |
x , y
|
Numeric vectors specifying the X and Y coordinates of each
element in |
... |
Additional parameters to send to |
mst |
Optional parameter specifying the minimum spanning tree in the
format returned by |
MSTEdges()
returns a matrix in which each row corresponds to an
edge of the minimum spanning tree, listed in non-decreasing order of length.
The two columns contain the indices of the entries in distances
that
each edge connects, with the lower value listed first.
MSTLength()
returns the length of the minimum spanning tree.
Martin R. Smith ([email protected])
Gower JC, Ross GJS (1969). “Minimum spanning trees and single linkage cluster analysis.” Journal of the Royal Statistical Society. Series C (Applied Statistics), 18(1), 54–64. doi:10.2307/2346439.
Slow implementation returning the association matrix of the minimum spanning
tree: ape::mst()
.
# Corners of an almost-regular octahedron points <- matrix(c(0, 0, 2, 2, 1.1, 1, 0, 2, 0, 2, 1, 1.1, 0, 0, 0, 0, 1, -1), 6) distances <- dist(points) mst <- MSTEdges(distances) MSTLength(distances, mst) plot(points[, 1:2], ann = FALSE, asp = 1) MSTEdges(distances, TRUE, x = points[, 1], y = points[, 2], lwd = 2)
# Corners of an almost-regular octahedron points <- matrix(c(0, 0, 2, 2, 1.1, 1, 0, 2, 0, 2, 1, 1.1, 0, 0, 0, 0, 1, -1), 6) distances <- dist(points) mst <- MSTEdges(distances) MSTLength(distances, mst) plot(points[, 1:2], ann = FALSE, asp = 1) MSTEdges(distances, TRUE, x = points[, 1], y = points[, 2], lwd = 2)
N1Spr()
calculates the number of trees one subtree prune-and-regraft
operation away from a binary input tree using the formula given by
Allen and Steel (2001);
IC1Spr()
calculates the information content of trees at this
distance: i.e. the entropy corresponding to the proportion of all possible
n-tip trees whose SPR distance is at most one from a specified tree.
N1Spr(n) IC1Spr(n)
N1Spr(n) IC1Spr(n)
n |
Integer vector specifying the number of tips in a tree. |
N1Spr()
returns an integer vector denoting the number of trees one
SPR rearrangement away from the input tree..
IC1Spr()
returns an numeric vector giving the phylogenetic
information content of trees 0 or 1 SPR rearrangement from an n-leaf tree,
in bits.
Allen BL, Steel MA (2001). “Subtree transfer operations and their induced metrics on evolutionary trees.” Annals of Combinatorics, 5(1), 1–15. doi:10.1007/s00026-001-8006-8.
N1Spr(4:6) IC1Spr(5)
N1Spr(4:6) IC1Spr(5)
NDescendants()
counts the number of nodes (including leaves) directly
descended from each node in a tree.
NDescendants(tree)
NDescendants(tree)
tree |
A tree of class |
NDescendants()
returns an integer listing the number of direct
descendants (leaves or internal nodes) for each node in a tree.
Martin R. Smith ([email protected])
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- CollapseNode(BalancedTree(8), 12:15) NDescendants(tree) plot(tree) nodelabels(NDescendants(tree))
tree <- CollapseNode(BalancedTree(8), 12:15) NDescendants(tree) plot(tree) nodelabels(NDescendants(tree))
NewickTree()
encodes a tree as a Newick-format string.
This differs from write.tree()
in the encoding of
spaces as spaces, rather than underscores.
NewickTree(tree)
NewickTree(tree)
tree |
A tree of class |
NewickTree()
returns a character string denoting tree
in Newick
format.
Use tip numbers, rather than leaf labels: as.Newick
NewickTree(BalancedTree(LETTERS[4:9]))
NewickTree(BalancedTree(LETTERS[4:9]))
NJTree()
generates a rooted neighbour joining tree from a phylogenetic
dataset.
NJTree(dataset, edgeLengths = FALSE, ratio = TRUE, ambig = "mean")
NJTree(dataset, edgeLengths = FALSE, ratio = TRUE, ambig = "mean")
dataset |
A phylogenetic data matrix of phangorn class |
edgeLengths |
Logical specifying whether to include edge lengths. |
ambig , ratio
|
Settings of |
NJTree
returns an object of class phylo
.
Martin R. Smith ([email protected])
Other tree generation functions:
ConstrainedNJ()
,
GenerateTree
,
TreeNumber
,
TrivialTree
data("Lobo") NJTree(Lobo.phy)
data("Lobo") NJTree(Lobo.phy)
NodeDepth()
evaluates how "deep" each node is within a tree.
NodeDepth(x, shortest = FALSE, includeTips = TRUE)
NodeDepth(x, shortest = FALSE, includeTips = TRUE)
x |
A tree of class |
shortest |
Logical specifying whether to calculate the length of the
shortest away-from-root path to a leaf. If |
includeTips |
Logical specifying whether to include leaves (each of depth zero) in return value. |
For a rooted tree, the depth of a node is the minimum (if shortest = TRUE
)
or maximum (shortest = FALSE
) number of edges that must be traversed,
moving away from the root, to reach a leaf.
Unrooted trees are treated as if a root node occurs in the "middle" of the tree, meaning the position that will minimise the maximum node depth.
NodeDepth()
returns an integer vector specifying the depth of
each external and internal node in x
.
Martin R. Smith ([email protected])
ape::node.depth
returns the number of tips descended from a
node.
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeNumbers()
,
NodeOrder()
,
RootNode()
tree <- CollapseNode(BalancedTree(10), c(12:13, 19)) plot(tree) nodelabels(NodeDepth(tree, includeTips = FALSE))
tree <- CollapseNode(BalancedTree(10), c(12:13, 19)) plot(tree) nodelabels(NodeDepth(tree, includeTips = FALSE))
NodeNumbers()
returns a sequence corresponding to the nodes in a treeNumeric index of each node in a tree
NodeNumbers()
returns a sequence corresponding to the nodes in a tree
NodeNumbers(tree, tips = FALSE)
NodeNumbers(tree, tips = FALSE)
tree |
A tree of class |
tips |
Logical specifying whether to also include the indices of leaves. |
NodeNumbers()
returns an integer vector corresponding to the
indices of nodes within a tree.
Martin R. Smith ([email protected])
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NSplits()
,
NTip()
,
PathLengths()
,
SplitsInBinaryTree()
,
TipLabels()
,
TreeIsRooted()
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeOrder()
,
RootNode()
NodeOrder()
calculates the order of each node: the number of edges
incident to it in a tree.
This value includes the root edge in rooted trees.
NodeOrder(x, includeAncestor = TRUE, internalOnly = FALSE)
NodeOrder(x, includeAncestor = TRUE, internalOnly = FALSE)
x |
A tree of class |
includeAncestor |
Logical specifying whether to count edge leading to ancestral node in calculation of order. |
internalOnly |
Logical specifying whether to restrict to results
to internal nodes, i.e. to omit leaves. Irrelevant if
|
NodeOrder()
returns an integer listing the order of each node;
entries are named with the number of each node.
Martin R. Smith ([email protected])
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
RootNode()
tree <- CollapseNode(BalancedTree(8), 12:15) NodeOrder(tree) plot(tree) nodelabels(NodeOrder(tree, internalOnly = TRUE))
tree <- CollapseNode(BalancedTree(8), 12:15) NodeOrder(tree) plot(tree) nodelabels(NodeOrder(tree, internalOnly = TRUE))
NPartitionPairs()
calculates the number of terminal arrangements matching
a specified configuration of two splits.
NPartitionPairs(configuration)
NPartitionPairs(configuration)
configuration |
Integer vector of length four specifying the number of terminals that occur in both (1) splits A1 and A2; (2) splits A1 and B2; (3) splits B1 and A2; (4) splits B1 and B2. |
Consider splits that divide eight terminals, labelled A to H.
Bipartition 1: | ABCD:EFGH | A1 = ABCD | B1 = EFGH |
Bipartition 2: | ABE:CDFGH | A2 = ABE | B2 = CDFGH |
This can be represented by an association matrix:
A2 | B2 | |
A1 | AB | C |
B1 | E | FGH |
The cells in this matrix contain 2, 1, 1 and 3 terminals respectively; this
four-element vector (c(2, 1, 1, 3)
) is the configuration
implied by
this pair of bipartition splits.
The number of ways to distribute sum(configuration)
taxa according
to the specified pattern.
Martin R. Smith ([email protected])
NPartitionPairs(c(2, 1, 1, 3))
NPartitionPairs(c(2, 1, 1, 3))
These functions return the number of rooted or unrooted binary trees consistent with a given pattern of splits.
NRooted(tips) NUnrooted(tips) NRooted64(tips) NUnrooted64(tips) LnUnrooted(tips) LnUnrooted.int(tips) Log2Unrooted(tips) Log2Unrooted.int(tips) LnRooted(tips) LnRooted.int(tips) Log2Rooted(tips) Log2Rooted.int(tips) LnUnrootedSplits(...) Log2UnrootedSplits(...) NUnrootedSplits(...) LnUnrootedMult(...) Log2UnrootedMult(...) NUnrootedMult(...)
NRooted(tips) NUnrooted(tips) NRooted64(tips) NUnrooted64(tips) LnUnrooted(tips) LnUnrooted.int(tips) Log2Unrooted(tips) Log2Unrooted.int(tips) LnRooted(tips) LnRooted.int(tips) Log2Rooted(tips) Log2Rooted.int(tips) LnUnrootedSplits(...) Log2UnrootedSplits(...) NUnrootedSplits(...) LnUnrootedMult(...) Log2UnrootedMult(...) NUnrootedMult(...)
tips |
Integer specifying the number of leaves. |
... |
Integer vector, or series of integers, listing the number of leaves in each split. |
Functions starting N
return the number of rooted or unrooted trees.
Replace this initial N
with Ln
for the natural logarithm of this number;
or Log2
for its base 2 logarithm.
Calculations follow Cavalli-Sforza and Edwards (1967) and Carter et al. (1990), Theorem 2.
NUnrooted()
: Number of unrooted trees
NRooted64()
: Exact number of rooted trees as 64-bit integer
(13 < nTip
< 19)
NUnrooted64()
: Exact number of unrooted trees as 64-bit integer
(14 < nTip
< 20)
LnUnrooted()
: Log Number of unrooted trees
LnUnrooted.int()
: Log Number of unrooted trees (as integer)
LnRooted()
: Log Number of rooted trees
LnRooted.int()
: Log Number of rooted trees (as integer)
NUnrootedSplits()
: Number of unrooted trees consistent with a bipartition
split.
NUnrootedMult()
: Number of unrooted trees consistent with a multi-partition
split.
Martin R. Smith ([email protected])
Carter M, Hendy M, Penny D, Székely LA, Wormald NC (1990).
“On the distribution of lengths of evolutionary trees.”
SIAM Journal on Discrete Mathematics, 3(1), 38–47.
doi:10.1137/0403005.
Cavalli-Sforza LL, Edwards AWF (1967).
“Phylogenetic analysis: models and estimation procedures.”
Evolution, 21(3), 550–570.
ISSN 00143820, doi:10.1111/j.1558-5646.1967.tb03411.x.
Other tree information functions:
CladisticInfo()
,
TreesMatchingTree()
NRooted(10) NUnrooted(10) LnRooted(10) LnUnrooted(10) Log2Unrooted(10) # Number of trees consistent with a character whose states are # 00000 11111 222 NUnrootedMult(c(5,5,3)) NUnrooted64(18) LnUnrootedSplits(c(2,4)) LnUnrootedSplits(3, 3) Log2UnrootedSplits(c(2,4)) Log2UnrootedSplits(3, 3) NUnrootedSplits(c(2,4)) NUnrootedSplits(3, 3)
NRooted(10) NUnrooted(10) LnRooted(10) LnUnrooted(10) Log2Unrooted(10) # Number of trees consistent with a character whose states are # 00000 11111 222 NUnrootedMult(c(5,5,3)) NUnrooted64(18) LnUnrootedSplits(c(2,4)) LnUnrootedSplits(3, 3) Log2UnrootedSplits(c(2,4)) Log2UnrootedSplits(3, 3) NUnrootedSplits(c(2,4)) NUnrootedSplits(3, 3)
nRootedShapes
and nUnrootedShapes
give the number of (un)rooted binary
trees on n unlabelled leaves.
nRootedShapes nUnrootedShapes
nRootedShapes nUnrootedShapes
An object of class integer64
of length 55.
An object of class integer64
of length 60.
nRootedShapes
corresponds to the Wedderburn-Etherington numbers,
OEIS A001190
nUnrootedShapes
is OEIS A000672
NSplits()
counts the unique bipartition splits in a tree or object.
NSplits(x) NPartitions(x) ## S3 method for class 'phylo' NSplits(x) ## S3 method for class 'list' NSplits(x) ## S3 method for class 'multiPhylo' NSplits(x) ## S3 method for class 'Splits' NSplits(x) ## S3 method for class 'numeric' NSplits(x) ## S3 method for class ''NULL'' NSplits(x) ## S3 method for class 'ClusterTable' NSplits(x) ## S3 method for class 'character' NSplits(x)
NSplits(x) NPartitions(x) ## S3 method for class 'phylo' NSplits(x) ## S3 method for class 'list' NSplits(x) ## S3 method for class 'multiPhylo' NSplits(x) ## S3 method for class 'Splits' NSplits(x) ## S3 method for class 'numeric' NSplits(x) ## S3 method for class ''NULL'' NSplits(x) ## S3 method for class 'ClusterTable' NSplits(x) ## S3 method for class 'character' NSplits(x)
x |
A phylogenetic tree of class |
NSplits()
returns an integer specifying the number of bipartitions in
the specified objects, or in a binary tree with x
tips.
Martin R. Smith ([email protected])
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NTip()
,
NodeNumbers()
,
PathLengths()
,
SplitsInBinaryTree()
,
TipLabels()
,
TreeIsRooted()
Other Splits operations:
LabelSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
NSplits(8L) NSplits(PectinateTree(8)) NSplits(as.Splits(BalancedTree(8)))
NSplits(8L) NSplits(PectinateTree(8)) NSplits(as.Splits(BalancedTree(8)))
NTip()
extends ape::Ntip()
to handle
objects of class Splits
and list
, and edge matrices
(equivalent to tree$edge
).
NTip(phy) ## Default S3 method: NTip(phy) ## S3 method for class 'Splits' NTip(phy) ## S3 method for class 'list' NTip(phy) ## S3 method for class 'phylo' NTip(phy) ## S3 method for class 'multiPhylo' NTip(phy) ## S3 method for class 'phyDat' NTip(phy) ## S3 method for class 'matrix' NTip(phy)
NTip(phy) ## Default S3 method: NTip(phy) ## S3 method for class 'Splits' NTip(phy) ## S3 method for class 'list' NTip(phy) ## S3 method for class 'phylo' NTip(phy) ## S3 method for class 'multiPhylo' NTip(phy) ## S3 method for class 'phyDat' NTip(phy) ## S3 method for class 'matrix' NTip(phy)
phy |
Object representing one or more phylogenetic trees. |
NTip()
returns an integer specifying the number of tips in each
object in phy
.
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NSplits()
,
NodeNumbers()
,
PathLengths()
,
SplitsInBinaryTree()
,
TipLabels()
,
TreeIsRooted()
Other Splits operations:
LabelSplits()
,
NSplits()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
Distances between each pair of trees
PairwiseDistances(trees, Func, valueLength = 1L, ...)
PairwiseDistances(trees, Func, valueLength = 1L, ...)
trees |
List of trees of class |
Func |
Function returning a distance between two trees. |
valueLength |
Integer specifying expected length of the value returned
by |
... |
Additional arguments to |
Matrix detailing distance between each pair of trees. Identical trees are assumed to have zero distance.
Martin R. Smith ([email protected])
trees <- list(BalancedTree(8), PectinateTree(8), StarTree(8)) TCIDiff <- function(tree1, tree2) { TotalCopheneticIndex(tree1) - TotalCopheneticIndex(tree2) } PairwiseDistances(trees, TCIDiff, 1) TCIRange <- function(tree1, tree2) { range(TotalCopheneticIndex(tree1), TotalCopheneticIndex(tree2)) } PairwiseDistances(trees, TCIRange, 2)
trees <- list(BalancedTree(8), PectinateTree(8), StarTree(8)) TCIDiff <- function(tree1, tree2) { TotalCopheneticIndex(tree1) - TotalCopheneticIndex(tree2) } PairwiseDistances(trees, TCIDiff, 1) TCIRange <- function(tree1, tree2) { range(TotalCopheneticIndex(tree1), TotalCopheneticIndex(tree2)) } PairwiseDistances(trees, TCIRange, 2)
Given a weighted rooted tree tree
, PathLengths()
returns the distance
from each vertex to each of its descendant vertices.
PathLengths(tree, fullMatrix = FALSE)
PathLengths(tree, fullMatrix = FALSE)
tree |
Original tree of class |
fullMatrix |
Logical specifying return format; see "value" section'. |
If fullMatrix = TRUE
, PathLengths()
returns a square matrix in
which entry [i, j]
denotes the distance from internal node i
to the
descendant vertex j
.
Vertex pairs without a continuous directed path are denoted NA
.
If fullMatrix = FALSE
, PathLengths()
returns a data.frame
with three
columns: start
lists the deepest node in each path (i.e. that closest
to the root); end
lists the shallowest node (i.e. that closest to a leaf);
length
lists the total length of that path.
Martin R. Smith ([email protected])
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NSplits()
,
NTip()
,
NodeNumbers()
,
SplitsInBinaryTree()
,
TipLabels()
,
TreeIsRooted()
tree <- rtree(6) plot(tree) add.scale.bar() nodelabels() tiplabels() PathLengths(tree)
tree <- rtree(6) plot(tree) add.scale.bar() nodelabels() tiplabels() PathLengths(tree)
Polarize splits on a single taxon
PolarizeSplits(x, pole = 1L)
PolarizeSplits(x, pole = 1L)
x |
Object of class |
pole |
Numeric or character identifying tip that should polarize each split. |
PolarizeSplits()
returns a Splits
object in which pole
is
represented by a zero bit
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
TreeNumber
objectS3 method for objects of class TreeNumber
.
## S3 method for class 'TreeNumber' print(x, ...)
## S3 method for class 'TreeNumber' print(x, ...)
x |
Object of class |
... |
Additional arguments for consistency with S3 method (unused). |
Other 'TreeNumber' utilities:
TreeNumber
,
is.TreeNumber()
Parse a Nexus (Maddison et al. 1997) or TNT (Goloboff et al. 2008) file, reading character states and names.
ReadCharacters(filepath, character_num = NULL, encoding = "UTF8") ReadTntCharacters( filepath, character_num = NULL, type = NULL, encoding = "UTF8" ) ReadTNTCharacters( filepath, character_num = NULL, type = NULL, encoding = "UTF8" ) ReadNotes(filepath, encoding = "UTF8") ReadAsPhyDat(...) ReadTntAsPhyDat(...) ReadTNTAsPhyDat(...) PhyDat(dataset)
ReadCharacters(filepath, character_num = NULL, encoding = "UTF8") ReadTntCharacters( filepath, character_num = NULL, type = NULL, encoding = "UTF8" ) ReadTNTCharacters( filepath, character_num = NULL, type = NULL, encoding = "UTF8" ) ReadNotes(filepath, encoding = "UTF8") ReadAsPhyDat(...) ReadTntAsPhyDat(...) ReadTNTAsPhyDat(...) PhyDat(dataset)
filepath |
character string specifying location of file, or a connection to the file. |
character_num |
Index of character(s) to return.
|
encoding |
Character encoding of input file. |
type |
Character vector specifying categories of data to extract from
file. Setting |
... |
Parameters to pass to |
dataset |
list of taxa and characters, in the format produced by
|
Tested with matrices downloaded from MorphoBank (O’Leary and Kaufman 2011), but should also work more widely; please report incompletely or incorrectly parsed files.
Matrices must contain only continuous or only discrete characters; maximum one matrix per file. Continuous characters will be read as strings (i.e. base type "character").
The encoding of an input file will be automatically determined by R.
Errors pertaining to an invalid multibyte string
or
string invalid at that locale
indicate that R has failed to detect
the appropriate encoding. Either
re-save the file
in a supported encoding (UTF-8
is a good choice) or
specify the file encoding (which you can find by, for example, opening in
Notepad++ and identifying
the highlighted option in the "Encoding" menu) following the example below.
ReadCharacters()
and ReadTNTCharacters()
return a matrix whose
row names correspond to tip labels, and
column names correspond to character labels, with the
attribute state.labels
listing the state labels for each character; or
a list of length one containing a character string explaining why the
function call was unsuccessful.
ReadAsPhyDat()
and ReadTntAsPhyDat()
return a phyDat
object.
ReadNotes()
returns a list in which each entry corresponds to a
single character, and itself contains a list of with two elements:
A single character object listing any notes associated with the character
A named character vector listing the notes associated with each taxon for that character, named with the names of each note-bearing taxon.
PhyDat()
: A convenient wrapper for phangorn's
phyDat()
, which converts a list of morphological characters into a
phyDat
object.
If your morphological characters are in the form of a matrix, perhaps
because they have been read using read.table()
, try MatrixToPhyDat()
instead.
Martin R. Smith ([email protected])
Goloboff PA, Farris JS, Nixon KC (2008).
“TNT, a free program for phylogenetic analysis.”
Cladistics, 24(5), 774–786.
Maddison DR, Swofford DL, Maddison WP (1997).
“Nexus: an extensible file format for systematic information.”
Systematic Biology, 46, 590–621.
doi:10.1093/sysbio/46.4.590.
O’Leary MA, Kaufman S (2011).
“MorphoBank: phylophenomics in the "cloud".”
Cladistics, 27(5), 529–537.
Convert between matrices and phyDat
objects: MatrixToPhyDat()
Write characters to TNT-format file: WriteTntCharacters()
fileName <- paste0(system.file(package = "TreeTools"), "/extdata/input/dataset.nex") ReadCharacters(fileName) fileName <- paste0(system.file(package = "TreeTools"), "/extdata/tests/continuous.nex") continuous <- ReadCharacters(fileName, encoding = "UTF8") # To convert from strings to numbers: at <- attributes(continuous) continuous <- suppressWarnings(as.numeric(continuous)) attributes(continuous) <- at continuous
fileName <- paste0(system.file(package = "TreeTools"), "/extdata/input/dataset.nex") ReadCharacters(fileName) fileName <- paste0(system.file(package = "TreeTools"), "/extdata/tests/continuous.nex") continuous <- ReadCharacters(fileName, encoding = "UTF8") # To convert from strings to numbers: at <- attributes(continuous) continuous <- suppressWarnings(as.numeric(continuous)) attributes(continuous) <- at continuous
Read posterior trees from 'MrBayes' output files, discarding burn-in generations.
ReadMrBayesTrees(filepath, n = NULL, burninFrac = NULL) ReadMrBayes(filepath, n = NULL, burninFrac = NULL) MrBayesTrees(filepath, n = NULL, burninFrac = NULL)
ReadMrBayesTrees(filepath, n = NULL, burninFrac = NULL) ReadMrBayes(filepath, n = NULL, burninFrac = NULL) MrBayesTrees(filepath, n = NULL, burninFrac = NULL)
filepath |
character string specifying path to |
n |
Integer specifying number of trees to sample from posterior. |
burninFrac |
Fraction of trees to discard from each run as burn-in.
If |
ReadMrBayesTrees()
samples trees from the posterior distributions
computed using the Bayesian inference software 'MrBayes'
ReadMrBayesTrees()
returns a 'multiPhylo' object containing
n
trees sampled evenly from all runs generated by analysis of filepath
,
or NULL
if no trees are found.
Martin R. Smith ([email protected])
Other tree import functions:
ReadTntTree()
## Not run: # Download will take a few seconds url <- "https://raw.githubusercontent.com/ms609/hyoliths/master/MrBayes/hyo.nex" trees <- ReadMrBayesTrees(url, n = 40) plot(Consensus(trees, p = 0.5)) ## End(Not run)
## Not run: # Download will take a few seconds url <- "https://raw.githubusercontent.com/ms609/hyoliths/master/MrBayes/hyo.nex" trees <- ReadMrBayesTrees(url, n = 40) plot(Consensus(trees, p = 0.5)) ## End(Not run)
Read a tree from TNT's parenthetical output.
ReadTntTree(filepath, relativePath = NULL, keepEnd = 1L, tipLabels = NULL) TntText2Tree(treeText) TNTText2Tree(treeText)
ReadTntTree(filepath, relativePath = NULL, keepEnd = 1L, tipLabels = NULL) TntText2Tree(treeText) TNTText2Tree(treeText)
filepath |
character string specifying path to TNT |
relativePath |
(discouraged) character string specifying location of the
matrix file used to generate the TNT results, relative to the current working
directory. Taxon names will be read from this file if they are not specified
by |
keepEnd |
(optional, default 1) integer specifying how many elements of the file path to conserve when creating relative path (see examples). |
tipLabels |
(optional) character vector specifying the names of the
taxa, in the sequence that they appear in the TNT file. If not specified,
taxon names will be loaded from the data file linked in the first line of the
|
treeText |
Character string describing one or more trees, in the parenthetical format output by TNT. |
ReadTntTree()
imports trees generated by the parsimony analysis program
TNT into R, including node labels
written with the ttags
command.
Tree files must have been saved by TNT in parenthetical notation, using the
TNT command tsave *
.
Trees are easiest to load into R if taxa have been saved using their names
(TNT command taxname =
). In this case, the TNT .tre
file
contains tip labels and can be parsed directly. The downside is that the
uncompressed .tre
files will have a larger file size.
ReadTntTree()
can also read .tre
files in which taxa have been saved
using their numbers (taxname -
). Such files contain a hard-coded link to
the matrix file that was used to generate the trees, in the first line of the
.tre
file. This poses problems for portability: if the matrix file is
moved, or the .tre
file is accessed on another computer, the taxon names
may be lost. As such, it is important to check that the matrix file
exists in the expected location – if it does not,
either use the relativePath
argument to point to its new location, or
specify tipLabels
to manually specify the tip labels.
TntText2Tree()
converts text representation of a tree in TNT to an
object of class phylo
.
ReadTntTree()
returns a tree of class phylo
in
TNT order,
corresponding to the tree in filepath
, or NULL if no trees are found.
Martin R. Smith ([email protected])
Other tree import functions:
ReadMrBayesTrees()
# In the examples below, TNT has read a matrix from # "c:/TreeTools/input/dataset.nex" # The results of an analysis were written to # "c:/TreeTools/output/results1.tnt" # # results1.tnt will contain a hard-coded reference to # "c:/TreeTools/input/dataset.nex". # On the original machine (but not elsewhere), it would be possible to read # this hard-coded reference from results.tnt: # ReadTntTree("output/results1.tnt") # These datasets are provided with the "TreeTools" package, which will # probably not be located at c:/TreeTools on your machine: oldWD <- getwd() # Remember the current working directory setwd(system.file(package = "TreeTools")) # If taxon names were saved within the file (using `taxname=` in TNT), # then our job is easy: ReadTntTree("extdata/output/named.tre") # But if taxa were compressed to numbers (using `taxname-`), we need to # look up the original matrix in order to dereference the tip names. # # We need to extract the relevant file path from the end of the # hard-coded path in the original file. # # We are interested in the last two elements of # c:/TreeTools/input/dataset.nex # 2 1 # # "." means "relative to the current directory" ReadTntTree("extdata/output/numbered.tre", "./extdata", 2) # If working in a lower subdirectory setwd("./extdata/otherfolder") # then it will be necessary to navigate up the directory path with "..": ReadTntTree("../output/numbered.tre", "..", 2) setwd(oldWD) # Restore original working directory TNTText2Tree("(A (B (C (D E ))));")
# In the examples below, TNT has read a matrix from # "c:/TreeTools/input/dataset.nex" # The results of an analysis were written to # "c:/TreeTools/output/results1.tnt" # # results1.tnt will contain a hard-coded reference to # "c:/TreeTools/input/dataset.nex". # On the original machine (but not elsewhere), it would be possible to read # this hard-coded reference from results.tnt: # ReadTntTree("output/results1.tnt") # These datasets are provided with the "TreeTools" package, which will # probably not be located at c:/TreeTools on your machine: oldWD <- getwd() # Remember the current working directory setwd(system.file(package = "TreeTools")) # If taxon names were saved within the file (using `taxname=` in TNT), # then our job is easy: ReadTntTree("extdata/output/named.tre") # But if taxa were compressed to numbers (using `taxname-`), we need to # look up the original matrix in order to dereference the tip names. # # We need to extract the relevant file path from the end of the # hard-coded path in the original file. # # We are interested in the last two elements of # c:/TreeTools/input/dataset.nex # 2 1 # # "." means "relative to the current directory" ReadTntTree("extdata/output/numbered.tre", "./extdata", 2) # If working in a lower subdirectory setwd("./extdata/otherfolder") # then it will be necessary to navigate up the directory path with "..": ReadTntTree("../output/numbered.tre", "..", 2) setwd(oldWD) # Restore original working directory TNTText2Tree("(A (B (C (D E ))));")
Renumber()
numbers the nodes and tips in a tree to conform with the
phylo
standards.
Renumber(tree)
Renumber(tree)
tree |
A tree of class |
The ape class phylo
is not formally defined, but expects trees' internal
representation to conform to certain principles: for example, nodes should
be numbered sequentially, with values increasing away from the root.
Renumber()
attempts to reformat any tree into a representation that will
not cause ape functions to produce unwanted results or to crash R.
Renumber()
returns a tree of class phylo
, numbered in a
Cladewise fashion consistent with the expectations of ape functions.
Martin R. Smith ([email protected])
Preorder()
provides a faster and simpler alternative, but also
rotates nodes.
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
tree <- RandomTree(letters[1:10]) Renumber(tree)
tree <- RandomTree(letters[1:10]) Renumber(tree)
RenumberTips(tree, tipOrder)
sorts the tips of a phylogenetic tree tree
such that the indices in tree[["edge"]][, 2]
correspond to the order of
leaves given in tipOrder
.
RenumberTips(tree, tipOrder) ## S3 method for class 'phylo' RenumberTips(tree, tipOrder) ## S3 method for class 'multiPhylo' RenumberTips(tree, tipOrder) ## S3 method for class 'list' RenumberTips(tree, tipOrder) ## S3 method for class ''NULL'' RenumberTips(tree, tipOrder)
RenumberTips(tree, tipOrder) ## S3 method for class 'phylo' RenumberTips(tree, tipOrder) ## S3 method for class 'multiPhylo' RenumberTips(tree, tipOrder) ## S3 method for class 'list' RenumberTips(tree, tipOrder) ## S3 method for class ''NULL'' RenumberTips(tree, tipOrder)
tree |
A tree of class |
tipOrder |
A character vector containing the values of
|
RenumberTips()
returns tree
, with the tips' internal
representation numbered to match tipOrder
.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
data("Lobo") # Loads the phyDat object Lobo.phy tree <- RandomTree(Lobo.phy) tree <- RenumberTips(tree, names(Lobo.phy))
data("Lobo") # Loads the phyDat object Lobo.phy tree <- RandomTree(Lobo.phy) tree <- RenumberTips(tree, names(Lobo.phy))
RightmostCharacter()
is a convenience function that returns the final
character of a string.
RightmostCharacter(string, len = nchar(string))
RightmostCharacter(string, len = nchar(string))
string |
Character string. |
len |
(Optional) Integer specifying number of characters in |
RightmostCharacter()
returns the rightmost character of a string.
Martin R. Smith ([email protected])
Other string parsing functions:
EndSentence()
,
MorphoBankDecode()
,
Unquote()
RightmostCharacter("Hello, World!")
RightmostCharacter("Hello, World!")
Plots a consensus of trees with a rogue taxon omitted, with edges coloured according to the proportion of trees in which the taxon attaches to that edge, after Klopfstein and Spasojevic (2019).
RoguePlot( trees, tip, p = 1, plot = TRUE, Palette = colorRampPalette(c(par("fg"), "#009E73"), space = "Lab"), nullCol = rgb(colorRamp(unlist(par(c("fg", "bg"))), space = "Lab")(0.8)/255), edgeLength = NULL, thin = par("lwd"), fat = thin + 1L, outgroupTips, sort = FALSE, legend = "none", legend.inset = 0, ... )
RoguePlot( trees, tip, p = 1, plot = TRUE, Palette = colorRampPalette(c(par("fg"), "#009E73"), space = "Lab"), nullCol = rgb(colorRamp(unlist(par(c("fg", "bg"))), space = "Lab")(0.8)/255), edgeLength = NULL, thin = par("lwd"), fat = thin + 1L, outgroupTips, sort = FALSE, legend = "none", legend.inset = 0, ... )
trees |
List or |
tip |
Numeric or character identifying rogue leaf, in format accepted
by |
p |
A numeric value between 0.5 and 1 giving the proportion for a clade
to be represented in the consensus tree (see |
plot |
Logical specifying whether to plot the tree. |
Palette |
Function that takes a parameter |
nullCol |
Colour to paint regions of the tree on which the rogue is never found. |
edgeLength |
Numeric specifying edge lengths of consensus tree;
|
thin , fat
|
Numeric specifying width to plot edges if the rogue tip never / sometimes does attach to them. |
outgroupTips |
Vector of type character, integer or logical, specifying
the names or indices of the tips to include in the outgroup.
If |
sort |
Logical specifying whether to sort consensus tree using
|
legend |
Character vector specifying position of legend (e.g.
|
legend.inset |
Numeric specifying fraction of plot width / height by which the legend's position should be inset. |
... |
Additional parameters to |
Rogue taxa can be identified using the package Rogue (Smith 2022).
RoguePlot()
invisibly returns a list whose elements are:
cons
: The reduced consensus tree, in preorder;
onEdge
: a vector of integers specifying the number of
trees in trees
in which the rogue leaf is attached to each edge in turn
of the consensus tree;
atNode
: a vector of integers specifying the number of trees in trees
in which the rogue leaf is attached to an edge collapsed into each node
of the consensus tree.
legendLabels
: A character vector suggesting labels for a plot legend;
suitable for PlotTools::SpectrumLegend(legend = x$legendLabels)
.
Martin R. Smith ([email protected])
Klopfstein S, Spasojevic T (2019).
“Illustrating phylogenetic placement of fossils using RoguePlots: An example from ichneumonid parasitoid wasps (Hymenoptera, Ichneumonidae) and an extensive morphological matrix.”
PLOS ONE, 14(4), e0212942.
doi:10.1371/journal.pone.0212942.
Smith MR (2022).
“Using information theory to detect rogue taxa and improve consensus trees.”
Systematic Biology, 71(5), 986–1008.
doi:10.1093/sysbio/syab099.
Other consensus tree functions:
Consensus()
,
ConsensusWithout()
trees <- list(read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(rogue, (a, (b, (c, (d, (e, f))))));"), read.tree(text = "((rogue, a), (b, (c, (d, (e, f)))));"), read.tree(text = "(a, (b, ((c, d), (rogue, (e, f)))));"), read.tree(text = "(a, (b, ((c, (rogue, d)), (e, f))));"), read.tree(text = "(a, (b, (c, (d, (rogue, (e, f))))));")) plotted <- RoguePlot(trees, "rogue", legend = "topleft", legend.inset = 0.02) PlotTools::SpectrumLegend( "bottomleft", palette = colorRampPalette(c(par("fg"), "#009E73"), space = "Lab")(100), legend = plotted$legendLabels, cex = 0.4 )
trees <- list(read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(a, (b, (c, (rogue, (d, (e, f))))));"), read.tree(text = "(rogue, (a, (b, (c, (d, (e, f))))));"), read.tree(text = "((rogue, a), (b, (c, (d, (e, f)))));"), read.tree(text = "(a, (b, ((c, d), (rogue, (e, f)))));"), read.tree(text = "(a, (b, ((c, (rogue, d)), (e, f))));"), read.tree(text = "(a, (b, (c, (d, (rogue, (e, f))))));")) plotted <- RoguePlot(trees, "rogue", legend = "topleft", legend.inset = 0.02) PlotTools::SpectrumLegend( "bottomleft", palette = colorRampPalette(c(par("fg"), "#009E73"), space = "Lab")(100), legend = plotted$legendLabels, cex = 0.4 )
RootNode()
identifies the root node of a (rooted or unrooted) phylogenetic
tree.
Unrooted trees are represented internally by a rooted tree with a polytomy
at the root.
RootNode(x)
RootNode(x)
x |
A tree of class |
RootNode()
returns an integer denoting the root node for each tree.
Badly conformed trees trigger an error.
Martin R. Smith ([email protected])
Test whether a tree is rooted: TreeIsRooted()
phangorn::getRoot()
Other tree navigation:
AncestorEdge()
,
CladeSizes()
,
DescendantEdges()
,
EdgeAncestry()
,
EdgeDistances()
,
ListAncestors()
,
MRCA()
,
MatchEdges()
,
NDescendants()
,
NodeDepth()
,
NodeNumbers()
,
NodeOrder()
RootNode(BalancedTree(8)) RootNode(UnrootTree(BalancedTree(8)))
RootNode(BalancedTree(8)) RootNode(UnrootTree(BalancedTree(8)))
RootTree()
roots a tree on the smallest clade containing the specified
tips;
RootOnNode()
roots a tree on a specified internal node;
UnrootTree()
collapses a root node, without the undefined behaviour
encountered when using ape::unroot()
on trees in
preorder.
RootTree(tree, outgroupTips) RootOnNode(tree, node, resolveRoot = FALSE) UnrootTree(tree)
RootTree(tree, outgroupTips) RootOnNode(tree, node, resolveRoot = FALSE) UnrootTree(tree)
tree |
A tree of class |
outgroupTips |
Vector of type character, integer or logical, specifying
the names or indices of the tips to include in the outgroup.
If |
node |
integer specifying node (internal or tip) to set as the root. |
resolveRoot |
logical specifying whether to resolve the root node. |
RootTree()
returns a tree of class phylo
, rooted on the smallest
clade that contains the specified tips, with edges and nodes numbered in
preorder. Node labels are not retained.
RootOnNode()
returns a tree of class phylo
, rooted on the
requested node
and ordered in Preorder
.
UnrootTree()
returns tree
, in preorder,
having collapsed the first child of the root node in each tree.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
tree <- PectinateTree(8) plot(tree) ape::nodelabels() plot(RootTree(tree, c("t6", "t7"))) plot(RootOnNode(tree, 12)) plot(RootOnNode(tree, 2))
tree <- PectinateTree(8) plot(tree) ape::nodelabels() plot(RootTree(tree, c("t6", "t7"))) plot(RootOnNode(tree, 12)) plot(RootOnNode(tree, 2))
Wrappers for members of the lapply()
family intended for use when a
function FUN
returns a vector of integer64
objects.
vapply()
, sapply()
or replicate()
drop the integer64
class,
resulting in a vector of numerics that require conversion back to
64-bit integers. These functions restore the missing class
attribute.
sapply64(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE) vapply64(X, FUN, FUN.LEN = 1, ...) replicate64(n, expr, simplify = "array")
sapply64(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE) vapply64(X, FUN, FUN.LEN = 1, ...) replicate64(n, expr, simplify = "array")
X |
a vector (atomic or list) or an |
FUN |
the function to be applied to each element of |
... |
optional arguments to |
simplify |
logical or character string; should the result be
simplified to a vector, matrix or higher dimensional array if
possible? For |
USE.NAMES |
logical; if |
FUN.LEN |
Integer specifying the length of the output of |
n |
integer: the number of replications. |
expr |
the expression (a language object, usually a call) to evaluate repeatedly. |
For details of the underlying functions, see base::lapply()
.
Martin R. Smith ([email protected])
sapply64(as.phylo(1:6, 6), as.TreeNumber) vapply64(as.phylo(1:6, 6), as.TreeNumber, 1) set.seed(0) replicate64(6, as.TreeNumber(RandomTree(6)))
sapply64(as.phylo(1:6, 6), as.TreeNumber) vapply64(as.phylo(1:6, 6), as.TreeNumber, 1) set.seed(0) replicate64(6, as.TreeNumber(RandomTree(6)))
Trees are sorted by their mixed base representation, treating their leaves in the order of their labels (i.e. alphabetically, if leaves are labelled with text).
## S3 method for class 'multiPhylo' sort(x, decreasing = FALSE, na.last = NA, ...) ## S3 method for class 'phylo' e1 == e2 ## S3 method for class 'phylo' e1 < e2 ## S3 method for class 'phylo' e1 > e2 ## S3 method for class 'MixedBase' e1 == e2 ## S3 method for class 'MixedBase' e1 < e2 ## S3 method for class 'MixedBase' e1 > e2
## S3 method for class 'multiPhylo' sort(x, decreasing = FALSE, na.last = NA, ...) ## S3 method for class 'phylo' e1 == e2 ## S3 method for class 'phylo' e1 < e2 ## S3 method for class 'phylo' e1 > e2 ## S3 method for class 'MixedBase' e1 == e2 ## S3 method for class 'MixedBase' e1 < e2 ## S3 method for class 'MixedBase' e1 > e2
x , decreasing , na.last , ...
|
As in |
e1 , e2
|
Objects to be compared. |
Martin R. Smith ([email protected])
sort(as.phylo(5:0, 7))
sort(as.phylo(5:0, 7))
SortTree()
sorts each node into a consistent order, so that node rotation
does not obscure similarities between similar trees.
SortTree(tree, how = "cladesize", order = TipLabels(tree)) ## S3 method for class 'phylo' SortTree(tree, how = "cladesize", order = TipLabels(tree)) ## S3 method for class 'list' SortTree(tree, how = "cladesize", order = TipLabels(tree[[1]])) ## S3 method for class 'multiPhylo' SortTree(tree, how = "cladesize", order = TipLabels(tree[[1]]))
SortTree(tree, how = "cladesize", order = TipLabels(tree)) ## S3 method for class 'phylo' SortTree(tree, how = "cladesize", order = TipLabels(tree)) ## S3 method for class 'list' SortTree(tree, how = "cladesize", order = TipLabels(tree[[1]])) ## S3 method for class 'multiPhylo' SortTree(tree, how = "cladesize", order = TipLabels(tree[[1]]))
tree |
One or more trees of class |
how |
Character vector specifying sort method:
|
order |
Character vector listing tip labels in sequence they should
appear on tree. Clades containing a taxon earlier in this list will be listed
sooner and thus plot lower on a tree. Taxa not listed in |
At each node, clades will be listed in tree[["edge"]]
in decreasing size
order.
Clades that contain the same number of leaves are sorted in decreasing order of minimum leaf number, so (2, 3) will occur before (1, 4).
As trees are plotted from "bottom up", the largest clades will "sink" to the bottom of a plotted tree.
SortTree()
returns tree in the format of tree
, with each node
in each tree sorted
Martin R. Smith ([email protected])
Preorder()
also rearranges trees into a consistent shape,
based on the index of leaves.
sort.multiPhylo()
sorts a list of trees stored as a multiPhylo
object.
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
Subtree()
,
TipTimedTree()
,
TrivialTree
messyTree <- as.phylo(10, 6) plot(messyTree) sorted <- SortTree(messyTree) plot(sorted) ape::nodelabels() ape::edgelabels() ape::tiplabels(adj = c(2, 1/3)) plot(SortTree(messyTree, how = "tip"))
messyTree <- as.phylo(10, 6) plot(messyTree) sorted <- SortTree(messyTree) plot(sorted) ape::nodelabels() ape::edgelabels() ape::tiplabels(adj = c(2, 1/3)) plot(SortTree(messyTree, how = "tip"))
SplitFrequency()
provides a simple way to count the number of times that
bipartition splits, as defined by a reference tree, occur in a forest of
trees. May be used to calculate edge ("node") support for majority consensus
or bootstrap trees.
SplitFrequency(reference, forest) SplitNumber(tips, tree, tipIndex, powersOf2) ForestSplits(forest, powersOf2) TreeSplits(tree)
SplitFrequency(reference, forest) SplitNumber(tips, tree, tipIndex, powersOf2) ForestSplits(forest, powersOf2) TreeSplits(tree)
reference |
A tree of class |
forest |
a list of trees of class |
tips |
Integer vector specifying the tips of the tree within the chosen split. |
tree |
A tree of class |
tipIndex |
Character vector of tip names, in a fixed order. |
powersOf2 |
Integer vector of same length as |
If multiple calculations are required, some time can be saved by using the constituent functions (see examples)
SplitFrequency()
returns the number of trees in forest
that
contain each split in reference
.
If reference
is a tree of class phylo
, then the sequence will correspond
to the order of nodes (use ape::nodelabels()
to view).
Note that the three nodes at the root of the tree correspond to a single
split; see the example for how these might be plotted on a tree.
SplitNumber()
: Assign a unique integer to each split
ForestSplits()
: Frequency of splits in a given forest of trees
TreeSplits()
: Deprecated. Listed the splits in a given tree.
Use as.Splits instead.
Martin R. Smith ([email protected])
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
# An example forest of 100 trees, some identical forest <- as.phylo(c(1, rep(10, 79), rep(100, 15), rep(1000, 5)), nTip = 9) # Generate an 80% consensus tree cons <- ape::consensus(forest, p = 0.8) plot(cons) # Calculate split frequencies splitFreqs <- SplitFrequency(cons, forest) # Optionally, colour edges by corresponding frequency. # Note that not all edges are associated with a unique split # (and two root edges may be associated with one split - not handled here) edgeSupport <- rep(1, nrow(cons$edge)) # Initialize trivial splits to 1 childNode <- cons$edge[, 2] edgeSupport[match(names(splitFreqs), childNode)] <- splitFreqs / 100 plot(cons, edge.col = SupportColour(edgeSupport), edge.width = 3) # Annotate nodes by frequency LabelSplits(cons, splitFreqs, unit = "%", col = SupportColor(splitFreqs / 100), frame = "none", pos = 3L)
# An example forest of 100 trees, some identical forest <- as.phylo(c(1, rep(10, 79), rep(100, 15), rep(1000, 5)), nTip = 9) # Generate an 80% consensus tree cons <- ape::consensus(forest, p = 0.8) plot(cons) # Calculate split frequencies splitFreqs <- SplitFrequency(cons, forest) # Optionally, colour edges by corresponding frequency. # Note that not all edges are associated with a unique split # (and two root edges may be associated with one split - not handled here) edgeSupport <- rep(1, nrow(cons$edge)) # Initialize trivial splits to 1 childNode <- cons$edge[, 2] edgeSupport[match(names(splitFreqs), childNode)] <- splitFreqs / 100 plot(cons, edge.col = SupportColour(edgeSupport), edge.width = 3) # Annotate nodes by frequency LabelSplits(cons, splitFreqs, unit = "%", col = SupportColor(splitFreqs / 100), frame = "none", pos = 3L)
Calculate the phylogenetic information content (sensu Steel and Penny 2006) of a split, which reflects the probability that a uniformly selected random tree will contain# the split: a split that is consistent with a smaller number of trees will have a higher information content.
SplitInformation(A, B = A[1]) MultiSplitInformation(partitionSizes)
SplitInformation(A, B = A[1]) MultiSplitInformation(partitionSizes)
A , B
|
Integer specifying the number of taxa in each partition. |
partitionSizes |
Integer vector specifying the number of taxa in each partition of a multi-partition split. |
SplitInformation()
addresses bipartition splits, which correspond to
edges in an unrooted phylogeny; MultiSplitInformation()
supports splits
that subdivide taxa into multiple partitions, which may correspond to
multi-state characters in a phylogenetic matrix.
A simple way to characterise trees is to count the number of edges. (Edges are almost, but not quite, equivalent to nodes.) Counting edges (or nodes) provides a quick measure of a tree's resolution, and underpins the Robinson-Foulds tree distance measure. Not all edges, however, are created equal.
An edge splits the leaves of a tree into two subdivisions. The more equal these subdivisions are in size, the more instructive this edge is. Intuitively, the division of mammals from reptiles is a profound revelation that underpins much of zoology; recognizing that two species of bat are more closely related to each other than to any other mammal or reptile is still instructive, but somewhat less fundamental.
Formally, the phylogenetic (Shannon) information content of a split S, h(S), corresponds to the probability that a uniformly selected random tree will contain the split, P(S): h(S) = -log P(S). Base 2 logarithms are typically employed to yield an information content in bits.
As an example, the split AB|CDEF
occurs in 15 of the 105 six-leaf trees;
h(AB|CDEF
) = -log P(AB|CDEF
) = -log(15/105) ~ 2.81 bits. The split
ABC|DEF
subdivides the leaves more evenly, and is thus more instructive:
it occurs in just nine of the 105 six-leaf trees, and
h(ABC|DEF
) = -log(9/105) ~ 3.54 bits.
As the number of leaves increases, a single even split may contain more information than multiple uneven splits – see the examples section below.
Summing the information content of all splits within a tree, perhaps using
the 'TreeDist' function
SplitwiseInfo()
,
arguably gives a more instructive picture of its resolution than simply
counting the number of splits that are present – though with the caveat
that splits within a tree are not independent of one another, so some
information may be double counted. (This same charge applies to simply
counting nodes, too.)
Alternatives would be to count the number of quartets that are resolved,
perhaps using the 'Quartet' function
QuartetStates()
,
or to use a different take on the information contained within a split, the
clustering information: see the 'TreeDist' function
ClusteringInfo()
for details.
SplitInformation()
and MultiSplitInformation()
return the
phylogenetic information content, in bits, of a split that subdivides leaves
into partitions of the specified sizes.
Martin R. Smith ([email protected])
Steel MA, Penny D (2006). “Maximum parsimony and the phylogenetic information in multistate characters.” In Albert VA (ed.), Parsimony, Phylogeny, and Genomics, 163–178. Oxford University Press, Oxford.
Sum the phylogenetic information content of splits within a tree:
TreeDist::SplitwiseInfo()
Sum the clustering information content of splits within a tree:
TreeDist::ClusteringInfo()
Other split information functions:
CharacterInformation()
,
SplitMatchProbability()
,
TreesMatchingSplit()
,
UnrootedTreesMatchingSplit()
# Eight leaves can be split evenly: SplitInformation(4, 4) # or unevenly, which is less informative: SplitInformation(2, 6) # A single split that evenly subdivides 50 leaves contains more information # that seven maximally uneven splits on the same leaves: SplitInformation(25, 25) 7 * SplitInformation(2, 48) # Three ways to split eight leaves into multiple partitions: MultiSplitInformation(c(2, 2, 4)) MultiSplitInformation(c(2, 3, 3)) MultiSplitInformation(rep(2, 4))
# Eight leaves can be split evenly: SplitInformation(4, 4) # or unevenly, which is less informative: SplitInformation(2, 6) # A single split that evenly subdivides 50 leaves contains more information # that seven maximally uneven splits on the same leaves: SplitInformation(25, 25) 7 * SplitInformation(2, 48) # Three ways to split eight leaves into multiple partitions: MultiSplitInformation(c(2, 2, 4)) MultiSplitInformation(c(2, 3, 3)) MultiSplitInformation(rep(2, 4))
(Ln
)SplitMatchProbability()
calculates the probability that two random
splits of the sizes provided will be at least as similar as the two
specified.
SplitMatchProbability(split1, split2) LnSplitMatchProbability(split1, split2)
SplitMatchProbability(split1, split2) LnSplitMatchProbability(split1, split2)
split1 , split2
|
Logical vectors listing terminals in same order, such that
each terminal is identified as a member of the ingroup ( |
SplitMatchProbability()
returns a numeric giving the proportion
of permissible non-trivial splits that divide the terminals into bipartitions
of the sizes given, that match as well as split1
and split2
do.
LnSplitMatchProbability()
returns the natural logarithm of the
probability.
Martin R. Smith ([email protected])
Other split information functions:
CharacterInformation()
,
SplitInformation()
,
TreesMatchingSplit()
,
UnrootedTreesMatchingSplit()
split1 <- as.Splits(c(rep(TRUE, 4), rep(FALSE, 4))) split2 <- as.Splits(c(rep(TRUE, 3), rep(FALSE, 5))) SplitMatchProbability(split1, split2) LnSplitMatchProbability(split1, split2)
split1 <- as.Splits(c(rep(TRUE, 4), rep(FALSE, 4))) split2 <- as.Splits(c(rep(TRUE, 3), rep(FALSE, 5))) SplitMatchProbability(split1, split2) LnSplitMatchProbability(split1, split2)
Splits
as.Splits()
converts a phylogenetic tree to a Splits
object representing
its constituent bipartition splits.
as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'phylo' as.Splits(x, tipLabels = NULL, asSplits = TRUE, ...) ## S3 method for class 'multiPhylo' as.Splits(x, tipLabels = unique(unlist(TipLabels(x))), asSplits = TRUE, ...) ## S3 method for class 'Splits' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'list' as.Splits(x, tipLabels = NULL, asSplits = TRUE, ...) ## S3 method for class 'matrix' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'logical' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'character' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'Splits' as.logical(x, tipLabels = attr(x, "tip.label"), ...)
as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'phylo' as.Splits(x, tipLabels = NULL, asSplits = TRUE, ...) ## S3 method for class 'multiPhylo' as.Splits(x, tipLabels = unique(unlist(TipLabels(x))), asSplits = TRUE, ...) ## S3 method for class 'Splits' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'list' as.Splits(x, tipLabels = NULL, asSplits = TRUE, ...) ## S3 method for class 'matrix' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'logical' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'character' as.Splits(x, tipLabels = NULL, ...) ## S3 method for class 'Splits' as.logical(x, tipLabels = attr(x, "tip.label"), ...)
x |
Object to convert into splits: perhaps a tree of class
|
tipLabels |
Character vector specifying sequence in which to order
tip labels. Label order must (currently) match to combine or compare separate
|
... |
Presently unused. |
asSplits |
Logical specifying whether to return a |
as.Splits()
returns an object of class Splits
, or
(if asSplits = FALSE
) a two-dimensional array of raw
objects, with
each bit specifying whether or not the leaf corresponding to the respective
bit position is a member of the split.
Splits are named according to the node at the non-root end of the edge that
defines them. In rooted trees, the child of the rightmost root edge names
the split.
Martin R. Smith ([email protected])
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
splits <- as.Splits(BalancedTree(letters[1:6])) summary(splits) TipsInSplits(splits) summary(!splits) TipsInSplits(!splits) length(splits + !splits) length(unique(splits + !splits)) summary(c(splits[[2:3]], !splits[[1:2]])) moreSplits <- as.Splits(PectinateTree(letters[6:1]), tipLabel = splits) print(moreSplits, details = TRUE) match(splits, moreSplits) moreSplits %in% splits as.Splits("....**", letters[1:6])
splits <- as.Splits(BalancedTree(letters[1:6])) summary(splits) TipsInSplits(splits) summary(!splits) TipsInSplits(!splits) length(splits + !splits) length(unique(splits + !splits)) summary(c(splits[[2:3]], !splits[[1:2]])) moreSplits <- as.Splits(PectinateTree(letters[6:1]), tipLabel = splits) print(moreSplits, details = TRUE) match(splits, moreSplits) moreSplits %in% splits as.Splits("....**", letters[1:6])
SplitsInBinaryTree()
is a convenience function to calculate the number of
splits in a fully-resolved (binary) tree with n leaves.
SplitsInBinaryTree(tree) ## S3 method for class 'list' SplitsInBinaryTree(tree) ## S3 method for class 'multiPhylo' SplitsInBinaryTree(tree) ## S3 method for class 'numeric' SplitsInBinaryTree(tree) ## S3 method for class ''NULL'' SplitsInBinaryTree(tree) ## Default S3 method: SplitsInBinaryTree(tree) ## S3 method for class 'Splits' SplitsInBinaryTree(tree) ## S3 method for class 'phylo' SplitsInBinaryTree(tree)
SplitsInBinaryTree(tree) ## S3 method for class 'list' SplitsInBinaryTree(tree) ## S3 method for class 'multiPhylo' SplitsInBinaryTree(tree) ## S3 method for class 'numeric' SplitsInBinaryTree(tree) ## S3 method for class ''NULL'' SplitsInBinaryTree(tree) ## Default S3 method: SplitsInBinaryTree(tree) ## S3 method for class 'Splits' SplitsInBinaryTree(tree) ## S3 method for class 'phylo' SplitsInBinaryTree(tree)
tree |
An object of a supported format that represents a tree or set of trees, from which the number of leaves will be calculated. |
SplitsInBinaryTree()
returns an integer vector detailing the number
of unique non-trivial splits in a binary tree with n leaves.
Martin R. Smith ([email protected])
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NSplits()
,
NTip()
,
NodeNumbers()
,
PathLengths()
,
TipLabels()
,
TreeIsRooted()
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
TipLabels()
,
TipsInSplits()
,
match.Splits
,
xor()
tree <- BalancedTree(8) SplitsInBinaryTree(tree) SplitsInBinaryTree(as.Splits(tree)) SplitsInBinaryTree(8) SplitsInBinaryTree(list(tree, tree))
tree <- BalancedTree(8) SplitsInBinaryTree(tree) SplitsInBinaryTree(as.Splits(tree)) SplitsInBinaryTree(8) SplitsInBinaryTree(list(tree, tree))
Functions to describe the position of a leaf relative to the root. "Stemmier" leaves ought to exhibit a smaller root-node distance and a larger sister size.
SisterSize(tree, tip) ## S3 method for class 'numeric' SisterSize(tree, tip) ## S3 method for class 'character' SisterSize(tree, tip) RootNodeDistance(tree, tip) ## S3 method for class 'numeric' RootNodeDistance(tree, tip) ## S3 method for class 'character' RootNodeDistance(tree, tip) RootNodeDist(tree, tip)
SisterSize(tree, tip) ## S3 method for class 'numeric' SisterSize(tree, tip) ## S3 method for class 'character' SisterSize(tree, tip) RootNodeDistance(tree, tip) ## S3 method for class 'numeric' RootNodeDistance(tree, tip) ## S3 method for class 'character' RootNodeDistance(tree, tip) RootNodeDist(tree, tip)
tree |
A tree of class |
tip |
Either a numeric specifying the index of a single tip, or a character specifying its label. |
RootNodeDistance()
calculates the number of nodes between the chosen leaf
and the root of tree
.
This is an unsatisfactory measure, as the range of possible
distances is a function of the shape of the tree
(Asher and Smith 2022).
As an example, leaf X1 in the tree (.,(.,(.,(.,(X1,(a,b))))))
falls outside the clade (a, b) and has a root-node distance of 4,
whereas leaf X2 in the tree (.,((.,(.,.)),(b,(X2,a))))
falls within the clade (a, b), so should be considered more "crownwards",
yet has a smaller root-node distance (3).
SisterSize()
measures the number of leaves in the clade that is sister to
the chosen leaf, as proposed by Asher and Smith (2022).
In the examples above, X1 has a sister size of 2 leaves, whereas X2,
which is "more crownwards", has a smaller sister size (1 leaf), as desired.
SisterSize()
returns an integer specifying the number of leaves
in the clade that is sister to tip
.
RootNodeDist()
returns an integer specifying the number of nodes between
tip
and the root node of tree
.
Martin R. Smith ([email protected])
Asher R, Smith MR (2022). “Phylogenetic signal and bias in paleontology.” Systematic Biology, 71(4), 986–1008. doi:10.1093/sysbio/syab072.
Other tree characterization functions:
CladisticInfo()
,
Consensus()
,
J1Index()
,
TotalCopheneticIndex()
bal8 <- BalancedTree(8) pec8 <- PectinateTree(8) SisterSize(bal8, 3) SisterSize(pec8, "t3") SisterSize(RootTree(pec8, "t3"), "t3") RootNodeDist(bal8, 3) RootNodeDist(pec8, "t3") RootNodeDist(RootTree(pec8, "t3"), "t3")
bal8 <- BalancedTree(8) pec8 <- PectinateTree(8) SisterSize(bal8, 3) SisterSize(pec8, "t3") SisterSize(RootTree(pec8, "t3"), "t3") RootNodeDist(bal8, 3) RootNodeDist(pec8, "t3") RootNodeDist(RootTree(pec8, "t3"), "t3")
phyDat
objectsPhyDatToString()
converts a phyDat
object as a string;
StringToPhyDat()
converts a string of character data to a phyDat
object.
StringToPhyDat(string, tips, byTaxon = TRUE) StringToPhydat(string, tips, byTaxon = TRUE) PhyToString( phy, parentheses = "{", collapse = "", ps = "", useIndex = TRUE, byTaxon = TRUE, concatenate = TRUE ) PhyDatToString( phy, parentheses = "{", collapse = "", ps = "", useIndex = TRUE, byTaxon = TRUE, concatenate = TRUE ) PhydatToString( phy, parentheses = "{", collapse = "", ps = "", useIndex = TRUE, byTaxon = TRUE, concatenate = TRUE )
StringToPhyDat(string, tips, byTaxon = TRUE) StringToPhydat(string, tips, byTaxon = TRUE) PhyToString( phy, parentheses = "{", collapse = "", ps = "", useIndex = TRUE, byTaxon = TRUE, concatenate = TRUE ) PhyDatToString( phy, parentheses = "{", collapse = "", ps = "", useIndex = TRUE, byTaxon = TRUE, concatenate = TRUE ) PhydatToString( phy, parentheses = "{", collapse = "", ps = "", useIndex = TRUE, byTaxon = TRUE, concatenate = TRUE )
string |
String of tokens, optionally containing whitespace, with no terminating semi-colon. |
tips |
(Optional) Character vector corresponding to the names (in order) of each taxon in the matrix, or an object such as a tree from which tip labels can be extracted. |
byTaxon |
Logical. If |
phy |
An object of class |
parentheses |
Character specifying format of parentheses with which to
surround ambiguous tokens. Choose from: |
collapse |
Character specifying text, perhaps |
ps |
Character specifying text, perhaps |
useIndex |
Logical (default: |
concatenate |
Logical specifying whether to concatenate all characters/taxa into a single string, or to return a separate string for each entry. |
StringToPhyDat()
returns an object of class phyDat
.
PhyToString()
returns a character vector listing a text
representation of the phylogenetic character state for each taxon in turn.
Martin R. Smith ([email protected])
Other phylogenetic matrix conversion functions:
Decompose()
,
MatrixToPhyDat()
StringToPhyDat("-?01231230?-", c("Lion", "Gazelle"), byTaxon = TRUE) # encodes the following matrix: # Lion -?0123 # Gazelle 1230?- fileName <- paste0(system.file(package = "TreeTools"), "/extdata/input/dataset.nex") phyDat <- ReadAsPhyDat(fileName) PhyToString(phyDat, concatenate = FALSE)
StringToPhyDat("-?01231230?-", c("Lion", "Gazelle"), byTaxon = TRUE) # encodes the following matrix: # Lion -?0123 # Gazelle 1230?- fileName <- paste0(system.file(package = "TreeTools"), "/extdata/input/dataset.nex") phyDat <- ReadAsPhyDat(fileName) PhyToString(phyDat, concatenate = FALSE)
Subsplit()
removes leaves from a Splits
object.
Subsplit(splits, tips, keepAll = FALSE, unique = TRUE)
Subsplit(splits, tips, keepAll = FALSE, unique = TRUE)
splits |
An object of class |
tips |
A vector specifying a subset of the leaf labels applied to |
keepAll |
logical specifying whether to keep entries that define trivial splits (i.e. splits of zero or one leaf) on the subset of leaves. |
unique |
logical specifying whether to remove duplicate splits. |
Subsplit()
returns an object of class Splits
, defined on the
leaves tips
.
Martin R. Smith ([email protected])
KeepTip()
is a less flexible but faster equivalent.
Other split manipulation functions:
DropTip()
,
TrivialSplits()
splits <- as.Splits(PectinateTree(letters[1:9])) splits efgh <- Subsplit(splits, tips = letters[5:8], keepAll = TRUE) summary(efgh) TrivialSplits(efgh) summary(Subsplit(splits, tips = letters[5:8], keepAll = FALSE))
splits <- as.Splits(PectinateTree(letters[1:9])) splits efgh <- Subsplit(splits, tips = letters[5:8], keepAll = TRUE) summary(efgh) TrivialSplits(efgh) summary(Subsplit(splits, tips = letters[5:8], keepAll = FALSE))
Subtree()
safely extracts a clade from a phylogenetic tree.
Subtree(tree, node)
Subtree(tree, node)
tree |
A tree of class |
node |
The number of the node at the base of the clade to be extracted. |
Modified from the ape function extract.clade
, which
sometimes behaves unpredictably.
Unlike extract.clade, this function supports the extraction of "clades"
that constitute a single tip.
Subtree()
returns a tree of class phylo
that represents a
clade extracted from the original tree.
Martin R. Smith ([email protected])
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
TipTimedTree()
,
TrivialTree
tree <- Preorder(BalancedTree(8)) plot(tree) ape::nodelabels() ape::nodelabels(13, 13, bg="yellow") plot(Subtree(tree, 13))
tree <- Preorder(BalancedTree(8)) plot(tree) ape::nodelabels() ape::nodelabels(13, 13, bg="yellow") plot(Subtree(tree, 13))
Colour value with which to display node support.
SupportColour( support, show1 = TRUE, scale = rev(diverge_hcl(101, h = c(260, 0), c = 100, l = c(50, 90), power = 1)), outOfRange = "red" ) SupportColor( support, show1 = TRUE, scale = rev(diverge_hcl(101, h = c(260, 0), c = 100, l = c(50, 90), power = 1)), outOfRange = "red" )
SupportColour( support, show1 = TRUE, scale = rev(diverge_hcl(101, h = c(260, 0), c = 100, l = c(50, 90), power = 1)), outOfRange = "red" ) SupportColor( support, show1 = TRUE, scale = rev(diverge_hcl(101, h = c(260, 0), c = 100, l = c(50, 90), power = 1)), outOfRange = "red" )
support |
A numeric vector of values in the range 0–1. |
show1 |
Logical specifying whether to display values of 1.
A transparent white will be returned if |
scale |
101-element vector listing colours in sequence. Defaults to a diverging HCL scale. |
outOfRange |
Colour to use if results are outside the range 0–1. |
SupportColour()
returns the appropriate value from scale
,
or outOfRange
if a value is outwith the valid range.
Use in conjunction with LabelSplits()
to colour split labels,
possibly calculated using SplitFrequency()
.
SupportColour((-1):4 / 4, show1 = FALSE) # An example forest of 100 trees, some identical forest <- as.phylo(c(1, rep(10, 79), rep(100, 15), rep(1000, 5)), nTip = 9) # Generate an 80% consensus tree cons <- ape::consensus(forest, p = 0.8) plot(cons) # Calculate split frequencies splitFreqs <- SplitFrequency(cons, forest) # Optionally, colour edges by corresponding frequency. # Note that not all edges are associated with a unique split # (and two root edges may be associated with one split - not handled here) edgeSupport <- rep(1, nrow(cons$edge)) # Initialize trivial splits to 1 childNode <- cons$edge[, 2] edgeSupport[match(names(splitFreqs), childNode)] <- splitFreqs / 100 plot(cons, edge.col = SupportColour(edgeSupport), edge.width = 3) # Annotate nodes by frequency LabelSplits(cons, splitFreqs, unit = "%", col = SupportColor(splitFreqs / 100), frame = "none", pos = 3L)
SupportColour((-1):4 / 4, show1 = FALSE) # An example forest of 100 trees, some identical forest <- as.phylo(c(1, rep(10, 79), rep(100, 15), rep(1000, 5)), nTip = 9) # Generate an 80% consensus tree cons <- ape::consensus(forest, p = 0.8) plot(cons) # Calculate split frequencies splitFreqs <- SplitFrequency(cons, forest) # Optionally, colour edges by corresponding frequency. # Note that not all edges are associated with a unique split # (and two root edges may be associated with one split - not handled here) edgeSupport <- rep(1, nrow(cons$edge)) # Initialize trivial splits to 1 childNode <- cons$edge[, 2] edgeSupport[match(names(splitFreqs), childNode)] <- splitFreqs / 100 plot(cons, edge.col = SupportColour(edgeSupport), edge.width = 3) # Annotate nodes by frequency LabelSplits(cons, splitFreqs, unit = "%", col = SupportColor(splitFreqs / 100), frame = "none", pos = 3L)
TipLabels()
extracts labels from an object: for example, names of taxa in
a phylogenetic tree or data matrix. AllTipLabels()
extracts all labels,
where entries of a list of trees may pertain to different taxa.
TipLabels(x, single = TRUE) ## Default S3 method: TipLabels(x, single = TRUE) ## S3 method for class 'matrix' TipLabels(x, single = TRUE) ## S3 method for class 'logical' TipLabels(x, single = TRUE) ## S3 method for class 'phylo' TipLabels(x, single = TRUE) ## S3 method for class 'phyDat' TipLabels(x, single = TRUE) ## S3 method for class 'MixedBase' TipLabels(x, single = TRUE) ## S3 method for class 'TreeNumber' TipLabels(x, single = TRUE) ## S3 method for class 'Splits' TipLabels(x, single = TRUE) ## S3 method for class 'list' TipLabels(x, single = FALSE) ## S3 method for class 'multiPhylo' TipLabels(x, single = FALSE) ## S3 method for class 'character' TipLabels(x, single = TRUE) ## S3 method for class 'numeric' TipLabels(x, single = TRUE) ## S3 method for class 'phyDat' TipLabels(x, single = TRUE) AllTipLabels(x) ## S3 method for class 'list' AllTipLabels(x) ## S3 method for class 'multiPhylo' AllTipLabels(x) ## S3 method for class 'phylo' AllTipLabels(x) ## S3 method for class 'Splits' AllTipLabels(x) ## S3 method for class 'TreeNumber' AllTipLabels(x) ## S3 method for class 'matrix' AllTipLabels(x)
TipLabels(x, single = TRUE) ## Default S3 method: TipLabels(x, single = TRUE) ## S3 method for class 'matrix' TipLabels(x, single = TRUE) ## S3 method for class 'logical' TipLabels(x, single = TRUE) ## S3 method for class 'phylo' TipLabels(x, single = TRUE) ## S3 method for class 'phyDat' TipLabels(x, single = TRUE) ## S3 method for class 'MixedBase' TipLabels(x, single = TRUE) ## S3 method for class 'TreeNumber' TipLabels(x, single = TRUE) ## S3 method for class 'Splits' TipLabels(x, single = TRUE) ## S3 method for class 'list' TipLabels(x, single = FALSE) ## S3 method for class 'multiPhylo' TipLabels(x, single = FALSE) ## S3 method for class 'character' TipLabels(x, single = TRUE) ## S3 method for class 'numeric' TipLabels(x, single = TRUE) ## S3 method for class 'phyDat' TipLabels(x, single = TRUE) AllTipLabels(x) ## S3 method for class 'list' AllTipLabels(x) ## S3 method for class 'multiPhylo' AllTipLabels(x) ## S3 method for class 'phylo' AllTipLabels(x) ## S3 method for class 'Splits' AllTipLabels(x) ## S3 method for class 'TreeNumber' AllTipLabels(x) ## S3 method for class 'matrix' AllTipLabels(x)
x |
An object of a supported class (see Usage section above). |
single |
Logical specifying whether to report the labels for the first
object only ( |
TipLabels()
returns a character vector listing the tip labels
appropriate to x
. If x
is a single integer, this will be a vector
t1
, t2
... tx
, to match the default of rtree()
.
Martin R. Smith ([email protected])
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NSplits()
,
NTip()
,
NodeNumbers()
,
PathLengths()
,
SplitsInBinaryTree()
,
TreeIsRooted()
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipsInSplits()
,
match.Splits
,
xor()
TipLabels(BalancedTree(letters[5:1])) TipLabels(5) data("Lobo") head(TipLabels(Lobo.phy)) AllTipLabels(c(BalancedTree(4), PectinateTree(8)))
TipLabels(BalancedTree(letters[5:1])) TipLabels(5) data("Lobo") head(TipLabels(Lobo.phy)) AllTipLabels(c(BalancedTree(4), PectinateTree(8)))
TipsInSplits()
specifies the number of tips that occur within each
bipartition split in a Splits
object.
TipsInSplits(splits, keep.names = TRUE, smallest = FALSE, ...) ## S3 method for class 'Splits' TipsInSplits(splits, keep.names = TRUE, smallest = FALSE, ...) ## S3 method for class 'phylo' TipsInSplits(splits, keep.names = TRUE, smallest = FALSE, ...) SplitImbalance(splits, keep.names = TRUE, ...) ## S3 method for class 'Splits' SplitImbalance(splits, keep.names = TRUE, ...) ## S3 method for class 'phylo' SplitImbalance(splits, keep.names = TRUE, ...)
TipsInSplits(splits, keep.names = TRUE, smallest = FALSE, ...) ## S3 method for class 'Splits' TipsInSplits(splits, keep.names = TRUE, smallest = FALSE, ...) ## S3 method for class 'phylo' TipsInSplits(splits, keep.names = TRUE, smallest = FALSE, ...) SplitImbalance(splits, keep.names = TRUE, ...) ## S3 method for class 'Splits' SplitImbalance(splits, keep.names = TRUE, ...) ## S3 method for class 'phylo' SplitImbalance(splits, keep.names = TRUE, ...)
splits |
Object of class |
keep.names |
Logical specifying whether to include the names of |
smallest |
Logical; if |
... |
Additional parameters to pass to |
TipsInSplits()
returns a named vector of integers, specifying the
number of tips contained within each split in splits
.
SplitImbalance()
returns a named vector of integers, specifying the
number of leaves within a split that are not "balanced" by a leaf outside it;
i.e. a split that divides leaves evenly has an imbalance of zero; one that
splits two tips from ten has an imbalance of 10 - 2 = 8.
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
match.Splits
,
xor()
tree <- PectinateTree(8) splits <- as.Splits(tree) TipsInSplits(splits) plot(tree) LabelSplits(tree, as.character(splits), frame = "none", pos = 3L, cex = 0.7) LabelSplits(tree, TipsInSplits(splits), unit = " tips", frame = "none", pos = 1L)
tree <- PectinateTree(8) splits <- as.Splits(tree) TipsInSplits(splits) plot(tree) LabelSplits(tree, as.character(splits), frame = "none", pos = 3L, cex = 0.7) LabelSplits(tree, TipsInSplits(splits), unit = " tips", frame = "none", pos = 1L)
TipTimedTree()
plots a phylogenetic tree against time using an
ad hoc approach based on dates associated with the leaves.
Nodes are dated to the youngest possible value, plus an additional "buffer"
(specified with minEdge
) to ensure that branching order is readable.
TipTimedTree(tree, tipAge, minEdge = 1)
TipTimedTree(tree, tipAge, minEdge = 1)
tree |
A tree of class |
tipAge |
Numeric vector specifying the age (in units-of-time ago)
associated with each tip in |
minEdge |
Minimum length of edge to allow (in units-of-time) |
This experimental function is liable to change its behaviour, or to be deprecated, in coming releases. Please contact the maintainer if you find it useful, so that a production-ready version can be prioritized.
TipTimedTree()
returns a tree with edge lengths set based on the
ages of each tip.
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TrivialTree
tree <- BalancedTree(6) plot(TipTimedTree(tree, tipAge = 1:6, minEdge = 2))
tree <- BalancedTree(6) plot(TipTimedTree(tree, tipAge = 1:6, minEdge = 2))
TopologyOnly()
removes all information from trees except for their
topologies and leaf labels. This allows other functions to process
trees more rapidly, as they do not need to process unneeded metadata.
TopologyOnly(tree)
TopologyOnly(tree)
tree |
A tree of class |
Returns tree
, with each tree in Preorder
, with edge lengths,
node labels and other attributes removed.
Martin R. Smith ([email protected])
TotalCopheneticIndex()
calculates the total cophenetic index
(Mir et al. 2013) for any tree, a measure of its balance;
TCIContext()
lists its possible values.
TotalCopheneticIndex(x) TCIContext(x) ## S3 method for class 'numeric' TCIContext(x)
TotalCopheneticIndex(x) TCIContext(x) ## S3 method for class 'numeric' TCIContext(x)
x |
A tree of class |
The Total Cophenetic Index is a measure of tree balance – i.e. whether a (phylogenetic) tree comprises symmetric pairs of nodes, or has a pectinate "caterpillar" shape. The index has a greater resolution power than Sackin's and Colless' indices, and can be applied to trees that are not perfectly resolved.
For a tree with n leaves, the Total Cophenetic Index can take values of
0 to choose(n, 3)
.
The minimum value is higher for a perfectly resolved (i.e. dichotomous) tree
(see Lemma 14 of Mir et al. 2013).
Formulae to calculate the expected values under the Yule and Uniform models
of evolution are given in Theorems 17 and 23.
Full details are provided by Mir et al. (2013).
The J1 index
(Lemant et al. 2022) has advantages over the Total Cophenetic
Index, particularly when comparing trees with different numbers of leaves,
or where the population size of nodes is meaningful; see J1Index()
.
TotalCopheneticIndex()
returns an integer denoting the total cophenetic index.
TCIContext()
returns a data frame detailing the maximum and minimum value
obtainable for the Total Cophenetic Index for rooted binary trees with the
number of leaves of the given tree, and the expected value under the Yule
and Uniform models.
The variance of the expected value is given under the Yule model, but cannot
be obtained by calculation for the Uniform model.
Martin R. Smith ([email protected])
Lemant J, Le Sueur C, Manojlović V, Noble R (2022).
“Robust, Universal Tree Balance Indices.”
Systematic Biology, 71(5), 1210–1224.
doi:10.1093/sysbio/syac027.
Mir A, Rosselló F, Rotger LA (2013).
“A new balance index for phylogenetic trees.”
Mathematical Biosciences, 241(1), 125–136.
doi:10.1016/j.mbs.2012.10.005.
J1Index()
provides a more robust, universal tree balance index.
cophen.index()
in the package
CollessLike
provides an alternative implementation of this index and its predecessors.
Other tree characterization functions:
CladisticInfo()
,
Consensus()
,
J1Index()
,
Stemwardness
# Balanced trees have the minimum index for a binary tree; # Pectinate trees the maximum: TCIContext(8) TotalCopheneticIndex(PectinateTree(8)) TotalCopheneticIndex(BalancedTree(8)) TotalCopheneticIndex(StarTree(8)) # Examples from Mir et al. (2013): tree12 <- ape::read.tree(text="(1, (2, (3, (4, 5))));") #Fig. 4, tree 12 TotalCopheneticIndex(tree12) # 10 tree8 <- ape::read.tree(text="((1, 2, 3, 4), 5);") #Fig. 4, tree 8 TotalCopheneticIndex(tree8) # 6 TCIContext(tree8) TCIContext(5L) # Context for a tree with 5 leaves.
# Balanced trees have the minimum index for a binary tree; # Pectinate trees the maximum: TCIContext(8) TotalCopheneticIndex(PectinateTree(8)) TotalCopheneticIndex(BalancedTree(8)) TotalCopheneticIndex(StarTree(8)) # Examples from Mir et al. (2013): tree12 <- ape::read.tree(text="(1, (2, (3, (4, 5))));") #Fig. 4, tree 12 TotalCopheneticIndex(tree12) # 10 tree8 <- ape::read.tree(text="((1, 2, 3, 4), 5);") #Fig. 4, tree 8 TotalCopheneticIndex(tree8) # 6 TCIContext(tree8) TCIContext(5L) # Context for a tree with 5 leaves.
TreeIsRooted()
is a fast alternative to ape::is.rooted()
.
TreeIsRooted(tree)
TreeIsRooted(tree)
tree |
A phylogenetic tree of class |
TreeIsRooted()
returns a logical specifying whether a root node is
resolved.
Martin R. Smith ([email protected])
Other tree properties:
ConsensusWithout()
,
MatchEdges()
,
NSplits()
,
NTip()
,
NodeNumbers()
,
PathLengths()
,
SplitsInBinaryTree()
,
TipLabels()
TreeIsRooted(BalancedTree(6)) TreeIsRooted(UnrootTree(BalancedTree(6)))
TreeIsRooted(BalancedTree(6)) TreeIsRooted(UnrootTree(BalancedTree(6)))
Functions converting between phylogenetic trees and their unique decimal representation, based on a concept by John Tromp, employed in (Li et al. 1996).
as.TreeNumber(x, ...) ## S3 method for class 'phylo' as.TreeNumber(x, ...) ## S3 method for class 'multiPhylo' as.TreeNumber(x, ...) ## S3 method for class 'character' as.TreeNumber(x, nTip, tipLabels = TipLabels(nTip), ...) ## S3 method for class 'TreeNumber' as.TreeNumber(x, ...) ## S3 method for class 'MixedBase' as.TreeNumber(x, ...) ## S3 method for class 'TreeNumber' as.MixedBase(x, ...) ## S3 method for class 'integer64' as.MixedBase(x, tipLabels = NULL, ...) ## S3 method for class 'numeric' as.MixedBase(x, tipLabels = NULL, ...) ## S3 method for class 'numeric' as.phylo(x, nTip = attr(x, "nTip"), tipLabels = attr(x, "tip.label"), ...) ## S3 method for class 'TreeNumber' as.phylo(x, nTip = attr(x, "nTip"), tipLabels = attr(x, "tip.label"), ...) as.MixedBase(x, ...) ## S3 method for class 'MixedBase' as.MixedBase(x, ...) ## S3 method for class 'phylo' as.MixedBase(x, ...) ## S3 method for class 'multiPhylo' as.MixedBase(x, ...) ## S3 method for class 'MixedBase' as.phylo(x, nTip = attr(x, "nTip"), tipLabels = attr(x, "tip.label"), ...)
as.TreeNumber(x, ...) ## S3 method for class 'phylo' as.TreeNumber(x, ...) ## S3 method for class 'multiPhylo' as.TreeNumber(x, ...) ## S3 method for class 'character' as.TreeNumber(x, nTip, tipLabels = TipLabels(nTip), ...) ## S3 method for class 'TreeNumber' as.TreeNumber(x, ...) ## S3 method for class 'MixedBase' as.TreeNumber(x, ...) ## S3 method for class 'TreeNumber' as.MixedBase(x, ...) ## S3 method for class 'integer64' as.MixedBase(x, tipLabels = NULL, ...) ## S3 method for class 'numeric' as.MixedBase(x, tipLabels = NULL, ...) ## S3 method for class 'numeric' as.phylo(x, nTip = attr(x, "nTip"), tipLabels = attr(x, "tip.label"), ...) ## S3 method for class 'TreeNumber' as.phylo(x, nTip = attr(x, "nTip"), tipLabels = attr(x, "tip.label"), ...) as.MixedBase(x, ...) ## S3 method for class 'MixedBase' as.MixedBase(x, ...) ## S3 method for class 'phylo' as.MixedBase(x, ...) ## S3 method for class 'multiPhylo' as.MixedBase(x, ...) ## S3 method for class 'MixedBase' as.phylo(x, nTip = attr(x, "nTip"), tipLabels = attr(x, "tip.label"), ...)
x |
Integer identifying the tree (see details). |
... |
Additional parameters for consistency with S3 methods (unused). |
nTip |
Integer specifying number of leaves in the tree. |
tipLabels |
Character vector listing the labels assigned to each tip
in a tree, perhaps obtained using |
There are NUnrooted(n)
unrooted trees with n leaves.
As such, each n-leaf tree can be uniquely identified by a non-negative
integer x < NUnrooted(n)
.
This integer can be converted by a tree by treating it as a mixed-base number, with bases 1, 3, 5, 7, … (2 n - 5).
Each digit of this mixed base number corresponds to a leaf, and determines the location on a growing tree to which that leaf should be added.
We start with a two-leaf tree, and treat 0 as the origin of the tree.
0 ---- 1
We add leaf 2 by breaking an edge and inserting a node (numbered
2 + nTip - 1
).
In this example, we'll work up to a six-leaf tree; this node will be numbered
2 + 6 - 1 = 7.
There is only one edge on which leaf 2 can be added. Let's add node 7 and
leaf 2:
0 ---- 7 ---- 1 | | 2
There are now three edges on which leaf 3 can be added. Our options are:
Option 0: the edge leading to 1;
Option 1: the edge leading to 2;
Option 2: the edge leading to 7.
If we select option 1, we produce:
0 ---- 7 ---- 1 | | 8 ---- 2 | | 3
1
is now the final digit of our mixed-base number.
There are five places to add leaf 4:
Option 0: the edge leading to 1;
Option 1: the edge leading to 2;
Option 2: the edge leading to 3;
Option 3: the edge leading to 7;
Option 4: the edge leading to 8.
If we chose option 3, then 3
would be the penultimate digit of our
mixed-base number.
If we chose option 0 for the next two additions, we could specify this tree with the mixed-base number 0021. We can convert this into decimal:
0 × (1 × 3 × 5 × 9) +
0 × (1 × 3 × 5) +
3 × (1 × 3) +
1 × (1)
= 10
Note that the hyperexponential nature of tree space means that there are >
2^64 unique 20-leaf trees. As a TreeNumber
is a 64-bit integer,
only trees with at most 19 leaves can be accommodated.
as.TreeNumber()
returns an object of class TreeNumber
,
which comprises a numeric vector, whose elements represent successive
nine-digit chunks of the decimal integer corresponding to the tree topology
(in big endian order). The TreeNumber
object has attributes
nTip
and tip.label
. If x
is a list of trees or a multiPhylo
object,
then as.TreeNumber()
returns a corresponding list of TreeNumber
objects.
as.phylo.numeric()
returns a tree of class phylo
.
Martin R. Smith ([email protected])
Li M, Tromp J, Zhang L (1996). “Some notes on the nearest neighbour interchange distance.” In Goos G, Hartmanis J, Leeuwen J, Cai J, Wong CK (eds.), Computing and Combinatorics, volume 1090, 343–351. Springer, Berlin, Heidelberg. ISBN 978-3-540-61332-9, doi:10.1007/3-540-61332-3_168.
Describe the shape of a tree topology, independent of leaf labels:
TreeShape()
Other tree generation functions:
ConstrainedNJ()
,
GenerateTree
,
NJTree()
,
TrivialTree
Other 'TreeNumber' utilities:
is.TreeNumber()
,
print.TreeNumber()
tree <- as.phylo(10, nTip = 6) plot(tree) as.TreeNumber(tree) # Larger trees: as.TreeNumber(BalancedTree(19)) # If > 9 digits, represent the tree number as a string. treeNumber <- as.TreeNumber("1234567890123", nTip = 14) tree <- as.phylo(treeNumber) as.phylo(0:2, nTip = 6, tipLabels = letters[1:6])
tree <- as.phylo(10, nTip = 6) plot(tree) as.TreeNumber(tree) # Larger trees: as.TreeNumber(BalancedTree(19)) # If > 9 digits, represent the tree number as a string. treeNumber <- as.TreeNumber("1234567890123", nTip = 14) tree <- as.phylo(treeNumber) as.phylo(0:2, nTip = 6, tipLabels = letters[1:6])
Calculates the number of unrooted bifurcated trees that are consistent with
a bipartition split that divides taxa into groups of size A
and B
.
TreesMatchingSplit(A, B = A[2]) LnTreesMatchingSplit(A, B = A[2]) Log2TreesMatchingSplit(A, B = A[2])
TreesMatchingSplit(A, B = A[2]) LnTreesMatchingSplit(A, B = A[2]) Log2TreesMatchingSplit(A, B = A[2])
A , B
|
Integer specifying the number of taxa in each partition. |
TreesMatchingSplit()
returns a numeric specifying the number of trees
that are compatible with the given split.
LnTreesMatchingSplit()
and Log2TreesMatchingSplit()
give the natural
and base-2 logarithms of this number.
Martin R. Smith ([email protected])
Other split information functions:
CharacterInformation()
,
SplitInformation()
,
SplitMatchProbability()
,
UnrootedTreesMatchingSplit()
TreesMatchingSplit(5, 6) LnTreesMatchingSplit(5, 6) Log2TreesMatchingSplit(5, 6)
TreesMatchingSplit(5, 6) LnTreesMatchingSplit(5, 6) Log2TreesMatchingSplit(5, 6)
TreesMatchingTree()
calculates the number of unrooted binary trees that
are consistent with a tree topology on the same leaves.
TreesMatchingTree(tree) LnTreesMatchingTree(tree) Log2TreesMatchingTree(tree)
TreesMatchingTree(tree) LnTreesMatchingTree(tree) Log2TreesMatchingTree(tree)
tree |
A tree of class |
Remember to unroot a tree first if the position of its root is arbitrary.
TreesMatchingTree()
returns a numeric specifying the number of
unrooted binary trees that contain all the edges present in the input tree.
LnTreesMatchingTree()
gives the natural logarithm of this number.
Martin R. Smith ([email protected])
Other tree information functions:
CladisticInfo()
,
NRooted()
partiallyResolvedTree <- CollapseNode(BalancedTree(8), 12:15) TreesMatchingTree(partiallyResolvedTree) LnTreesMatchingTree(partiallyResolvedTree) # Number of rooted trees: rootedTree <- AddTip(partiallyResolvedTree, where = 0) TreesMatchingTree(partiallyResolvedTree)
partiallyResolvedTree <- CollapseNode(BalancedTree(8), 12:15) TreesMatchingTree(partiallyResolvedTree) LnTreesMatchingTree(partiallyResolvedTree) # Number of rooted trees: rootedTree <- AddTip(partiallyResolvedTree, where = 0) TreesMatchingTree(partiallyResolvedTree)
TrivialSplits()
identifies trivial splits (which separate one or zero
leaves from all others); WithoutTrivialSplits()
removes them from a
Splits
object.
TrivialSplits(splits, nTip = attr(splits, "nTip")) WithoutTrivialSplits(splits, nTip = attr(splits, "nTip"))
TrivialSplits(splits, nTip = attr(splits, "nTip")) WithoutTrivialSplits(splits, nTip = attr(splits, "nTip"))
splits |
An object of class |
nTip |
Integer specifying number of tips (leaves). |
TrivialSplits()
returns a logical vector specifying whether each
split in splits
is trivial, i.e. includes or excludes only a single tip or
no tips at all.
WithoutTrivialSplits()
returns a Splits
object with trivial
splits removed.
Martin R. Smith ([email protected])
Other split manipulation functions:
DropTip()
,
Subsplit()
splits <- as.Splits(PectinateTree(letters[1:9])) efgh <- Subsplit(splits, tips = letters[5:8], keepAll = TRUE) summary(efgh) TrivialSplits(efgh) summary(WithoutTrivialSplits(efgh))
splits <- as.Splits(PectinateTree(letters[1:9])) efgh <- Subsplit(splits, tips = letters[5:8], keepAll = TRUE) summary(efgh) TrivialSplits(efgh) summary(WithoutTrivialSplits(efgh))
SingleTaxonTree()
creates a phylogenetic "tree" that contains a single
taxon.
ZeroTaxonTree()
creates an empty phylo
object with zero leaves or edges.
SingleTaxonTree(label = "t1") ZeroTaxonTree()
SingleTaxonTree(label = "t1") ZeroTaxonTree()
label |
a character vector specifying the label of the tip. |
SingleTaxonTree()
returns a phylo
object containing a single
tip with the specified label.
ZeroTaxonTree()
returns an empty phylo
object.
Other tree manipulation:
AddTip()
,
CollapseNode()
,
ConsensusWithout()
,
DropTip()
,
EnforceOutgroup()
,
ImposeConstraint()
,
KeptPaths()
,
KeptVerts()
,
LeafLabelInterchange()
,
MakeTreeBinary()
,
Renumber()
,
RenumberTips()
,
RenumberTree()
,
RootTree()
,
SortTree()
,
Subtree()
,
TipTimedTree()
Other tree generation functions:
ConstrainedNJ()
,
GenerateTree
,
NJTree()
,
TreeNumber
SingleTaxonTree("Homo_sapiens") plot(SingleTaxonTree("root") + BalancedTree(4)) ZeroTaxonTree()
SingleTaxonTree("Homo_sapiens") plot(SingleTaxonTree("root") + BalancedTree(4)) ZeroTaxonTree()
Remove quotation marks from a string
Unquote(string)
Unquote(string)
string |
Input string |
Unquote()
returns string
, with any matched punctuation marks
and trailing whitespace removed.
Martin R. Smith
Other string parsing functions:
EndSentence()
,
MorphoBankDecode()
,
RightmostCharacter()
Unquote("'Hello World'")
Unquote("'Hello World'")
Calculates the number of unrooted bifurcating trees consistent with the specified multi-partition split, using theorem two of Carter et al. (1990).
UnrootedTreesMatchingSplit(...) LnUnrootedTreesMatchingSplit(...) Log2UnrootedTreesMatchingSplit(...)
UnrootedTreesMatchingSplit(...) LnUnrootedTreesMatchingSplit(...) Log2UnrootedTreesMatchingSplit(...)
... |
A series or vector of integers listing the number of tips in
each of a number of tree splits (e.g. bipartitions).
For example, |
UnrootedTreesMatchingSplit()
returns an integer specifying the
number of unrooted bifurcating trees consistent with the specified split.
Martin R. Smith ([email protected])
Carter M, Hendy M, Penny D, Székely LA, Wormald NC (1990). “On the distribution of lengths of evolutionary trees.” SIAM Journal on Discrete Mathematics, 3(1), 38–47. doi:10.1137/0403005.
Other split information functions:
CharacterInformation()
,
SplitInformation()
,
SplitMatchProbability()
,
TreesMatchingSplit()
UnrootedTreesMatchingSplit(c(3, 5)) UnrootedTreesMatchingSplit(3, 2, 1, 2)
UnrootedTreesMatchingSplit(c(3, 5)) UnrootedTreesMatchingSplit(3, 2, 1, 2)
UnshiftTree()
adds a phylogenetic tree to the start of a list of trees.
This is useful where the class of a list of trees is unknown, or where
names of trees should be retained.
UnshiftTree(add, treeList)
UnshiftTree(add, treeList)
add |
Tree to add to the list, of class |
treeList |
A list of trees, of class |
Caution: adding a tree to a multiPhylo
object whose own attributes apply
to all trees, for example trees read from a Nexus file, causes data to be
lost.
UnshiftTree()
returns a list of class list
or multiPhylo
(following the original class of treeList
), whose first element is the
tree specified as 'add.
Martin R. Smith ([email protected])
c()
joins a tree or series of trees to a multiPhylo
object, but loses
names and does not handle lists of trees.
forest <- as.phylo(0:5, 6) tree <- BalancedTree(6) UnshiftTree(tree, forest) UnshiftTree(tree, tree)
forest <- as.phylo(0:5, 6) tree <- BalancedTree(6) UnshiftTree(tree, forest) UnshiftTree(tree, tree)
Write morphological character matrix to TNT file
WriteTntCharacters( dataset, filepath = NULL, comment = "Dataset written by `TreeTools::WriteTntCharacters()`", types = NULL, pre = "", post = "" ) ## S3 method for class 'phyDat' WriteTntCharacters( dataset, filepath = NULL, comment = "Dataset written by `TreeTools::WriteTntCharacters()`", types = NULL, pre = "", post = "" ) ## S3 method for class 'matrix' WriteTntCharacters( dataset, filepath = NULL, comment = "Dataset written by `TreeTools::WriteTntCharacters()`", types = NULL, pre = "", post = "" )
WriteTntCharacters( dataset, filepath = NULL, comment = "Dataset written by `TreeTools::WriteTntCharacters()`", types = NULL, pre = "", post = "" ) ## S3 method for class 'phyDat' WriteTntCharacters( dataset, filepath = NULL, comment = "Dataset written by `TreeTools::WriteTntCharacters()`", types = NULL, pre = "", post = "" ) ## S3 method for class 'matrix' WriteTntCharacters( dataset, filepath = NULL, comment = "Dataset written by `TreeTools::WriteTntCharacters()`", types = NULL, pre = "", post = "" )
dataset |
Morphological dataset of class |
filepath |
Path to file; if |
comment |
Optional comment with which to entitle matrix. |
types |
Optional list specifying where different data types begin.
|
pre , post
|
Character vector listing text to print before and after the
character matrix. Specify |
Martin R. Smith ([email protected])
data("Lobo", package = "TreeTools") WriteTntCharacters(Lobo.phy) # Read with extended implied weighting WriteTntCharacters(Lobo.phy, pre = "piwe=10;", post = "xpiwe=;") # Write to a file with: # WriteTntCharacters(Lobo.phy, "example_file.tnt")
data("Lobo", package = "TreeTools") WriteTntCharacters(Lobo.phy) # Read with extended implied weighting WriteTntCharacters(Lobo.phy, pre = "piwe=10;", post = "xpiwe=;") # Write to a file with: # WriteTntCharacters(Lobo.phy, "example_file.tnt")
Exclusive OR operation
xor(x, y) ## S4 method for signature 'Splits,Splits' xor(x, y)
xor(x, y) ## S4 method for signature 'Splits,Splits' xor(x, y)
x , y
|
Objects to be compared. |
Other Splits operations:
LabelSplits()
,
NSplits()
,
NTip()
,
PolarizeSplits()
,
SplitFrequency()
,
Splits
,
SplitsInBinaryTree()
,
TipLabels()
,
TipsInSplits()
,
match.Splits