Tapestree

Tapestree implements phylogenetic analyses of diversification, trait and biogeographic dynamics.

Travis AppVeyor Coverage Status codecov.io

References

For the TRIBE model:

  1. "Trait and Range Interspecific Biogeographic Evolution" (TRIBE): which implements a joint model of trait evolution and biogeographic history as described in Quintero, I., & Landis, M. J. (2020). Interdependent phenotypic and biogeographic evolution driven by biotic interactions. Systematic biology, 69(4), 739-755. https://doi.org/10.1093/sysbio/syz082

For the ESSE model: 2. "Environmental and State dependent Speciation and Extinction" (ESSE): which implements a joint geographic and environmental model of diversification as described in Quintero, I., Landis, M. J., Jetz, W., & Morlon, H. (2022). The build-up of the present-day tropical diversity of tetrapods. Proceedings of the National Academy of Sciences, 2023. 120 (20) e2220672120. https://doi.org/10.1073/pnas.2220672120

Usage

Requirements:

  • Julia v1.1.x
  • Tapestree Package installed along with RCall, Optim and ProgressMeter. Install packages by typing ] in the julia prompt and typing add <package_name>. For example, for Tapestree: add Tapestree.
  • R installed
  • R ape package installed.

TRIBE

  1. Open Julia v1.1.x

  2. Load Tapestree package:

using Tapestree
  1. Specify the path to the phylogenetic tree (in a format that ape can read):
finches_tree_file = "/directory_where_Tapestree_was_cloned/Tapestree/data/finches_rescaled.tre"
  1. Specify data. Data should be a .txt file where each row is a species, first the species name that matches the tree tip labels, second the phenotypic data and then the species presence in each area (0 if absent and 1 if present) . Open finches_pca1.txt in the data folder to see an example.
finches_data_file = "/directory_where_Tapestree_was_cloned/Tapestree/data/finches_pca1.txt"
  1. Specify output file (homedir() is an alias to your home folder)
out_file  = *(homedir(),"...")
  1. Run the tribe() (TRIBE: Trait and Range Interspecific Biogeographic Evolution) model:
tribe(finches_tree_file, finches_data_file, out_file)
  1. Further options for tribe() are
min_dt  = 0.01                       # a float describing the percentage of tree height allowed for discretization (lower values are more precise but take longer).
niter   = 10_000                     # an integer for the number of iterations.
nburn   = 5_000                      # an integer for the number of iterations in the adaptive burn-in phase.
nthin   = 100                        # an integer for the iteration sampling frequency.
saveXY  = (true, 1_000)              # a tuple of length 2: first is a boolean to save (or not) data augmented histories, second an integer for sampling frequency.
saveDM  = (true, 1_000)              # a tuple of length 2: first is a boolean to save (or not) data augmented deterministic effects, second an integer for sampling frequency.
ωxprior = (0.,10.)                   # a tuple of length 2 for the normal prior of ωx, first the mean, second the variance.
ω1prior = (0.,10.)                   # a tuple of length 2 for the normal prior of ω1, first the mean, second the variance.
ω0prior = (0.,10.)                   # a tuple of length 2 for the normal prior of ω0, first the mean, second the variance.
σ²prior = 1e-1                       # a float for the mean of the exponential prior for σ².
λprior  = 1e-1                       # a float for the mean of the exponential prior for both λs.
weight  = (0.15,0.05,0.02,0.02,5e-3) # a tuple of length 5 specifying the probabilities to update σ², ωx, ω1 & ω0, and λ1 & λ0 respectively.
λ1i     = 1.0                        # a float for the starting value for λ1.
λ0i     = 0.5                        # a float for the starting value for λ0.
ωxi     = 0.0                        # a float for the starting value for ωx.
ω1i     = 0.0                        # a float for the starting value for ω1.
ω0i     = 0.0                        # a float for the starting value for ω0.
fix_ωx  = false                      # a boolean to make inference without ωx.
fix_ω1  = false                      # a boolean to make inference without ω1.
fix_ω0  = false                      # a boolean to make inference without ω0.
  1. The output is a .log file with the results of the MCMC chain, and optionally (if saveXY = (true, k)), an R data file (.Rdata) with the augmented data histories. R code to manipulate and visualize this output are provided upon request.

Simulation

  1. Specify the path to the phylogenetic tree (in a format that ape can read):
finches_tree_file = "/directory_where_Tapestree_was_cloned/Tapestree/data/finches_rescaled.tre"
  1. Perform simulation (here with 0.0 as the inital trait value and 6 areas on the finches tree)
x_init  = 0.0
n_areas = 6
tip_values, tip_areas, tree, bts = simulate_tribe(x_init, n_areas, finches_tree_file)
  1. Further options for simulate_tribe() are
ωx       = 0.0   # a float for simulated value of ωx.
σ²       = 0.5   # a float for simulated value of σ².
ω1       = 0.0   # a float for simulated value of ω1.
ω0       = 0.0   # a float for simulated value of ω0.
λ1       = 0.5   # a float for simulated value of λ1.
λ0       = 0.2   # a float for simulated value of λ0.
const_δt = 1e-4  # a float for the delta t used to approximate the simulation (lower values are more accurate but at a slight computation cost).
  1. Specify output file (homedir() is an alias to your home folder)
out_file  = *(homedir(),"...")
  1. Run the tribe() (optional parameters are the same as with inference):
tribe(tip_values, tip_areas, tree, bts, out_file)

ESSE