phyddle 0.3.1

Software for exploring phylogenetic models with deep learning [manuscript]

User guide

Visit https://phyddle.org to learn how to use the software.

Overview

A standard phyddle analysis performs the following tasks for you:

• Pipeline configuration applies analysis settings provided through a config file and/or command line arguments.
• Simulate simulates a large training dataset using a user-designed simulator.
• Format encodes the raw simulated data (from Simulate) into tensor format for Train.
• Train loads and splits training data (from Format), builds a network, then trains and saves the network.
• Estimate estimates model parameters for a new dataset with the trained network (from Train).
• Plot generates figures that summarize the training data (Format), the network and its training (Train), and any new predictions (Estimate).

Quick start

To run a phyddle analysis enter the scripts directory:

cd ~/projects/phyddle

Then create and run a pipeline under the settings you've specified in workspace/example/config.py:

cd workspace/example
phyddle --cfg config.py

This will run a phyddle analysis with 1000 simulations using R and the castor package for a simple birth-death model with one 3-state character. In practice, you'll want to generate a larger training dataset with anywhere from 10k to 1M examples, depending on the model.

To add new examples to your training set

# simulate new training examples and store in simulate
phyddle -s S -c config.py --sim_more 14000

# encode all raw_data examples as tensors in format
phyddle -s F -c config.py

# train network with tensor data, but override batch size, then store in train
phyddle -s T -c config.py --trn_batch_size 256

# make prediction for empirical example in dataset
phyddle -s E -c config.py

# generate figures and store in plot
phyddle -s P -c config.py

To see a full list of all options currently supported by phyddle

phyddle --help

Installation

A stable version of phyddle can be installed using the Python package manager, pip:

python3 -m pip install --upgrade phyddle
# ... install ...
phyddle

...or using conda:

conda create -n phyddle_env -c bioconda -c landismj phyddle
# ... install ...
conda activate phyddle_env
phyddle

phyddle uses third-party simulators to generate training datasets. Example workflows assume that R, RevBayes, Phylojunction, or BEAST with MASTER (plugin) is installed on your machine and can be executed as a command from terminal. The documentation explains how to configure R for use with phyddle.

Need help?

Visit the Discussions page to interact with other phyddle users and receive help.

Citation

If you used phyddle, please cite:

MJ Landis, A Thompson. 2025. phyddle: software for exploring phylogenetic models with deep learning. Systematic Biology (in press). doi:10.1093/sysbio/syaf036.

A Thompson, B Liebeskind, EJ Scully, MJ Landis. 2024. Deep learning and likelihood approaches for viral phylogeography converge on the same answers whether the inference model is right or wrong. Systematic Biology 73:183-206.

Note on code stability

Code on the main branch is tested and stable with respect to the standard use cases. Code on the development branch contains new features, but is not as rigorously tested. Most phyddle development occurs on a 16-core Intel Macbook Pro laptop and a 64-core Intel Ubuntu server. Any feedback is appreciated! michael.landis@wustl.edu

About

Thanks for your interest in phyddle. The phyddle project emerged from a phylogenetic deep learning study led by Ammon Thompson (paper). The goal of phyddle is to provide its users with a generalizable pipeline workflow for phylogenetic modeling and deep learning. This hopefully will make it easier for phylogenetic model enthusiasts and developers to explore and apply models that do not have tractable likelihood functions. It's also intended for use by methods developers who want to characterize how deep learning methods perform under different conditions for standard phylogenetic estimation tasks. Read more about phyddle at https://doi.org/10.1093/sysbio/syaf036.

The phyddle project is developed by Michael Landis and Ammon Thompson.