extendPhylo {treeDbalance}

Useful extensions to the phylo format

Description

extendPhylo - Extends a tree in phylo or phylo3D format, i.e., adds or updates several useful attributes of the tree that facilitate various computations and allow it to be independent of a certain node enumeration. These are: information on descendants, ancestors, and depths as well as on the centroids of all pending subtrees. The latter is only computed if the tree is in phylo3D format and as such contains the attributes 'node.coord' and 'edge.weight'.

getDescs - Creates a matrix with two rows, the second contains in the i-th entry the index of the first row in which the descendants of node i start. Use the function getChildren to quickly retrieve the direct descendants of each node.

getChildren - Creates a vector containing the direct children of a node. If the method indicates that also edges should be returned, this function will also return the number (identifier) of the incoming edge of each child.

getDescendants - Creates a vector containing all descendants of a node.

getAncs - Creates a matrix that contains the parent (direct ancestor) of node i as well as the corresponding edge number in column i.

getNodeDepths - Creates a matrix with three rows: The first contains the nodes ordered by increasing depth. The second contains the indices at which the next depth starts in the first row, i.e., these first two rows are similar to the output matrix of getDescs. The last row contains the depth of each node.

getNodesAtDepth - Creates a vector containing the nodes at a certain depth.

getLeaves - Creates a logical vector that indicates if the i-th node is a leaf.

getSubtrCentr - Calculates the centroid of each pending subtree. Returns a matrix containing the 3D coordinates (3 columns) where row i gives the position of the centroid of T_i, the pending subtree rooted in node i.

getDistFromRoot - Creates a vector containing the length of the path from the node to the root, i.e., the sum of the corresponding edge lengths.

getDistFromLeaf - Creates a vector containing the length of the path from the node to the nearest descendant leaf, i.e., the sum of the corresponding edge lengths.

getIncEdgeLens - Returns the length of the incoming edge of every node as a numeric vector.

getIncEdgeWeights - Returns the weight of the incoming edge of every node as a numeric vector.

Usage

extendPhylo(tree)

getDescs(tree)

getChildren(tree, node, method = "onlyNodes")

getDescendants(tree, node)

getAncs(tree)

getNodeDepths(tree)

getNodesAtDepth(tree, depth)

getLeaves(tree)

getSubtrCentr(tree)

getDistFromRoot(tree)

getDistFromLeaf(tree)

getIncEdgeLens(tree)

getIncEdgeWeights(tree)

Arguments

tree

A rooted tree in phylo3D format (no special node enumeration required, except that nodes are numbered from 1 to |V| = the total number of nodes). There must be at least 2 nodes, i.e., one edge. The attributes 'node.coord' and 'edge.weight' are strictly required.

node

Numeric/integer value representing a node of the tree.

method

A string specifying if only descending nodes or also descending edges should be returned. Can be one of 'onlyNodes' or 'alsoEdges'.

depth

An integer value representing the depth of interest in the tree. A depth of 0 indicates the root layer, 1 the layer of its children, and so forth.

Value

extendPhylo Tree in extended phylo(3D) format, i.e., phylo(3D) format with further attributes.

getDescs Numeric matrix with 2 rows.

getChildren Depending on the method the function either returns an integer vector containing the direct descendants of a node or an integer matrix with two rows, the first containing the direct descendants and the second the corresponding incoming edges.

getAncs Integer matrix with 2 rows. The first row contains the direct ancestor of each node, the second row the incoming edge of this node, i.e., the edge that leads to its ancestor.

getNodeDepths Numeric matrix with 3 rows.

getNodesAtDepth Integer/numeric vector containing all nodes at the desired depth.

getLeaves Creates a logical vector that indicates if the i-th node is a leaf, TRUE for leaf and FALSE for interior node.

getSubtrCentr Numeric matrix with 2 columns.

getDistFromRoot Integer/numeric vector containing the length of the path from each node to the root.

getDistFromLeaf Integer/numeric vector containing the length of the path from each node to its nearest descendant leaf.

getIncEdgeLens Numeric vector containing the length of the incoming edge of each node, i.e., the length of the edge from its direct ancestor to the node itself.

getIncEdgeWeights Numeric vector containing the weight of the incoming edge of each node, i.e., the weight of the edge from its direct ancestor to the node itself.

Author(s)

Sophie Kersting

Examples

tree <- treeDbalance::example3Dtrees$bean09
ext_tree <- extendPhylo(tree)
getDescs(tree)
getChildren(ext_tree, 3, method="alsoEdges")
getDescendants(ext_tree,3)
getAncs(tree)
getNodeDepths(tree)
getNodesAtDepth(tree,4)
getLeaves(tree)
getSubtrCentr(ext_tree)
getDistFromRoot(ext_tree)
getDistFromLeaf(ext_tree)
getIncEdgeLens(tree)
getIncEdgeWeights(tree)