phylogenie 3.11.2

Generate phylogenetic datasets with minimal setup effort

---

Phylogenie is a Python package designed to easily simulate phylogenetic datasets—such as trees and multiple sequence alignments (MSAs)—with minimal setup effort. Simply specify the distributions from which your parameters should be sampled, and Phylogenie will handle the rest! It also makes it easy to define your own simulation models, allowing you to tailor simulations to your specific use cases.

✨ Features

Phylogenie comes packed with useful features, including:

• Simulate tree and multiple sequence alignment (MSA) datasets from parameter distributions 🌳🧬
  Define distributions over your parameters and sample a different combination of parameters for each dataset sample.

• Automatic metadata management 🗂️
  Phylogenie stores each parameter combination sampled during dataset generation in a .csv file.

• Generalizable configurations 🔧 Easily apply the same configuration across multiple dataset splits (e.g., train, validation, test).

• Flexible acceptance criteria 🔄
  Define custom acceptance criteria on the simulated trees to ensure they meet your requirements.

• Multiprocessing support ⚙️💻
  Simply specify the number of cores to use, and Phylogenie handles multiprocessing automatically.

• Pre-implemented parameterizations 🎯
  Include birth-death (BD), birth-death with exposed-infectious (BDEI), birth-death with superspreading (BDSS), susceptible-infected-recovered (SIR), and other commonly used parameterizations.

• Custom models and extensibility 🧩
  Define your own simulation models and extend Phylogenie via plugins.

• Skyline parameter support 🪜
  Support for piece-wise constant parameters.

• Operations on parameters 🧮
  Perform flexible operations between parameters directly within the config file.

📦 Installation

Phylogenie requires Python 3.10+ to be installed on your system. There are several ways to install Python and managing different Python versions. One popular option is to use uv.

Once you have Python set up, you can install Phylogenie directly from PyPI:

pip install phylogenie

Or install from source:

git clone https://github.com/gabriele-marino/phylogenie.git
cd phylogenie
pip install .

🛠 Backend dependencies

Phylogenie relies on AliSim for simulating multiple sequence alignments (MSAs). AliSim is a powerful MSAs simulation tool distributed with IQ-TREE, and requires separate installation to use it as a simulation backend.

🚀 Quick start

Once you have installed Phylogenie, check out the examples folder.

For quick start, pick your favorite config file and run Phylogenie with:

phylogenie examples/config_file.yaml

This command will create the output dataset in the folder specified inside the configuration file, including data directories and metadata files for each dataset split defined in the config.

📖 Examples and documentation

The documentation website provides a comprehensive reference, including detailed explanations of configuration options, models, and usage examples. It also covers the full Python API, along with step-by-step tutorials on how to develop custom plugins and extend the framework with new functionality.

📄 License

This project is licensed under MIT License.

📫 Contact

For questions, bug reports, or feature requests, please, consider opening an issue on GitHub, or contact me directly.

For help with configuration files, don’t hesitate to reach out — I’m happy to assist!