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 dinc or incubation fraction fE = dinc/d;
- fraction of superspreaders fS < 0.5;
- super-spreading transmission increase XS > 1;
- contact tracing probability υ;
- contact-traced removal speed up XC > 1.
Setting dinc=0 (equivalent to fE=0) removes incubation (EI), setting fS=0 or XS=1 removes superspreading (SS), while setting υ=0 or XC=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.
1 maintainer
Metadata
1 maintainer
Release files for bdext 0.2.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bdext-0.2.9.tar.gz | 32.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bdext-0.2.9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 64.9 MB
Release files / bdext-0.2.9.tar.gz
| Download URL | bdext-0.2.9.tar.gz |
|---|---|
| Size | 32.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
694a45f172036d3fc4182078a65081bc3ef3722b740e5f196d58e21e13af4962
|
|
BLAKE2b-256 checksum How to use checksums |
77fdd0b5a465df165e0df4e9e7c7fcd6fc359f369344c4f00e35409a50fa2eaf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.17
|
Release files / bdext-0.2.9-py3-none-any.whl
| Download URL | bdext-0.2.9-py3-none-any.whl |
|---|---|
| Size | 32.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
305479826ec6d454a1059a073431bc8e015d1257aac340299cf96bc336607936
|
|
BLAKE2b-256 checksum How to use checksums |
432d69d605c678be8d9387b9a2990b405fc6a28802e3e60d4de891837e63a5bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.17
|
