distTips {adephylo}

Compute some phylogenetic distance between tips

Description

The function distTips computes a given distance between a set of tips of a phylogeny. A vector of tips is supplied: distances between all possible pairs of these tips are computed. The distances are computed from the shortest path between the tips. Several distances can be used, defaulting to the sum of branch lengths (see argument method).

Usage

distTips(
  x,
  tips = "all",
  method = c("patristic", "nNodes", "Abouheif", "sumDD"),
  useC = TRUE
)

Arguments

x

a tree of class phylo, phylo4 or phylo4d.

tips

A vector of integers identifying tips by their numbers, or a vector of characters identifying tips by their names. Distances will be computed between all possible pairs of tips.

method

a character string (full or abbreviated without ambiguity) specifying the method used to compute distances ; possible values are:
- patristic: patristic distance, i.e. sum of branch lengths
- nNodes: number of nodes on the path between the nodes
- Abouheif: Abouheif's distance (see details)
- sumDD: sum of direct descendants of all nodes on the path (see details)

useC

a logical indicating whether computations should be performed using compiled C code (TRUE, default), or using a pure R version (FALSE). C version is several orders of magnitude faster, and R version is kept for backward compatibility.

Details

An option (enabled by default) allows computations to be run using compiled C code, which is much faster than pure R code. In this case, a matrix of all pairwise distances is returned (i.e., tips argument is ignored).

Abouheif distance refers to the phylogenetic distance underlying the test of Abouheif (see references). Let P be the set of all the nodes in the path going from node1 to node2. Let DDP be the number of direct descendants from each node in P. Then, the so-called 'Abouheif' distance is the product of all terms in DDP.

sumDD refers to a phylogenetic distance quite similar to that of Abouheif. We consider the same sets P and DDP. But instead of computing the product of all terms in DDP, this distance computes the sum of all terms in DDP.

Value

An object of class dist, containing phylogenetic distances.

Author(s)

Thibaut Jombart [e-mail]

References

Pavoine, S.; Ollier, S.; Pontier, D. & Chessel, D. (2008) Testing for phylogenetic signal in life history variable: Abouheif's test revisited. Theoretical Population Biology: 73, 79-91.

See Also

distTips which computes several phylogenetic distances between tips.

Examples

if(require(ape) & require(phylobase)){
## make a tree
x <- as(rtree(10),"phylo4")
plot(x, show.node=TRUE)
axisPhylo()
## compute different distances
distTips(x, 1:3)
distTips(x, 1:3, "nNodes")
distTips(x, 1:3, "Abouheif")
distTips(x, 1:3, "sumDD")

## compare C and pure R code outputs
x <- rtree(10)
all.equal(as.matrix(distTips(x)), as.matrix(distTips(x, useC=FALSE)))
all.equal(as.matrix(distTips(x, meth="nNode")),
   as.matrix(distTips(x, meth="nNode", useC=FALSE)))
all.equal(as.matrix(distTips(x, meth="Abou")),
   as.matrix(distTips(x, meth="Abou", useC=FALSE)))
all.equal(as.matrix(distTips(x, meth="sumDD")),
   as.matrix(distTips(x, meth="sumDD", useC=FALSE)))

## compare speed
x <- rtree(50)
tim1 <- system.time(distTips(x, useC=FALSE)) # old pure R version
tim2 <- system.time(distTips(x)) # new version using C
tim1[c(1,3)]/tim2[c(1,3)] # C is about a thousand time faster in this case
}