R: Reorder trees

RenumberTree {TreeTools} | R Documentation

## Reorder trees

### Description

`Reorder()` is a wrapper for `ape:::.reorder_ape`. Calling this C function directly is approximately twice as fast as using `ape::cladewise` or `ape::postorder`

### Usage

    RenumberTree(parent, child)

    RenumberEdges(parent, child, ...)

    Cladewise(tree, nTip, edge)

    ## S3 method for class 'phylo'
    Cladewise(tree, nTip = length(tree$tip.label), edge = tree$edge)

    ## S3 method for class 'list'
    Cladewise(tree, nTip, edge)

    ## S3 method for class 'multiPhylo'
    Cladewise(tree, nTip, edge)

    ## S3 method for class 'matrix'
    Cladewise(tree, nTip = min(tree[, 1]) - 1L, edge)

    ApePostorder(tree, nTip, edge)

    ## S3 method for class 'phylo'
    ApePostorder(tree, nTip = length(tree$tip.label), edge = tree$edge)

    ## S3 method for class 'list'
    ApePostorder(tree, nTip, edge)

    ## S3 method for class 'multiPhylo'
    ApePostorder(tree, nTip, edge)

    Postorder(tree, force = FALSE, renumber = FALSE)

    ## S3 method for class 'phylo'
    Postorder(tree, force = FALSE, renumber = FALSE)

    ## S3 method for class 'list'
    Postorder(tree, force = FALSE, renumber = FALSE)

    ## S3 method for class 'multiPhylo'
    Postorder(tree, force = FALSE, renumber = FALSE)

    ## S3 method for class 'numeric'
    Postorder(tree, force = FALSE, renumber = FALSE)

    PostorderEdges(edge, renumber = FALSE)

    Pruningwise(tree, nTip, edge)

    ## S3 method for class 'phylo'
    Pruningwise(tree, nTip = length(tree$tip.label), edge = tree$edge)

    ## S3 method for class 'list'
    Pruningwise(tree, nTip, edge)

    ## S3 method for class 'multiPhylo'
    Pruningwise(tree, nTip, edge)

    Preorder(tree)

    ## S3 method for class 'phylo'
    Preorder(tree)

    ## S3 method for class 'numeric'
    Preorder(tree)

    ## S3 method for class 'multiPhylo'
    Preorder(tree)

    ## S3 method for class 'list'
    Preorder(tree)

### Arguments

`parent` | Integer vector corresponding to the first column of the edge matrix of a tree of class `phylo`, i.e. `tree$edge[, 1]`
`child` | Integer vector corresponding to the second column of the edge matrix of a tree of class `phylo`, i.e. `tree$edge[, 2]`.
`...` | Deprecated; included for compatibility with previous versions.
`tree` | A tree of class `phylo`.
`nTip` | Integer specifying number of tips (leaves).
`edge` | Two-column matrix listing the parent and child of each edge in a tree, corresponding to `tree$edge`. Optional in `Cladewise()`.
`force` | Logical specifying whether to rearrange trees already in postorder, in order to ensure edges are ordered in the 'TreeTools' fashion.
`renumber` | Logical specifying whether to renumber nodes such that they increase in number away from the root.

### Details

`Cladewise()`, `ApePostorder()` and `Pruningwise()` are convenience functions to the corresponding functions in 'ape'. Single nodes may need to be collapsed using ape::collapse.singles first. 'ape' functions can cause crashes if nodes are numbered unconventionally – sometimes encountered after using tree rearrangement functions, e.g. `phangorn::SPR`.

`Preorder()` is more robust: it supports polytomies, nodes can be numbered in any sequence, and edges can be listed in any order in the input tree. Its output is guaranteed to be identical for any tree of an equivalent topology, allowing unique trees to be detected by comparing sorted edge matrices alone.

A tree in preorder is numbered starting from the root node. Each node is numbered in the sequence in which it is encountered, and each edge is listed in the sequence in which it is visited.

At each node, child edges are sorted from left to right in order of the lowest-numbered leaf in the subtree subtended by each edge; i.e. an edge that leads eventually to tip 1 will be to the left of an edge leading to a subtree containing tip 2.

Numbering begins by following the leftmost edge of the root node, and sorting its descendant subtree into preorder. Then, the next edge at the root node is followed, and its descendants sorted into preorder, until each edge has been visited.

`RenumberTree()` and `RenumberEdges()` are wrappers for the C function `preorder_edges_and_nodes()`; they do not perform the same checks on input as `Preorder()` and are intended for use where performance is at a premium.

`Postorder()` is modified from the 'ape' function to return a specific order: edges are listed from the node that subtends the smallest subtree to the one that subtends the largest (i.e. the root node), with all of a node's descendant edges listed adjacently. If a tree is already in postorder, it will not be rearranged unless `force = TRUE`.

Methods applied to numeric inputs do not check input for sanity, so should be used with caution: malformed input may cause undefined results, including crashing R.

Trees with >8191 leaves require additional memory and are not handled at present. If you need to process such large trees, please contact the maintainer for advice.

### Value

`RenumberTree()` returns an edge matrix for a tree of class `phylo` following the preorder convention for edge and node numbering.

`RenumberEdges()` formats the output of `RenumberTree()` into a list whose two entries correspond to the new parent and child vectors.

`ApePostorder()`, `Cladewise()`, `Postorder()`, `Preorder()` and `Pruningwise()` each return a tree of class `phylo` with nodes following the specified numbering scheme.

`Postorder.numeric` accepts a numeric matrix corresponding to the `edge` entry of a tree of class `phylo`, and returns a two-column array corresponding to `tree`, with edges listed in postorder

### Functions

- `Cladewise`: Reorder tree cladewise.

- `ApePostorder`: Reorder tree in Postorder using ape's `postorder` function, which is robust to unconventional node numbering.

- `Postorder`: Reorder tree in Postorder. Edge lengths are not retained.

- `Pruningwise`: Reorder tree Pruningwise.

- `Preorder`: Reorder tree in Preorder (special case of cladewise).

### Author(s)

`Preorder()` and `Postorder()`: Martin R. Smith.

`Cladewise()`, `ApePostorder()` and `Pruningwise()`: modified by Martin R. Smith from `.reorder_ape()` in ape (Emmanuel Paradis).

### See Also

Rotate each node into a consistent orientation with `SortTree()`.

Other tree manipulation: `AddTip()`, `CollapseNode()`, `ConsensusWithout()`, `DropTip()`, `EnforceOutgroup()`, `LeafLabelInterchange()`, `MakeTreeBinary()`, `RenumberTips()`, `Renumber()`, `RootTree()`, `SingleTaxonTree()`, `SortTree()`, `Subtree()`

Other C wrappers: `Neworder`

Other C wrappers: `Neworder`

[Package TreeTools version 1.3.1 Index]