dateNodes {paleotree}

Absolute Dates for Nodes of a Time-Scaled Phylogeny

Description

This function returns the ages of nodes (both internal and terminal tips) for a given phylogeny of class phylo. Its use is specialized for application to dated trees from paleotree, see Details below.

Usage

dateNodes(
  tree,
  rootAge = tree$root.time,
  labelDates = FALSE,
  tolerance = 0.001
)

Arguments

tree

A phylogeny object of class phylo. Must have edge lengths!

rootAge

The root age of the tree, assumed by default to be equal to the element at tree$root.time, which is a standard element for trees dated by the paleotree package. If not given by the user and if the $root.time element does not exist, then the maximum depth of the tree will be taken as the root age, which implicitly assumes the latest most terminal tip is an extant taxon at the modern day (time = 0). If rootAge is so defined that some nodes may occur later than time = 0, this function may return negative dates.

labelDates

If FALSE (the default), the dates returned are labeled with the tip/node numbers as given in tree$edge. If TRUE, they are labeled with the tip labels of every descendant tip, which for terminal tips means a single taxon label, and for internal tips a label that might be very long, composed of multiple tip labels pasted together. Thus, by default, this argument is FALSE.

tolerance

The tolerance within which a node date has to be removed from zero-time (i.e. the modern) to issue a warning that there are 'negative' node dates.

Details

This function is specialized for dated phylogenies, either estimated from empirical data or simulated with functions from paleotree, and thus have a $root.time element. This function will still work without such, but users should see the details for the rootAge argument.

Value

Returns 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. These dates are always on a descending scale (i.e. time before present); see help for argument rootAge for how the present time is determined. If rootAge is so defined that some nodes may occur later than time = 0 units before present, this function may (confusingly) return negative dates and a warning message will be issued.

Author(s)

David W. Bapst, based on a function originally written by Graeme Lloyd.

See Also

compareTimescaling, nodeDates2branchLengths

Examples

#let's simulate some example data
set.seed(444)
record <- simFossilRecord(p = 0.1, q = 0.1, nruns = 1,
	nTotalTaxa = c(30,40), nExtant = 0)
taxa <- fossilRecord2fossilTaxa(record)
#get the true time-sclaed tree
tree1 <- taxa2phylo(taxa)

#now let's try dateNodes
dateNodes(tree1)

#let's ignore $root.time
dateNodes(tree1,rootAge = NULL)

#with the lengthy tip-label based labels
   #some of these will be hideously long
dateNodes(tree1,labelDates = TRUE)