fixRootTime: Modify, Drop or Bind Terminal Branches of Various Types (Mainly for Paleontological Phylogenies)

Description

Modifying a dated tree with $root.time elements often changes the actual timing of the root relative to the tips, such as when dropping tips, extending branches, or shift node ages backwards. When such modifications occur, the function fixRootTime can be used to find the correct root age. This function is mainly used as a utility function called by other tree-modifying functions discussed in the manual page for modifyTerminalBranches. This is typically performed via the function fixRootTime.

Usage

fixRootTime(
  treeOrig,
  treeNew,
  testConsistentDepth = TRUE,
  fixingMethod = "matchCladeTransferNodeAge"
)

Value

Gives back a modified phylogeny as a phylo object, with a modified $root.time element.

Arguments

treeOrig

A phylo object of a time-scaled phylogeny with a $root.time element.

treeNew

A phylo object containing a modified form of treeOrig (with no extra tip taxa added, but possibly with some tip taxa removed).

testConsistentDepth

A logical, either TRUE or FALSE. If TRUE (the default) the tree's root-to-furthest-tip depth is tested to make sure this depth is not greater than the new $root.time appended to the output tree.

fixingMethod

must be an character value, with a length of 1.

The default option fixingMethod = "matchCladeTransferNodeAge", will determine the $root.time of the new tree by comparing the clades of taxa between the two input trees. The new root age assigned is the age of (1) the treeOrig clade that contains all taxa present in treeNew and, if the set of (1) contains multiple clades, (2) the clade in the first set that contains the fewest taxa not in treeNew.

If fixingMethod = "rescaleUsingTipToRootDist", the root.time assigned to treeNew is the $root.time of treeOrig, adjusted based on the change in total tree depth between treeOrig and treeNew, as measured between the root and the first matching taxon in both trees. The "rescaleUsingTipToRootDist" option was the default for fixRootTime prior to paleotree v2.3, and is the option used by function minBranchLength when applied to a tree with pre-existing root age element.

Author

David W. Bapst

Examples

Run this code


# \donttest{

#testing dropPaleoTip... and fixRootTime by extension

#simple example
tree <- read.tree(text = "(A:3,(B:2,(C:5,D:3):2):3);")
tree$root.time <- 10
plot(tree,no.margin = FALSE)
axisPhylo()

# now a series of tests, dropping various tips
(test <- dropPaleoTip(tree,"A")$root.time) #  = 7
(test[2] <- dropPaleoTip(tree,"B")$root.time) #  = 10
(test[3] <- dropPaleoTip(tree,"C")$root.time) #  = 10
(test[4] <- dropPaleoTip(tree,"D")$root.time) #  = 10
(test[5] <- dropPaleoTip(tree,c("A","B"))$root.time) #  = 5
(test[6] <- dropPaleoTip(tree,c("B","C"))$root.time) #  = 10
(test[7] <- dropPaleoTip(tree,c("A","C"))$root.time) #  = 7
(test[8] <- dropPaleoTip(tree,c("A","D"))$root.time) #  = 7

# is it all good? if not, fail so paleotree fails...
if(!identical(test,c(7,10,10,10,5,10,7,7))){stop("fixRootTime fails!")}

# }