treesimulator

Simulation of rooted phylogenetic trees under a given Multitype Birth–Death (MTBD) model. The MTBD models were introduced by Stadler & Bonhoeffer [Philos. Trans. R. Soc. B 2013].

We pay particular interest to the classical BD model, the BD Exposed-Infectious (BDEI) model, and BD with superspreading (BDSS), as they are described in [Voznica et al. 2021].

BD

3 parameters:

λ -- transmission rate
ψ -- removal rate
p -- sampling probability upon removal

Epidemiological parameters:

R₀=λ/ψ -- reproduction number
1/ψ -- infectious time

BDEI

2 compartments:

E, exposed, i.e. infected but not yet infectious
I, infectious

4 parameters:

μ -- transition rate from E to I (becoming infectious)
λ -- transmission rate from I to E
ψ -- removal rate of I
p -- sampling probability upon removal

Epidemiological parameters:

R₀=λ/ψ -- reproduction number
1/ψ -- infectious time
1/μ -- incubation period

BDSS

2 compartments:

N, standard infectious individual
S, superspreader

6 parameters:

λ_nn -- transmission rate from N to N
λ_ns -- transmission rate from N to S
λ_sn -- transmission rate from S to N
λ_ss -- transmission rate from S to S

(with a constraint that λ_ss/λ_ns=λ_sn/λ_nn)
ψ -- removal rate of S and of N (the same)
p -- sampling probability upon removal (the same for N and S)

Epidemiological parameters:

R₀=(λ_nn + λ_ss)/ψ -- reproduction number
1/ψ -- infectious time
X=λ_ss/λ_ns=λ_sn/λ_nn -- super-spreading transmission ratio
f=λ_ss/(λ_sn + λ_ss) -- super-spreading fraction

Installation

To install treesimulator:

pip3 install treesimulator

Usage

Command line

BD

The following command simulates a tree with 200-500 tips under BD model, with λ=0.5, ψ=0.25, p=0.5, and saves it to a file tree.nwk, while saving the parameters to a comma-separated file params.csv:

generate_bd --min_tips 200 --max_tips 500 --la 0.5 --psi 0.25 --p 0.5 --nwk tree.nwk --log params.csv

To seee detailed options, run:

generate_bd --help

BDEI

The following command simulates a tree with 200-500 tips under BDEI model, with μ=1, λ=0.5, ψ=0.25, p=0.5, and saves it to a file tree.nwk, while saving the parameters to a comma-separated file params.csv:

generate_bdei --min_tips 200 --max_tips 500 --mu 1 --la 0.5 --psi 0.25 --p 0.5 --nwk tree.nwk --log params.csv

To seee detailed options, run:

generate_bdei --help

BDSS

The following command simulates a tree with 200-500 tips under BDSS model, with λ_nn=0.1, λ_ns=0.3, λ_sn=0.5, λ_ss=1.5, ψ=0.25, p=0.5, and saves it to a file tree.nwk, while saving the parameters to a comma-separated file params.csv:

generate_bdss --min_tips 200 --max_tips 500 --la_nn 0.1 --la_ns 0.3 --la_sn 0.5 --la_ss 1.5 --psi 0.25 --p 0.5 --nwk tree.nwk --log params.csv

To seee detailed options, run:

generate_bdss --help

User-defined MTBD model

The following command simulates a tree with 200-500 tips under a generic MTBD model, with two states A and B, with μ_aa=0.5, μ_ab=0.6, μ_ba=0.7, μ_bb=0.8, λ_aa=0.1, λ_ab=0.2, λ_ba=0.3, λ_bb=0.4, ψ_a=0.05, ψ_b=0.08, p=_a0.15, p=_b0.65, and saves it to a file tree.nwk, while saving the parameters to a comma-separated file params.csv:

generate_mtbd --min_tips 200 --max_tips 500 --nwk tree.nwk --log params.csv \
--states A B \
--transition_rates 0.5 0.6 0.7 0.8 \
--transmission_rates 0.1 0.2 0.3 0.4 \
--removal_rates 0.05 0.08 \
--sampling_probabilities 0.15 0.65

