R: Get distances between pairs of tips or nodes.

get_pairwise_distances {castor} | R Documentation

## Get distances between pairs of tips or nodes.

### Description

Calculate phylogenetic ("patristic") distances between tips or nodes in some list A and tips or nodes in a second list B of the same size.

### Usage

    get_pairwise_distances(tree, A, B, as_edge_counts=FALSE, check_input=TRUE)

### Arguments

`tree` | A rooted tree of class "phylo". The root is assumed to be the unique node with no incoming edge.
`A` | An integer vector or character vector of size Npairs, specifying the first of the two members of each pair for which to calculate the distance. If an integer vector, it must list indices of tips (from 1 to Ntips) and/or nodes (from Ntips+1 to Ntips+Nnodes). If a character vector, it must list tip and/or node names.
`B` | An integer vector or character vector of size Npairs, specifying the second of the two members of each pair for which to calculate the distance. If an integer vector, it must list indices of tips (from 1 to Ntips) and/or nodes (from Ntips+1 to Ntips+Nnodes). If a character vector, it must list tip and/or node names.
`check_input` | Logical, whether to perform basic validations of the input data. If you know for certain that your input is valid, you can set this to `FALSE` to reduce computation time.
`as_edge_counts` | Logical, specifying whether distances should be calculated in terms of edge counts, rather than cumulative edge lengths. This is the same as if all edges had length 1.

### Details

The "patristic distance" between two tips and/or nodes is the shortest cumulative branch length that must be traversed along the tree in order to reach one tip/node from the other. Given a list of tips and/or nodes A, and a 2nd list of tips and/or nodes B of the same size, this function will calculate patristic distance between each pair (A[i], B[i]), where i=1,2,..,Npairs.

If `tree$edge.length` is missing, then each edge is assumed to be of length 1; this is the same as setting `as_edge_counts=TRUE`. The tree may include multi-furcations as well as mono-furcations (i.e. nodes with only one child). The input tree must be rooted at some node for technical reasons (see function `root_at_node`), but the choice of the root node does not influence the result. If `A` and/or `B` is a character vector, then `tree$tip.label` must exist. If node names are included in `A` and/or `B`, then `tree$node.label` must also exist.

The asymptotic average time complexity of this function for a balanced binary tree is O(Ntips+Npairs*log2(Ntips)).

### Value

A numeric vector of size Npairs, with the i-th element being the patristic distance between the tips/nodes A[i] and B[i].

### Author(s)

Stilianos Louca

### See Also

`get_all_distances_to_root`

### Examples

    # generate a random tree
    Ntips = 1000
    tree = generate_random_tree(list(birth_rate_intercept=1),Ntips)$tree

    # pick 3 random pairs of tips or nodes
    Npairs = 3
    A = sample.int(n=(Ntips+tree$Nnode), size=Npairs, replace=FALSE)
    B = sample.int(n=(Ntips+tree$Nnode), size=Npairs, replace=FALSE)

    # calculate distances
    distances = get_pairwise_distances(tree, A, B)

    # reroot at some other node
    tree = root_at_node(tree, new_root_node=20, update_indices=FALSE)
    new_distances = get_pairwise_distances(tree, A, B)

    # verify that distances remained unchanged
    print(distances)
    print(new_distances)

[Package castor version 1.3.4 Index]