nodeDates2branchLengths {paleotree}

Obtaining Edge Lengths for Undated Phylogenies Using Known Branching Node and Tip Ages

Description

This function takes some undated phylogenetic topology, a set of ages in absolute time, for the internal nodes and (by default) the terminal tips of that phylogeny, and returns a dated phylogeny consistent with those input ages.

Usage

nodeDates2branchLengths(nodeDates, tree, allTipsModern = FALSE)

Arguments

nodeDates

Under default allTipsModern = FALSE conditions, nodeDates should be a vector of length Ntip(tree) + Nnode(tree) which contains the dates for all terminal tip nodes and internal nodes for the tree, in that order, as numbered in the tree$edge matrix. Such a vector is produced as output by dateNodes. If allTipsModern = TRUE, then the vector should only be as long as the number of nodes, and contain the dates only for those same internal nodes in tree. These dates should always on a descending scale (i.e. time before present), with respect to an absolute time-scale. It is possible for the time 0 date to represent a date far in the future from the latest tip.

tree

An undated phylogeny object, of class phylo, lacking edge lengths. If the tree appears to be dated (i.e. has edge lengths), the function will issue a warning.

allTipsModern

A logical, default is FALSE. If FALSE, then the function expects nodeDates to contain ages for all 'nodes' - both internal branching nodes and terminal tips. If TRUE, then the function will expect nodeDates to contain ages only for internal branching nodes, and all tips will be assumed to be at time 0. (Thus, if your tree is ultrametric but tips aren't all at the modern, do not use allTipsModern = TRUE).

Details

The function compute.brtime in package ape does a very similar functionality, but is limited in its application for only ultrametric trees, as it does not allow for tips to have incongruent ages. It also only accepts node ages as on the relative scale where the latest tips are at zero, as assumed in general elsewhere in package ape.

Value

A dated tree as a list of class phylo, with a $root.time element for referencing the tree against absolute time.

Author(s)

David W. Bapst

See Also

This function will likely often be used in conjunction with dateNodes, such as for summarizing node and tip age estimates from a sample of trees, to produce a single dated tree to act as a point estimate. Beware however that point estimates of tree samples may have little resemblance to any individual tree in that sample.

This function should perform identically for ultrametric trees as package ape's function compute.brtime.

Examples

set.seed(444)

# we'll do a number of tests, let's check at the end that all are TRUE
tests <- logical()

# with a non-ultrametric tree
chrono <- rtree(10)
# make an undated tree
notChrono <- chrono
notChrono$edge.length <- NULL

# now lets try with dateNodes in paleotree
nodeTimes <- dateNodes(chrono)
# need to use allTipsModern = FALSE because tip ages are included
chronoRedux <-  nodeDates2branchLengths(tree = notChrono,
    nodeDates = nodeTimes, allTipsModern = FALSE)
# test that its the same
(tests <- c(tests,all.equal.numeric(chrono$edge.length,chronoRedux$edge.length)))

######################################
# modern ultrametric tree
chrono <- rcoal(10)
# make an undated tree
notChrono <- chrono
notChrono$edge.length <- NULL

# with ultrametric trees, you could just use ape's compute.brtime 

# getting branching times with ape
branchingTimes <- branching.times(chrono)	
# setting those branching times with ape
chronoRedux <-  compute.brtime(notChrono, branchingTimes)
# test that its the same
(tests <- c(tests,all.equal.numeric(chrono$edge.length,chronoRedux$edge.length)))

# lets do the same thing but with nodeDates2branchLengths

# can use branching.times from ape 
	# (but only for ultrametric trees!)
chronoRedux <-  nodeDates2branchLengths(tree = notChrono,
    nodeDates = branchingTimes, allTipsModern = TRUE)
# test that its the same
(tests <- c(tests,all.equal.numeric(chrono$edge.length,chronoRedux$edge.length)))

# now lets try with dateNodes in paleotree
nodeTimes <- dateNodes(chrono)
# need to use allTipsModern = FALSE because tip ages are included
chronoRedux <-  nodeDates2branchLengths(tree = notChrono,
    nodeDates = nodeTimes, allTipsModern = FALSE)
# test that its the same
(tests <- c(tests,all.equal.numeric(chrono$edge.length,chronoRedux$edge.length)))

# get just the node times (remove tip dates)
nodeOnlyTimes <- nodeTimes[-(1:Ntip(chrono))]
# let's use the allTipsModern = TRUE setting
chronoRedux <-  nodeDates2branchLengths(tree = notChrono,
    nodeDates = nodeOnlyTimes, allTipsModern = TRUE)
# test that its the same
(tests <- c(tests,all.equal.numeric(chrono$edge.length,chronoRedux$edge.length)))

# did all tests come out as TRUE?
if(!all(tests)){stop("nodeDates2branchLengths isn't functioning correctly")}