phylogenie

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!

✨ 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 canonical, fossilized birth-death, epidemiological, birth-death with exposed-infectious (BDEI), birth-death with superspreading (BDSS).

• 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 pyenv.

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 dependency

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 tutorials folder.
It includes a collection of thoroughly commented configuration files, organized as a step-by-step tutorial. These examples will help you understand how to use Phylogenie in practice and can be easily adapted to fit your own workflow.

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

phylogenie tutorials/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.

❗ Tip: Can’t choose just one config file? You can run them all at once by pointing Phylogenie to the folder! Just use: phylogenie tutorials. In this mode, Phylogenie will automatically find all .yaml files in the folder you specified and run for each of them!

📖 Documentation

• The tutorials folder contains many ready-to-use, extensively commented configuration files that serve as a step-by-step tutorial to guide you through using Phylogenie. You can explore them to learn how it works or adapt them directly to your own workflows.
• A complete user guide and API reference are under development. In the meantime, feel free to reach out if you have any questions about integrating Phylogenie into your workflows.

📄 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!