modifyTerminalBranches: 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
)

Value

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

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.

Author

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

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).