Given a rooted timetree (i.e., a tree whose edge lengths represent time intervals), calculate the number of lineages represented in the tree at various time points, otherwise known as "lineages through time"" (LTT) curve. The root is interpreted as time 0, and the distance of any node or tip from the root is interpreted as time elapsed since the root. Optionally, the slopes and relative slopes of the LTT curve are also returned.
count_lineages_through_time( tree,
Ntimes = NULL,
min_time = NULL,
max_time = NULL,
times = NULL,
include_slopes= FALSE,
ultrametric = FALSE,
degree = 1,
regular_grid = TRUE)A list with the following elements:
Integer, indicating the number of returned time points. Equal to the provided Ntimes if applicable.
Numeric vector of size Ntimes, listing the time points at which the LTT was calculated. If times was provided as an argument to the function, then this will be the same as provided, otherwise times will be listed in ascending order.
Numeric vector of size Ntimes, listing the ages (time before the youngest tip) corresponding to the returned times[].
Integer vector of size Ntimes, listing the number of lineages represented in the tree at each time point that have at least degree descending tips, i.e. the LTT curve.
Numeric vector of size Ntimes, listing the slopes (finite-difference approximation of 1st derivative) of the LTT curve.
Numeric vector of size Ntimes, listing the relative slopes of the LTT curve, i.e. slopes divided by a sliding-window average of lineages.
A rooted tree of class "phylo", where edge lengths represent time intervals (or similar).
Integer, number of equidistant time points at which to count lineages. Can also be NULL, in which case times must be provided.
Minimum time (distance from root) to consider. If NULL, this will be set to the minimum possible (i.e. 0). Only relevant if times==NULL.
Maximum time (distance from root) to consider. If NULL, this will be set to the maximum possible. Only relevant if times==NULL.
Integer vector, listing time points (in ascending order) at which to count lineages. Can also be NULL, in which case Ntimes must be provided.
Logical, specifying whether the slope and the relative slope of the returned clades-per-time-point curve should also be returned.
Logical, specifying whether the input tree is guaranteed to be ultrametric, even in the presence of some numerical inaccuracies causing some tips not have exactly the same distance from the root. If you know the tree is ultrametric, then this option helps the function choose a better time grid for the LTT.
Integer, specifying the "degree" of the LTT curve: LTT(t) will be the number of lineages in the tree at time t that have at least n descending tips in the tree. Typically order=1, which corresponds to the classical LTT curve.
Logical, specifying whether the automatically generated time grid should be regular (equal distances between grid points). This option only matters if times==NULL. If regular_grid==FALSE and times==NULL, the time grid will be irregular, with grid point density being roughly proportional to the square root of the number of lineages at any particular time (i.e., the grid becomes finer towards the tips).
Stilianos Louca
Given a sequence of time points between a tree's root and tips, this function essentially counts how many edges "cross" each time point (if degree==1). The slopes and relative slopes are calculated from this curve using finite differences.
Note that the classical LTT curve (degree=1) is non-decreasing over time, whereas higher-degree LTT's may be decreasing as well as increasing over time.
If tree$edge.length is missing, then every edge in the tree is assumed to be of length 1. The tree may include multifurcations as well as monofurcations (i.e. nodes with only one child). The tree need not be ultrametric, although in general this function only makes sense for dated trees (e.g., where edge lengths are time intervals or similar).
Either Ntimes or times must be non-NULL, but not both. If times!=NULL, then min_time and max_time must be NULL.
# generate a random tree
tree = generate_random_tree(list(birth_rate_intercept=1), max_tips=1000)$tree
# calculate classical LTT curve
results = count_lineages_through_time(tree, Ntimes=100)
# plot classical LTT curve
plot(results$times, results$lineages, type="l", xlab="time", ylab="# clades")
Run the code above in your browser using DataLab