Skip to contents

Calculate average evolutionary distinctiveness (ED) for a set of species

avg_evol_dist.Rd

Computes the average evolutionary distinctiveness (ED) of each species based on a rooted, time-calibrated phylogenetic tree. ED can be calculated either across the full tree or across multiple evolutionary time slices.

Usage

avg_evol_dist(
  phy,
  data_frame,
  species_col = "species",
  taxon = NULL,
  time = TRUE,
  time_slices = c(25, 50, 75, 100, 115),
  num_cores = 1
)

Arguments

phy

A rooted, time-calibrated phylogenetic tree (phylo object). Branch lengths must reflect time (e.g., millions of years).

data_frame

A data frame containing the species of interest. Must include a column with species names.

species_col

A character string specifying the name of the species column in data_frame. Default is "species".

taxon

Optional character vector specifying which taxa (species) to compute ED for. If NULL (default), all unique species in data_frame are used.

time

Logical; if FALSE, ED is calculated across the full tree. If TRUE, ED is calculated across multiple evolutionary time slices. Default is TRUE

time_slices

Numeric vector of time depths (in millions of years ago, MYA) at which to slice the tree. Default is c(25, 50, 75, 100, 115). Values must be less than the root age of phy. Ultrametric trees are recommended.

num_cores

Number of CPU cores to use for parallel processing. Default is 1. We recommend increasing this for faster computation.

Value

A data.frame with two columns:

  1. The species column (name matches species_col).

  2. ED — the average evolutionary distinctiveness.

Details

Evolutionary distinctiveness (ED) is computed using the "fair.proportion"method from picante. When time = TRUE, the phylogeny is sliced at each time depth using phytools::treeSlice() and ED is computed for each slice. The mean ED across slices is returned for each species.

Calculating ED at several evolutionary depths captures how distinct species are over deep vs. shallow time scales.

Parallel processing is supported via foreach and doParallel.

Examples

# Generate a phylogeny
set.seed(123)
random_phy <- ape::rtree(n = 7)
random_phy$tip.label <- c("Acer_campestre", "Acer_monspessulanum",
                          "Acer_negundo", "Acer_opalus",
                          "Acer_platanoides", "Acer_pseudoplatanus",
                          "Acer_saccharinum")

# Create a dataframe of species
maple_data <- data.frame(species = random_phy$tip.label)

# Compute ED using time slices
ed_results <- avg_evol_dist(phy = random_phy,
                            data_frame = maple_data,
                            species_col = "species",
                            num_cores = 1,
                            time_slices = c(0.5, 1, 1.5))
#> Warning: The phylogeny is not ultrametric. Some species may not be present at chosen time slices and will return NA.

print(ed_results)
#>               species         ED
#> 1      Acer_campestre 0.19265958
#> 2 Acer_monspessulanum 0.04205953
#> 3        Acer_negundo 0.26781128
#> 4         Acer_opalus 1.18458392
#> 5    Acer_platanoides 1.53834688
#> 6 Acer_pseudoplatanus 0.85338120
#> 7    Acer_saccharinum 0.63902031