correlate_phylo_geodistances: Correlations between phylogenetic & geographic distances.

In castor: Efficient Phylogenetics on Large Trees

Correlations between phylogenetic & geographic distances.

Description

Given a rooted phylogenetic tree and geographic coordinates (latitudes & longitudes) of each tip, examine the correlation between pairwise phylogenetic and geographic distances of tips. The statistical significance is computed by randomly permuting the tip coordinates, which is essentially a phylogenetic version of the Mantel test and accounts for shared evolutionary history between tips.

Usage

correlate_phylo_geodistances(tree,
                             tip_latitudes,
                             tip_longitudes,
                             correlation_method,
                             max_phylodistance  = Inf,
                             Npermutations      = 1000,
                             alternative        = "right",
                             radius             = 1)

Arguments

tree	A rooted tree of class "phylo".
tip_latitudes	Numeric vector of size Ntips, specifying the latitudes (decimal degrees) of the tree's tips. By convention, positive latitudes correspond to the northern hemisphere. Note that tip_latitudes[i] must correspond to the i-th tip in the tree, i.e. as listed in tree$tip.label.
tip_longitudes	Numeric vector of size Ntips, specifying the longitudes (decimal degrees) of the tree's tips. By convention, positive longitudes correspond to the eastern hemisphere.
correlation_method	Character, one of "pearson", "spearman" or "kendall".
max_phylodistance	Numeric, maximum phylodistance between tips to consider, in the same units as the tree's edge lengths. If Inf, all tip pairs will be considered.
Npermutations	Integer, number of random permutations to consider for estimating the statistical significance (P value). If 0, the significance will not be computed. A larger number improves accuracy but at the cost of increased computing time.
alternative	Character, one of "two_sided", "right" or "left", specifying which part of the null model's distribution to use as P-value.
radius	Optional numeric, radius to assume for the sphere. If 1, then all geodistances are measured in multiples of the sphere radius. This does not affect the correlation or P-value, but it affects the returned geodistances. Note that Earth's average radius is about 6371 km.

Details

To compute the statistical significance (P value) of the observed correlation C, this function repeatedly randomly permutes the tip coordinates, each time recomputing the corresponding "random" correlation, and then examines the distribution of the random correlations. If alternative="right", the P value is set to the fraction of random correlations equal to or greater than C.

Value

A named list with the following elements:

correlation	Numeric between -1 and 1, the correlation between phylodistances and geodistances.
Npairs	Integer, the number of tip pairs considered.
Pvalue	Numeric between 0 and 1, estimated statistical significance of the correlation. Only returned if Npermutations>0.
mean_random_correlation	Numeric between -1 and 1, the mean correlation obtained across all random permutations. Only returned if Npermutations>0.
phylodistances	Numeric vector of length Npairs, listing the pairwise phylodistances between tips, used to compute the correlation.
geodistances	Numeric vector of length Npairs, listing the pairwise geodistances between tips, used to compute the correlation.

Author(s)

Stilianos Louca

See Also

geographic_acf

Examples

# Generate a random tree
Ntips = 50
tree = generate_random_tree(list(birth_rate_intercept=1),max_tips=Ntips)$tree

# simulate spherical Brownian motion (a dispersal model) on the tree
simul = simulate_sbm(tree, radius=6371, diffusivity=50)

# Analyze correlations between geodistances & phylodistances
coranal = correlate_phylo_geodistances(tree               = tree,
                                       tip_latitudes      = simul$tip_latitudes,
                                       tip_longitudes     = simul$tip_longitudes,
                                       correlation_method = "spearman",
                                       Npermutations      = 100,
                                       max_phylodistance  = 100,
                                       radius             = 6371)
print(coranal$correlation)
print(coranal$Pvalue)
plot(coranal$phylodistances, coranal$geodistances,
     xlab="phylodistance", ylab="geodistance", type="p")

castor documentation built on June 29, 2024, 9:08 a.m.