modifyTerminalBranches: Modify, Drop or Bind Terminal Branches of Various Types...

In paleotree: Paleontological and Phylogenetic Analyses of Evolution

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

Description

These functions modify terminal branches or drop certain terminal branches based on various criteria. dropZLB drops tip-taxa that are attached to the tree via zero-length terminal branches ("ZLBs"). This is sometimes useful for phylogenies of fossil taxa, as various time-scaling methods often produce these 'ZLBs', taxa whose early appearance causes them to be functionally interpreted as ancestors in some time-scaling methods. Removing 'ZLBs' is advised for analyses of diversification/diversity, as these will appear as simultaneous speciation/extinction events. Note this function only drops tips attached to a terminal zero-length branch; if you want to collapse internal zero-length branches, see the ape function di2multi.

Usage

dropZLB(tree)

dropExtinct(tree, tol = 0.01, ignore.root.time = FALSE)

dropExtant(tree, tol = 0.01)

addTermBranchLength(tree, addtime = 0.001)

dropPaleoTip(tree, ...)

bindPaleoTip(
  tree,
  tipLabel,
  nodeAttach = NULL,
  tipAge = NULL,
  edgeLength = NULL,
  positionBelow = 0,
  noNegativeEdgeLength = TRUE
)

Arguments

tree	A phylogeny, as an object of class phylo. dropPaleoTip requires this input object to also have a tree$root.time element. If not provided for bindPaleoTip, then the $root.time will be presumed to be such that the furthest tip from the root is at time = 0.
tol	Tolerance for determining modern age; used for distinguishing extinct from extant taxa. Tips which end within tol of the furthest distance from the root will be treated as 'extant' taxa for the purpose of keeping or dropping.
ignore.root.time	Ignore tree$root.time in calculating which tips are extinct? tree$root.time will still be adjusted, if the operation alters the tree$root.time.
addtime	Extra amount of time to add to all terminal branch lengths.
...	additional arguments passed to dropPaleoTip are passed to drop.tip.
tipLabel	A character string of length = 1 containing the name of the new tip to be added to tree.
nodeAttach	Node or tip ID number (as given in tree$edge) at which to attach the new tip. See documentation of bind.tip for more details.
tipAge	The age of the tip taxon added to the tree, in time before present (i.e. where present is 0), given in the same units as the edges of the tree are already scaled. Cannot be given if edgeLength is given.
edgeLength	The new edge.length of the terminal branch this tip is connected to. Cannot be given if tipAge is given.
positionBelow	The distance along the edge below the node to be attached to (given in nodeAttach to add the new tip. Cannot be negative or greater than the length of the edge below nodeAttach.
noNegativeEdgeLength	Return an error if a negative terminal edge length is calculated for the new tip.

Details

dropExtinct drops all terminal branches which end before the modern (i.e. extinct taxa). DropExtant drops all terminal branches which end at the modern (i.e. extant/still-living taxa). In both cases, the modern is defined based on tree$root.time if available, or the modern is inferred to be the point in time when the tip furthest from the root (the latest tip) terminates.

If the input tree has a $root.time element, as expected for most phylogeny containing fossil taxa objects handled by this library, that $root.time is adjusted if the relative time of the root divergence changes when terminal branches are dropped. This is typically performed via the function fixRootTime. Adjusted $root.time elements are only given if the input tree has a $root.time element.

addTermBranchLength adds an amount equal to the argument addtime to the terminal branch lengths of the tree. If there is a $root.time element, this is increased by an amount equal to addtime. A negative amount can be input to reduce the length of terminal branches. However, if negative branch lengths are produced, the function fails and a warning is produced. The function addTermBranchLength does not call fixRootTime, so the root.time elements in the result tree may be nonsensical, particularly if negative amounts are input.

dropPaleoTip is a wrapper for ape's drop.tip which also modifies the $root.time element if necessary, using fixRootTime. Similarly, bindPaleoTip is a wrapper for phytool's bind.tip which allows tip age as input and modifies the $root.time element if necessary (i.e. if a tip is added to edge leading up to the root).

Note that for bindPaleoTip, tips added below the root are subtracted from any existing $root.edge element, as per behavior of link{bind.tip} and bind.tree. However, bindPaleoTip will append a $root.edge of the appropriate value (i.e., root edge length) if one does not exist (or is not long enough) to avoid an error. After binding is finished, any $root.edge equal to 0 is removed before the resulting tree is output.

Value

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

Author(s)

David W. Bapst. The functions dropTipPaleo and bindTipPaleo are modified imports of drop.tip and bind.tip from packages ape and phytools.

See Also

compareTermBranches, phyloDiv, drop.tip, bind.tip

Examples

set.seed(444)
# Simulate some fossil ranges with simFossilRecord
record <- simFossilRecord(
    p = 0.1, q = 0.1, 
    nruns = 1, 
    nTotalTaxa = c(30,40), 
    nExtant = 0
    )
taxa <- fossilRecord2fossilTaxa(record)
# simulate a fossil record 
    # with imperfect sampling with sampleRanges
rangesCont <- sampleRanges(taxa,r = 0.5)
# Now let's make a tree using taxa2phylo
tree <- taxa2phylo(taxa,obs_time = rangesCont[,2])
# compare the two trees
layout(1:2)
plot(ladderize(tree))
plot(ladderize(dropZLB(tree)))

# reset
layout(1)


# example using dropExtinct and dropExtant
set.seed(444)
record <- simFossilRecord(
    p = 0.1, q = 0.1, 
    nruns = 1, 
    nTotalTaxa = c(30,40), 
    nExtant = c(10,20)
    )
taxa <- fossilRecord2fossilTaxa(record)
tree <- taxa2phylo(taxa)
phyloDiv(tree)
tree1 <- dropExtinct(tree)
phyloDiv(tree1)
tree2 <- dropExtant(tree)
phyloDiv(tree2)


# example using addTermBranchLength
set.seed(444)
treeA <- rtree(10)
treeB <- addTermBranchLength(treeA,1)
compareTermBranches(treeA,treeB)

#########################
# test 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!")
     }


