Tianjian Qin

How to install

This package illustrates how to integrate R with pre-trained neural network models for phylogenetic tree parameter estimation. Only R interface is provided in the package, although utilized both R and Python.

Step 1: Install R and Python

R (>=4.2.1) and Python (>=3.10) should be installed correctly. It is recommended to not alter the default settings of the installers.

Step 2: Install R packages

                        install.packages("devtools")
remotes::install_github("EvoLandEco/treestats")
remotes::install_github("EvoLandEco/EvoNN")
                    

A virtual environment “EvoNN” with necessary dependencies will also be installed in your home directory.
This may take a while. Wait for the completion message.

How to use

Step 1: Prepare the phylogeny

Click Here to download an example phylogeny by Valente et al. 2020 Nature, unzip to your favorite path.

                        library(EvoNN)
# Set the path to the tree file
path <- "your_path/Columbiformes.tre"
# Read in tree file if it is in Newick format, e.g. the example phylogeny
test_tre <- ape::read.tree(path)
# Otherwise, use the following to read in Nexus format
# test_tre <- ape::read.nexus(path)
                    

Step 2: Estimate parameters

The function estimates phylogenetic parameters from a phylo object.

                        result <- nn_estimate(test_tre, scenario = "DDD") 
                    

Step 3: Bootstrap uncertainty

Some parameter settings may take too long or fail consistently. It is recommended to set a timeout limit.

                        bootstrap <- nn_bootstrap_uncertainty(result, n = 100, timeout = 30)
                    

Step 4: Plot uncertainty

The neural network estimates are indicated by the red dashed lines and the blue values. Their uncertainties are represented by the density curves of bootstrap results.

nn_plot_bootstrap(bootstrap, result, scenario = "DDD")
                    

Output:

Known Issue

• Error messages may appear when you use library(EvoNN) to load the package right after installation. Try to fully close your IDE (e.g. R Studio, VS Code, or DataSpell, the software you use for R coding), then open it again. Re-run the example code, it should work this time.

• Mac users might have to install cmake to build some dependencies from source code. Run brew install --cask cmake in your terminal to install it.

Important Note

The package will automatically set up a Python virtual environment named “EvoNN” in your home directory during installation, this may take a while. A sanity check for this virtual environment will be performed every time library(EvoNN) is called. If this environment is altered, the package will try to reinstall mismatched dependencies.

You can manually remove this virtual environment by running the following code in R:

reticulate::virtualenv_remove("EvoNN")
                    

After removal, the package may fail to fix the environment on load unless you fully close all R sessions and restart.