| modifyTerminalBranches {paleotree} | R Documentation |
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 |
tol |
Tolerance for determining modern age; used for distinguishing
extinct from extant taxa. Tips which end within |
ignore.root.time |
Ignore |
addtime |
Extra amount of time to add to all terminal branch lengths. |
... |
additional arguments passed to |
tipLabel |
A character string of |
nodeAttach |
Node or tip ID number (as given in |
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 |
The new |
positionBelow |
The distance along the edge below the node to be attached to
(given in |
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[ape]{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!")
}