##############
# testing bindPaleoTip

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

## Not run: 

require(phytools)

# bindPaleoTip effectively wraps bind.tip from phytools
# using a conversion like below

tipAge <- 5
node <- 6

# the new tree length (tip to root depth) should be:
# new length = the root time - tipAge - nodeheight(tree,node)

newLength <- tree$root.time-tipAge-nodeheight(tree,node)
tree1 <- bind.tip(tree,
    "tip.label",
    where = node,\
    edge.length = newLength)

layout(1:2)
plot(tree)
axisPhylo()
plot(tree1)
axisPhylo()

# reset
layout(1)


## End(Not run)

# now with bindPaleoTip

tree1 <- bindPaleoTip(tree,"new",nodeAttach = 6,tipAge = 5)

layout(1:2)
plot(tree)
axisPhylo()
plot(tree1)
axisPhylo()

# reset
layout(1)

#then the tip age of "new" should 5
test <- dateNodes(tree1)[which(tree1$tip.label == "new")] == 5
if(!test){
    stop("bindPaleoTip fails!")
    }

# with positionBelow

tree1 <- bindPaleoTip(
    tree,
    "new",
    nodeAttach = 6,
    tipAge = 5,
    positionBelow = 1
    )

layout(1:2)
plot(tree)
axisPhylo()
plot(tree1)
axisPhylo()

# reset
layout(1)

# at the root

tree1 <- bindPaleoTip(
    tree,
    "new", 
    nodeAttach = 5,
    tipAge = 5)

layout(1:2)
plot(tree)
axisPhylo()
plot(tree1)
axisPhylo()

# reset
layout(1)

#then the tip age of "new" should 5
test <- dateNodes(tree1)[which(tree1$tip.label == "new")] == 5
if(!test){
     stop("bindPaleoTip fails!")
     }

# at the root with positionBelow

tree1 <- bindPaleoTip(tree,"new",nodeAttach = 5,tipAge = 5,
	positionBelow = 3)

layout(1:2)
plot(tree)
axisPhylo()
plot(tree1)
axisPhylo()

# reset
layout(1)

#then the tip age of "new" should 5
test <- dateNodes(tree1)[which(tree1$tip.label == "new")] == 5
#and the root age should be 23
test1 <- tree1$root.time == 23
if(!test | !test1){
     stop("bindPaleoTip fails!")
     }

paleotree documentation built on Aug. 22, 2022, 9:09 a.m.