paleotree (version 3.4.7)

timeSliceTree: Time-Slicing a Phylogeny

Description

Removes the portion of a tree after a set point in time, as if the tree after that moment had been sliced away.

Usage

timeSliceTree(
  ttree,
  sliceTime,
  drop.extinct = FALSE,
  tipLabels = "earliestDesc",
  plot = TRUE
)

Value

Returns the modified phylogeny as an object of class phylo. See argument tipLabels for how the labeling of the tips for cut branches is controlled.

Arguments

ttree

A time-scaled phylogeny of class phylo.

sliceTime

Time at which to 'slice' the tree. See details.

drop.extinct

If TRUE, drops tips that go extinct before the input timeSlice using function dropExtinct. Note that dropExtinct will also automatically adjust the $root.time if the removal of extinct branches causes the room to shift to a younger age.

tipLabels

What sort of tip labels should be placed on cropped branches which had multiple descendants? The default option, "earliestDesc" labels a clipped branch with the earliest appearing tip descendant of that branch. Alternatively, if tipLabels = "allDesc", these tips can instead be labeled with a compound label consisting of all descendants that were on the cropped branch, separated by semi-colons.

plot

If TRUE, plots input and output trees for comparison.

Author

David W. Bapst, with modification of code by Klaus Schliep to avoid use of function dist.nodes, which has difficulty with large trees, and greatly benefiting the run time of this function.

Details

The function assumes that the input ttree will generally have an element called $root.time, which is the time before present that the root divergence occurred. If $root.time is not present as an element of ttree, then it is assumed the tip furthest from the root is at time zero (present-day) and a new $root.time is calculated (a warning will be issued in this case).

The sliceTime is always calculated as on the same scale as ttree$root.time. In other words, if root.time = 100, then timeSlice = 80 will slice the tree 20 time units after the root.

If drop.extinct = TRUE, then extinct tips are dropped and (if present) the $root.time of ttree is adjusted. This is done using the paleotree function dropExtinct.

See Also

phyloDiv, dropExtinct, dropExtant

Also see the function treeSlice in the library phytools, which will slice a tree at some point in and return all the subtrees which remain after the slicing time. (Effectively the reversed opposite of timeSliceTree.)

Examples

# a neat example of using phyloDiv with timeSliceTree 
    # to simulate doing extant-only phylogeny studies 
    # of diversification...in the past!
set.seed(444)
record <- simFossilRecord(
    p = 0.1, q = 0.1, nruns = 1,
    nTotalTaxa = c(30,40), 
    nExtant = 0)
taxa <- fossilRecord2fossilTaxa(record)
taxicDivCont(taxa)

# that's the whole diversity curve
   # now let's do it for a particular time-slide
tree <- taxa2phylo(taxa)
# use timeSliceTree to make tree of relationships
    # up until time = 950 
tree950 <- timeSliceTree(
    tree,
    sliceTime = 950,
    plot = TRUE,
    drop.extinct = FALSE
    )

# compare tip labels when we use tipLabels = "allDesc"
tree950_AD <- timeSliceTree(
    tree,
    sliceTime = 950,
    plot = TRUE,
    tipLabel = "allDesc",
    drop.extinct = FALSE
    )
    
# look for the differences!     
cbind(tree950$tip.label, tree950_AD$tip.label)

# with timeSliceTree we could
    # look at the lineage accumulation curve 
    # we would recover from the species extant
    # at that point in time

# use drop.extinct = T to only get the
    # tree of lineages extant at time = 950
tree950 <- timeSliceTree(
    tree,
    sliceTime = 950,
    plot = FALSE,
    drop.extinct = TRUE
    )
# now its an ultrametric tree with many fewer tips...
    # lets plot the lineage accumulation plot on a log scale
phyloDiv(tree950,
    plotLogRich = TRUE
    )