To seee detailed options, run:

generate_mtbd --help

Python3

To simulate trees with 200-500 tips under the above models and settings:

from treesimulator.generator import generate
from treesimulator import save_forest
from treesimulator.mtbd_models import Model, BirthDeathModel, BirthDeathExposedInfectiousModel, BirthDeathWithSuperSpreadingModel

bd_model = BirthDeathModel(p=0.5, la=0.5, psi=0.25)
print(bd_model.get_epidemiological_parameters())
[bd_tree], (bd_total_tips, _, bd_total_time) = generate(bd_model, min_tips=200, max_tips=500)
save_forest([bd_tree], 'BD_tree.nwk')

bdei_model = BirthDeathExposedInfectiousModel(p=0.5, mu=1, la=0.5, psi=0.25)
print(bdei_model.get_epidemiological_parameters())
[bdei_tree], (bdei_total_tips, _, bdei_total_time) = generate(bdei_model, min_tips=200, max_tips=500)
save_forest([bdei_tree], 'BDEI_tree.nwk')

bdss_model = BirthDeathWithSuperSpreadingModel(p=0.5, la_nn=0.1, la_ns=0.3, la_sn=0.5, la_ss=1.5, psi=0.25)
print(bdss_model.get_epidemiological_parameters())
[bdss_tree], (bdss_total_tips, _, bdss_total_time) = generate(bdss_model, min_tips=200, max_tips=500)
save_forest([bdss_tree], 'BDSS_tree.nwk')

mtbd_model = Model(states=['A', 'B'], transition_rates=[[0.5, 0.6], [0.7, 0.8]], 
                   transmission_rates=[[0.1, 0.2], [0.3, 0.4]],
                   removal_rates=[0.05, 0.08], ps=[0.15, 0.65])
[mtbd_tree], (mtbd_total_tips, _, mtbd_total_time) = generate(mtbd_model, min_tips=200, max_tips=500)
save_forest([mtbd_tree], 'MTBD_tree.nwk')

Release files for treesimulator 0.1.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for treesimulator 0.1.22
File	Size	Uploaded
treesimulator-0.1.22.tar.gz	28.0 kB	Jul 1, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for treesimulator 0.1.22
File	Interpreter	ABI	Platform	Reset
treesimulator-0.1.22-py3-none-any.whl 31.5 kB Jul 1, 2024	Python 3	none	any	Details

Total release size: 59.5 kB

Release files / treesimulator-0.1.22.tar.gz

Download URL	treesimulator-0.1.22.tar.gz
Size	28.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`2ea8d07b1ef98590b1477c322d8a06efabf63f39ac7d9ff0f75f6063e48898c8`
BLAKE2b-256 checksum How to use checksums	`42fa3650ae720513aab5eff856b4f441b32f791661c6ff4472bb921cc3f685dd`
Upload date	Jul 1, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.8.0 colorama/0.4.4 importlib-metadata/4.6.4 keyring/23.5.0 pkginfo/1.8.2 readme-renderer/34.0 requests-toolbelt/0.9.1 requests/2.25.1 rfc3986/1.5.0 tqdm/4.57.0 urllib3/1.26.5 CPython/3.10.12`

Release files / treesimulator-0.1.22-py3-none-any.whl

Download URL	treesimulator-0.1.22-py3-none-any.whl
Size	31.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0612469b4918fb0083c8265130edeb9bc3bb0fbfa4f8a87aed1f97bc48897994`
BLAKE2b-256 checksum How to use checksums	`8ed88491641183aacfcba96098c115185e9ddb56bf5da35d68adee0660f2a388`
Upload date	Jul 1, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.8.0 colorama/0.4.4 importlib-metadata/4.6.4 keyring/23.5.0 pkginfo/1.8.2 readme-renderer/34.0 requests-toolbelt/0.9.1 requests/2.25.1 rfc3986/1.5.0 tqdm/4.57.0 urllib3/1.26.5 CPython/3.10.12`