bdext

The bdext package provides scripts to simulate transmission trees, train Deep-Learning-based estimators, and estimate epidemiological parameters with BD(EI)(SS)(CT) models from dated phylogenetic trees.

BDEISS-CT model

The Birth-Death (BD) Exposed-Infectious (EI) with SuperSpreading (SS) and Contact-Tracing (CT) model (BDEISS-CT) can be described with the following 8 parameters:

average reproduction number R;
average total infection duration d;
sampling probability ρ;
incubation period d_inc or incubation fraction f_E = d_inc/d;
fraction of superspreaders f_S < 0.5;
super-spreading transmission increase X_S > 1;
contact tracing probability υ;
contact-traced removal speed up X_C > 1.

Setting d_inc=0 (equivalent to f_E=0) removes incubation (EI), setting f_S=0 or X_S=1 removes superspreading (SS), while setting υ=0 or X_C=1 removes contact-tracing (CT).

For identifiability, we require the sampling probability ρ to be given by the user. The other parameters are estimated from a time-scaled phylogenetic tree.

Example data

In the examples below we will use the wave3.days.nwk tree as an example to show how to run the commands. This tree is a time-scaled phylogenetic tree of SARS-CoV-2 sequences sampled in Hong-Kong during the third wave of the pandemic, resolved with contact-tracing data and rescaled to days. It was reconstructed by Xie et al. 2024. The estimated sampling probability for this tree is ρ=0.238.

Installation

There are 3 alternative ways to run bdct on your computer: with apptainer, in Python3, or via command line (requires installation with Python3, potentially using conda).

Installation and use in python3 or command-line (for linux systems, recommended Ubuntu 21 or newer versions)

You could either install python (version 3.10 or higher) system-wide and then install bdext via pip:

sudo apt install -y python3 python3-pip python3-setuptools python3-distutils
pip3 install bdext

or alternatively, you could install python (version 3.10 or higher) and bdext via conda (make sure that conda is installed first). Here we will create a conda environment called phylodyn:

conda create --name phylodyn python=3.10
conda activate phylodyn
pip install bdext

Basic usage in a command line

If you installed bdext in a conda environment (here named phylodyn), do not forget to first activate it, e.g.

conda activate phylodyn

We will analyse the [wave3.days.nwk][real_data/wave3.days.nwk] tree, using ρ=0.238 (see above for details). For each of the 8 BDEISS-CT nested models, we will assess whether the tree resembles the transmission trees in its training dataset by checking the summary statistics and reporting those with z-score > 5. We will then make estimates with each model.

for model in BD BDEI BDSS BDCT BDEISS BDEICT BDSSCT BDEISSCT
do
    bdeissct_check --nwk wave3.days.nwk --p 0.238 --model_name ${model} --log wave3.days.ss_${model}.tab
    bdeissct_infer --nwk wave3.days.nwk --p 0.238 --model_name ${model} --log wave3.days.est_${model}.tab
done

Help

To see detailed options, run:

bdeissct_check --help
bdeissct_infer --help

Additional commands

There are also commands to simulate trees, encode them into summary statistics and train models available:

bdeissct_simulate --help
bdeissct_encode --help
bdeissct_train --help

To see an example of how to use these commands, see the example/main.py file.

Basic usage in Python

To see an example of how to use bdext in Python, see the example/main.py file.

Run with apptainer

Once apptainer is installed, run the following command (update the version as needed, here v0.1.98 is used as an example):

apptainer run docker://evolbioinfo/bdext:v0.1.98

This will launch a terminal session within the container, in which you can run bdext commands following the instructions for the command line ("Basic usage in a command line") above.

Training the models from scratch

The simulations_bdeissct in folder contains the explanations and command-line pipelines for generation of training and test datasets, and deep-learning-based BD(EI)(SS)(-CT) model training.

The example folder contains the explanations and a python file with code needed for generation of training and test datasets, and deep-learning-based BD(EI)(SS)(-CT) model training directly in python.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bdext-0.2.1.tar.gz (6.6 MB view details)

Uploaded Sep 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

bdext-0.2.1-py3-none-any.whl (6.7 MB view details)

Uploaded Sep 3, 2026 Python 3

File details

Details for the file bdext-0.2.1.tar.gz.

File metadata

Download URL: bdext-0.2.1.tar.gz
Upload date: Sep 3, 2026
Size: 6.6 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.10.17

File hashes

Hashes for bdext-0.2.1.tar.gz
Algorithm	Hash digest
SHA256	`5d6b85db2aeb2f3e1b29c42fe2fe8f0be190af8791735da2a3db516773933c07`
MD5	`8d2881965f5b39ee67a55e3de1aa4375`
BLAKE2b-256	`3142c40e41806e786afee074b62bf17dce7151cd183594926b1fe1dab74daf0a`

See more details on using hashes here.

File details

Details for the file bdext-0.2.1-py3-none-any.whl.

File metadata

Download URL: bdext-0.2.1-py3-none-any.whl
Upload date: Sep 3, 2026
Size: 6.7 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.10.17

File hashes

Hashes for bdext-0.2.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`078a381962184af4027cb20eea31b00daedda3a403d95901bc6545dd4c49dcb3`
MD5	`27d7ab843ad6d4ae9009a54116900423`
BLAKE2b-256	`56de1872154e95d3edf491451f7dd3d944cbd53a19229223a3f4e8679f459724`