R: Phylogenetic autocorrelation function of a numeric trait.

get_trait_acf {castor} | R Documentation

## Phylogenetic autocorrelation function of a numeric trait.

### Description

Given a rooted phylogenetic tree and a numeric (typically continuous) trait with known value (state) on each tip, calculate the phylogenetic autocorrelation function (ACF) of the trait. The ACF is a function of phylogenetic distance x, where ACF(x) is the Pearson autocorrelation of the trait between two tips, provided that the tips have phylogenetic ("patristic") distance x. The function `get_trait_acf` also calculates the mean absolute difference and the mean relative difference of the trait between any two random tips at phylogenetic distance x (see details below).

### Usage

    get_trait_acf(tree, tip_states, Npairs=10000, Nbins=10)

### Arguments

`tree` | A rooted tree of class "phylo". The root is assumed to be the unique node with no incoming edge.
`tip_states` | A numeric vector of size Ntips, specifying the value of the trait at each tip in the tree. Note that tip_states[i] (where i is an integer index) must correspond to the i-th tip in the tree.
`Npairs` | Total number of random tip pairs to draw. A greater number of tip pairs will improve the accuracy of the estimated ACF within each distance bin. Tip pairs are drawn randomly with replacement. If `Npairs<=0`, then every tip pair is included exactly once.
`Nbins` | Number of distance bins to consider within the range of phylogenetic distances encountered between tip pairs in the tree. A greater number of bins will increase the resolution of the ACF as a function of phylogenetic distance, but will decrease the number of tip pairs falling within each bin (which reduces the accuracy of the estimated ACF).

### Details

The phylogenetic autocorrelation function (ACF) of a trait can give insight into the evolutionary processes shaping its distribution across clades. An ACF that decays slowly with increasing phylogenetic distance indicates a strong phylogenetic conservatism of the trait, whereas a rapidly decaying ACF indicates weak phylogenetic conservatism. Similarly, if the mean absolute difference in trait value between two random tips increases with phylogenetic distance, this indicates a phylogenetic autocorrelation of the trait (Zaneveld et al. 2014). Here, phylogenetic distance between tips refers to their patristic distance, i.e. the minimum cumulative edge length required to connect the two tips.

Since the phylogenetic distances between all possible tip pairs do not cover a continuoum (as there is only a finite number of tips), this function randomly draws tip pairs from the tree, maps them onto a finite set of equally-sized distance bins and then estimates the ACF for the centroid of each distance bin based on tip pairs in that bin. In practice, as a next step one would usually plot the estimated ACF (returned vector `autocorrelations`) over the centroids of the distance bins (returned vector `distances`).

The tree may include multi-furcations (i.e. nodes with more than 2 children) as well as mono-furcations (i.e. nodes with only one child). If `tree$edge.length` is missing, then every edge is assumed to have length 1. The input tree must be rooted at some node for technical reasons (see function `root_at_node`), but the choice of the root node does not influence the result.

### Value

A list with the following elements:

`distances` | Numeric vector of size Nbins, storing the centroid phylogenetic distance of each distance bin in increasing order. The first and last distance bin approximately span the full range of phylogenetic distances encountered between any two random tips in the tree.
`autocorrelations` | Numeric vector of size Nbins, storing the estimated Pearson autocorrelation of the trait for each distance bin.
`mean_abs_differences` | Numeric vector of size Nbins, storing the mean absolute difference of the trait between tip pairs in each distance bin.
`mean_rel_differences` | Numeric vector of size Nbins, storing the mean relative difference of the trait between tip pairs in each distance bin. The relative difference between two values X and Y is 0 if X==Y, and equal to \frac{|X-Y|}{0.5\cdot (|X|+|Y|)} otherwise.
`Npairs_per_distance` | Integer vector of size Nbins, storing the number of random tip pairs associated with each distance bin.

### Author(s)

Stilianos Louca

### References

J. R. Zaneveld and R. L. V. Thurber (2014). Hidden state prediction: A modification of classic ancestral state reconstruction algorithms helps unravel complex symbioses. Frontiers in Microbiology. 5:431.

### See Also

`get_trait_depth`, `geographic_acf`

### Examples

    # generate a random tree
    tree = generate_random_tree(list(birth_rate_intercept=1),max_tips=1000)$tree

    # simulate continuous trait evolution on the tree
    tip_states = simulate_bm_model(tree, diffusivity=1)$tip_states

    # calculate autocorrelation function
    ACF = get_trait_acf(tree, tip_states, Npairs=1e7, Nbins=10)

    # plot ACF (autocorrelation vs phylogenetic distance)
    plot(ACF$distances, ACF$autocorrelations, type="l", xlab="distance", ylab="ACF")

[Package castor version 1.6.7 Index]