clade_densities: Estimate the density of tips & nodes in a timetree.

In castor: Efficient Phylogenetics on Large Trees

Estimate the density of tips & nodes in a timetree.

Description

Given a rooted timetree (i.e., a tree whose edge lengths represent time intervals), estimate the density of tips and nodes as a function of age (tips or nodes per time unit), on a discrete grid. Optionally the densities can be normalized by the local number of lineages. If the tree is full (includes all extinct & extant clades), then the normalized tip (node) density is an estimate for the per-capita extinction (speciation) rate.

Usage

clade_densities(tree, 
                Nbins       = NULL,
                min_age     = NULL,
                max_age     = NULL,
                normalize   = TRUE,
                ultrametric	= FALSE)		

Arguments

tree	A rooted tree of class "phylo", where edge lengths represent time intervals (or similar).
Nbins	Integer, number of equidistant age bins at which to calculate densities.
min_age	Numeric, minimum age to consider. If NULL, it will be set to the minimum possible.
max_age	Numeric, maximum age to consider. If NULL, it will be set to the maximum possible.
normalize	Logical, whether to normalize densities by the local number of lineages (in addition to dividing by the age interval). Hence, tip (or node) densities will represent number of tips (or nodes) per time unit per lineage.
ultrametric	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.

Details

This function discretizes the full considered age range (from min_age to max_age) into Nbins discrete disjoint bins, then computes the number of tips and nodes in each bin, and finally divides those numbers by the bin width. If normalize==True, the densities are further divided by the number of lineages in the middle of each age bin. For typical timetrees it is generally recommended to omit the most recent tips (i.e., extant at age 0), by setting min_age to a small non-zero value; otherwise, the first age bin will typically be associated with a high tip density, i.e., tip densities will be zero-inflated.

Value

A list with the following elements:

Nbins	Integer, indicating the number of discrete age bins.
ages	Numeric vector of size Nbins, listing the centres of the age bins.
tip_densities	Numeric vector of size Nbins, listing the tip densities in the corresponding age bins.
node_densities	Numeric vector of size Nbins, listing the node densities in the corresponding age bins.

Author(s)

Stilianos Louca

See Also

count_lineages_through_time

Examples

# generate a random full tree, including all extinct & extant tips
tree = generate_random_tree(list(birth_rate_intercept=1), 
                            max_tips=1000, coalescent=FALSE)$tree

# compute node densities, as an estimate for the speciation rate
densities = clade_densities(tree, Nbins=10, normalize=TRUE)

# plot node densities
plot(densities$ages, densities$node_densities, type="l", xlab="age", ylab="node density")

castor documentation built on Aug. 18, 2023, 1:07 a.m.