# treesimulator
Simulation of rooted phylogenetic trees under a given Multitype Birth–Death (MTBD) model, with or without partner notification (PN).
[//]: # ([](https://doi.org/10.1093/sysbio/syad059))
[](https://github.com/evolbioinfo/treesimulator/releases)
[](https://pypi.org/project/treesimulator/)
[](https://pypi.org/project/treesimulator/)
[](https://hub.docker.com/r/evolbioinfo/treesimulator/tags)
## MTBD
The MTBD models were introduced by Stadler & Bonhoeffer [[_Philos. Trans. R. Soc. B_ 2013]](https://royalsocietypublishing.org/doi/10.1098/rstb.2012.0198).
An MTBD model with m states has
m(m-1) state transition rate parameters:
* μ<sub>ij</sub> -- transition rate from state i to state j (1 ≤ i, j ≤ m; i ≠ j), where μ<sub>ij</sub> ≥ 0
m<sup>2</sup> transmission rate parameters:
* λ<sub>ij</sub> -- transmission rate from state i (donor) to state j (recipient) (1 ≤ i, j ≤ m), where λ<sub>ij</sub> ≥ 0
m removal (becoming non-infectious) rate parameters:
* ψ<sub>i</sub> -- removal rate of state i (1 ≤ i ≤ m), where ψ<sub>i</sub> ≥ 0
m sampling probability upon removal parameters:
* p<sub>i</sub> -- probability to sample the pathogen of an individual in state i upon removal (1 ≤ i ≤ m), where 0 < p<sub>i</sub> ≤ 1
## Partner Notification (PN)
Partner notification adds two parameters to the initial MTBD model:
* υ -- probability to notify partners upon sampling
* φ -- notified partner removal and sampling rate: φ >> ψ<sub>i</sub> ∀i (1 ≤ i ≤ m). The pathogen of a notified partner is sampled automatically (with a probability of 1) upon removal.
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]]((https://www.biorxiv.org/content/10.1101/2021.03.11.435006v1)), and to their -PN versions.
## BD
3 parameters:
* λ -- transmission rate
* ψ -- removal rate
* p -- sampling probability upon removal
Epidemiological parameters:
* R<sub>0</sub>=λ/ψ -- reproduction number
* 1/ψ -- infectious time
## BD-PN
5 parameters:
* λ -- transmission rate
* ψ -- removal rate
* p -- sampling probability upon removal
* υ -- probability to notify partners upon sampling
* φ -- notified partner removal and sampling rate: φ >> ψ
Epidemiological parameters:
* R<sub>0</sub>=λ/ψ -- reproduction number
* 1/ψ -- infectious time
* 1/φ -- notified partner removal time
## BDEI
2 states:
* 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<sub>0</sub>=λ/ψ -- reproduction number
* 1/ψ -- infectious time
* 1/μ -- incubation period
## BDEI-PN
2 states:
* E, exposed, i.e. infected but not yet infectious
* I, infectious
6 parameters:
* μ -- transition rate from E to I (becoming infectious)
* λ -- transmission rate from I to E
* ψ -- removal rate of I
* p -- sampling probability upon removal
* υ -- probability to notify partners upon sampling
* φ -- notified partner removal and sampling rate: φ >> ψ
Epidemiological parameters:
* R<sub>0</sub>=λ/ψ -- reproduction number
* 1/ψ -- infectious time
* 1/μ -- incubation period
* 1/φ -- notified partner removal time
## BDSS
2 compartments:
* N, standard infectious individual
* S, superspreader
6 parameters:
* λ<sub>nn</sub> -- transmission rate from N to N
* λ<sub>ns</sub> -- transmission rate from N to S
* λ<sub>sn</sub> -- transmission rate from S to N
* λ<sub>ss</sub> -- transmission rate from S to S
(with a constraint that λ<sub>ss</sub>/λ<sub>ns</sub>=λ<sub>sn</sub>/λ<sub>nn</sub>)
* ψ -- removal rate of S and of N (the same)
* p -- sampling probability upon removal (the same for N and S)
Epidemiological parameters:
* R<sub>0</sub>=(λ<sub>nn</sub> + λ<sub>ss</sub>)/ψ -- reproduction number
* 1/ψ -- infectious time
* X=λ<sub>ss</sub>/λ<sub>ns</sub>=λ<sub>sn</sub>/λ<sub>nn</sub> -- super-spreading transmission ratio
* f=λ<sub>ss</sub>/(λ<sub>sn</sub> + λ<sub>ss</sub>) -- super-spreading fraction
## BDSS-PN
2 states:
* N, standard infectious individual
* S, superspreader
8 parameters:
* λ<sub>nn</sub> -- transmission rate from N to N
* λ<sub>ns</sub> -- transmission rate from N to S
* λ<sub>sn</sub> -- transmission rate from S to N
* λ<sub>ss</sub> -- transmission rate from S to S
(with a constraint that λ<sub>ss</sub>/λ<sub>ns</sub>=λ<sub>sn</sub>/λ<sub>nn</sub>)
* ψ -- removal rate of S and of N (the same)
* p -- sampling probability upon removal (the same for N and S)
* υ -- probability to notify partners upon sampling
* φ -- notified partner removal and sampling rate: φ >> ψ
Epidemiological parameters:
* R<sub>0</sub>=(λ<sub>nn</sub> + λ<sub>ss</sub>)/ψ -- reproduction number
* 1/ψ -- infectious time
* X=λ<sub>ss</sub>/λ<sub>ns</sub>=λ<sub>sn</sub>/λ<sub>nn</sub> -- super-spreading transmission ratio
* f=λ<sub>ss</sub>/(λ<sub>sn</sub> + λ<sub>ss</sub>) -- super-spreading fraction
* 1/φ -- notified partner removal time
## Installation
There are 4 alternative ways to run __treesimulator__ on your computer:
with [docker](https://www.docker.com/community-edition),
[apptainer](https://apptainer.org/),
in Python3, or via command line (requires installation with Python3).
### Installation in python3 or command-line
You could either install python (version 3.6 or higher) system-wide and then install treesimulator via pip:
```bash
sudo apt install -y python3 python3-pip python3-setuptools python3-distutils
pip3 install treesimulator
```
or alternatively, you could install python (version 3.6 or higher) and treesimulator via [conda](https://conda.io/docs/) (make sure that conda is installed first).
(Optional) to install treesimulator in a new conda environment (e.g., called _phyloenv_ below), first create and activate the environment:
```bash
conda create --name phyloenv python=3.6
conda activate phyloenv
```
Install treesimulator with conda
```bash
conda install treesimulator
```
### Basic usage in a command line
If you installed __treesimulator__ in a conda environment (here named _phyloenv_), do not forget to first activate it, e.g.
```bash
conda activate phyloenv
```
#### BD and BD-PN
The following command simulates a tree with 200-500 tips under the BD model, with λ=0.5, ψ=0.25, p=0.5,
and saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:
```bash
generate_bd --min_tips 200 --max_tips 500 \
--la 0.5 --psi 0.25 --p 0.5 \
--nwk tree.nwk --log params.csv
```
The following command simulates a tree with 200-500 tips under the BD-PN model, with λ=0.5, ψ=0.25, p=0.5, φ=2.5, υ=0.2,
and allowing to notify only the most recent partner of each sampled index case.
The simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:
```bash
generate_bd --min_tips 200 --max_tips 500 \
--la 0.5 --psi 0.25 --p 0.5 \
--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \
--nwk tree.nwk --log params.csv
```
To see detailed options, run:
```bash
generate_bd --help
```
#### BDEI and BDEI-PN
The following command simulates a tree with 200-500 tips under the BDEI model, with μ=1, λ=0.5, ψ=0.25, p=0.5,
and saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:
```bash
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
```
The following command simulates a tree with 200-500 tips under the BDEI-PN model, with μ=1, λ=0.5, ψ=0.25, p=0.5, φ=2.5, υ=0.2,
and allowing to notify only the most recent partner of each sampled index case.
The simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:
```bash
generate_bdei --min_tips 200 --max_tips 500 \
--mu 1 --la 0.5 --psi 0.25 --p 0.5 \
--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \
--nwk tree.nwk --log params.csv
```
To see detailed options, run:
```bash
generate_bdei --help
```
#### BDSS and BDSS-PN
The following command simulates a tree with 200-500 tips under the BDSS model,
with λ<sub>nn</sub>=0.1, λ<sub>ns</sub>=0.3, λ<sub>sn</sub>=0.5, λ<sub>ss</sub>=1.5, ψ=0.25, p=0.5,
and saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:
```bash
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
```
The following command simulates a tree with 200-500 tips under the BDSS-PN model,
with λ<sub>nn</sub>=0.1, λ<sub>ns</sub>=0.3, λ<sub>sn</sub>=0.5, λ<sub>ss</sub>=1.5, ψ=0.25, p=0.5, φ=2.5, υ=0.2,
and allowing to notify only the most recent partner of each sampled index case.
The simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:
```bash
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 \
--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \
--nwk tree.nwk --log params.csv
```
To see detailed options, run:
```bash
generate_bdss --help
```
#### User-defined MTBD and MTBD-PN models
The following command simulates a tree with 200-500 tips under a generic MTBD model, with two states A and B,
with μ<sub>aa</sub>=0.5, μ<sub>ab</sub>=0.6, μ<sub>ba</sub>=0.7, μ<sub>bb</sub>=0.8,
λ<sub>aa</sub>=0.1, λ<sub>ab</sub>=0.2, λ<sub>ba</sub>=0.3, λ<sub>bb</sub>=0.4,
ψ<sub>a</sub>=0.05, ψ<sub>b</sub>=0.08,
p=<sub>a</sub>0.15, p=<sub>b</sub>0.65,
and saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:
```bash
generate_mtbd --min_tips 200 --max_tips 500 \
--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 \
--nwk tree.nwk --log params.csv
```
The following command simulates a tree with 200-500 tips under a generic MTBD model, with two states A and B,
with μ<sub>aa</sub>=0.5, μ<sub>ab</sub>=0.6, μ<sub>ba</sub>=0.7, μ<sub>bb</sub>=0.8,
λ<sub>aa</sub>=0.1, λ<sub>ab</sub>=0.2, λ<sub>ba</sub>=0.3, λ<sub>bb</sub>=0.4,
ψ<sub>a</sub>=0.05, ψ<sub>b</sub>=0.08,
p=<sub>a</sub>0.15, p=<sub>b</sub>0.65,
φ=2.5, υ=0.2,
and allowing to notify only the most recent partner of each sampled index case.
The simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:
```bash
generate_mtbd --min_tips 200 --max_tips 500 \
--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 \
--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \
--nwk tree.nwk --log params.csv
```
To see detailed options, run:
```bash
generate_mtbd --help
```
#### Basic usage in Python3
To simulate trees with 200-500 tips under the above models and settings:
```python3
from treesimulator.generator import generate
from treesimulator import save_forest
from treesimulator.mtbd_models import Model, BirthDeathModel, BirthDeathExposedInfectiousModel, \
BirthDeathWithSuperSpreadingModel, PNModel
# BD and BD-PN
bd_model = BirthDeathModel(p=0.5, la=0.5, psi=0.25)
print(bd_model.get_epidemiological_parameters())
[bd_tree], _, _ = generate(bd_model, min_tips=200, max_tips=500)
save_forest([bd_tree], 'BD_tree.nwk')
bdpn_model = PNModel(model=bd_model, upsilon=0.2, partner_removal_rate=2.5)
[bdpn_tree], _, _ = generate(bdpn_model, min_tips=200, max_tips=500)
save_forest([bdpn_tree], 'BDPN_tree.nwk')
# BDEI and BDEI-PN
bdei_model = BirthDeathExposedInfectiousModel(p=0.5, mu=1, la=0.5, psi=0.25)
print(bdei_model.get_epidemiological_parameters())
[bdei_tree], _, _ = generate(bdei_model, min_tips=200, max_tips=500)
save_forest([bdei_tree], 'BDEI_tree.nwk')
bdeipn_model = PNModel(model=bdei_model, upsilon=0.2, partner_removal_rate=2.5)
[bdeipn_tree], _, _ = generate(bdeipn_model, min_tips=200, max_tips=500)
save_forest([bdeipn_tree], 'BDEIPN_tree.nwk')
# BDSS and BDSS-PN
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], _, _ = generate(bdss_model, min_tips=200, max_tips=500)
save_forest([bdss_tree], 'BDSS_tree.nwk')
bdsspn_model = PNModel(model=bdss_model, upsilon=0.2, partner_removal_rate=2.5)
[bdsspn_tree], _, _ = generate(bdsspn_model, min_tips=200, max_tips=500)
save_forest([bdsspn_tree], 'BDSSPN_tree.nwk')
# MTBD and MTBD-PN
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], _, _ = generate(mtbd_model, min_tips=200, max_tips=500)
save_forest([mtbd_tree], 'MTBD_tree.nwk')
mtbdpn_model = PNModel(model=mtbd_model, upsilon=0.2, partner_removal_rate=2.5)
[mtbdpn_tree], _, _ = generate(mtbdpn_model, min_tips=200, max_tips=500)
save_forest([mtbdpn_tree], 'MTBDPN_tree.nwk')
```
### Run with apptainer
Once [apptainer](https://apptainer.org/docs/user/latest/quick_start.html#installation) is installed,
run the following command:
```bash
apptainer run docker://evolbioinfo/treesimlator
```
This will launch a terminal session within the container,
in which you can run treesimulator following the instructions for the command line ("Basic usage in a command line") above.
Raw data
{
"_id": null,
"home_page": "https://github.com/evolbioinfo/treesimulator",
"name": "treesimulator",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "phylogenetics, tree generator, multitype birth-death model",
"author": "Anna Zhukova",
"author_email": "anna.zhukova@pasteur.fr",
"download_url": "https://files.pythonhosted.org/packages/ce/92/433a8b91fe6975bb77c3ec8ea63a06ed77f5ff1367e6b1924de819130311/treesimulator-0.2.0.tar.gz",
"platform": null,
"description": "# treesimulator\n\nSimulation of rooted phylogenetic trees under a given Multitype Birth\u2013Death (MTBD) model, with or without partner notification (PN).\n\n[//]: # ([](https://doi.org/10.1093/sysbio/syad059))\n[](https://github.com/evolbioinfo/treesimulator/releases)\n[](https://pypi.org/project/treesimulator/)\n[](https://pypi.org/project/treesimulator/)\n[](https://hub.docker.com/r/evolbioinfo/treesimulator/tags)\n\n## MTBD\nThe MTBD models were introduced by Stadler & Bonhoeffer [[_Philos. Trans. R. Soc. B_ 2013]](https://royalsocietypublishing.org/doi/10.1098/rstb.2012.0198).\n\nAn MTBD model with m states has \n\nm(m-1) state transition rate parameters:\n* \u03bc<sub>ij</sub> -- transition rate from state i to state j (1 \u2264 i, j \u2264 m; i \u2260 j), where \u03bc<sub>ij</sub> \u2265 0\n\nm<sup>2</sup> transmission rate parameters:\n* \u03bb<sub>ij</sub> -- transmission rate from state i (donor) to state j (recipient) (1 \u2264 i, j \u2264 m), where \u03bb<sub>ij</sub> \u2265 0\n\nm removal (becoming non-infectious) rate parameters:\n* \u03c8<sub>i</sub> -- removal rate of state i (1 \u2264 i \u2264 m), where \u03c8<sub>i</sub> \u2265 0\n\nm sampling probability upon removal parameters:\n* p<sub>i</sub> -- probability to sample the pathogen of an individual in state i upon removal (1 \u2264 i \u2264 m), where 0 < p<sub>i</sub> \u2264 1\n\n## Partner Notification (PN)\nPartner notification adds two parameters to the initial MTBD model:\n\n* \u03c5 -- probability to notify partners upon sampling\n* \u03c6 -- notified partner removal and sampling rate: \u03c6 >> \u03c8<sub>i</sub> \u2200i (1 \u2264 i \u2264 m). The pathogen of a notified partner is sampled automatically (with a probability of 1) upon removal. \n\n\nWe pay particular interest to the classical BD model, the BD Exposed-Infectious (BDEI) model, \nand BD with superspreading (BDSS), \nas they are described in [[Voznica _et al._ 2021]]((https://www.biorxiv.org/content/10.1101/2021.03.11.435006v1)), and to their -PN versions.\n\n\n## BD\n3 parameters:\n* \u03bb -- transmission rate\n* \u03c8 -- removal rate\n* p -- sampling probability upon removal\n\nEpidemiological parameters:\n* R<sub>0</sub>=\u03bb/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n\n\n## BD-PN\n5 parameters:\n* \u03bb -- transmission rate\n* \u03c8 -- removal rate\n* p -- sampling probability upon removal\n* \u03c5 -- probability to notify partners upon sampling\n* \u03c6 -- notified partner removal and sampling rate: \u03c6 >> \u03c8 \n\n\nEpidemiological parameters:\n* R<sub>0</sub>=\u03bb/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n* 1/\u03c6 -- notified partner removal time\n\n## BDEI\n2 states: \n* E, exposed, i.e. infected but not yet infectious\n* I, infectious\n\n4 parameters:\n* \u03bc -- transition rate from E to I (becoming infectious)\n* \u03bb -- transmission rate from I to E\n* \u03c8 -- removal rate of I\n* p -- sampling probability upon removal\n\nEpidemiological parameters:\n* R<sub>0</sub>=\u03bb/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n* 1/\u03bc -- incubation period\n\n\n## BDEI-PN\n2 states: \n* E, exposed, i.e. infected but not yet infectious\n* I, infectious\n\n6 parameters:\n* \u03bc -- transition rate from E to I (becoming infectious)\n* \u03bb -- transmission rate from I to E\n* \u03c8 -- removal rate of I\n* p -- sampling probability upon removal\n* \u03c5 -- probability to notify partners upon sampling\n* \u03c6 -- notified partner removal and sampling rate: \u03c6 >> \u03c8 \n\nEpidemiological parameters:\n* R<sub>0</sub>=\u03bb/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n* 1/\u03bc -- incubation period\n* 1/\u03c6 -- notified partner removal time\n\n## BDSS\n2 compartments: \n* N, standard infectious individual\n* S, superspreader\n\n6 parameters:\n* \u03bb<sub>nn</sub> -- transmission rate from N to N\n* \u03bb<sub>ns</sub> -- transmission rate from N to S\n* \u03bb<sub>sn</sub> -- transmission rate from S to N\n* \u03bb<sub>ss</sub> -- transmission rate from S to S\n\n (with a constraint that \u03bb<sub>ss</sub>/\u03bb<sub>ns</sub>=\u03bb<sub>sn</sub>/\u03bb<sub>nn</sub>)\n* \u03c8 -- removal rate of S and of N (the same)\n* p -- sampling probability upon removal (the same for N and S)\n\nEpidemiological parameters:\n* R<sub>0</sub>=(\u03bb<sub>nn</sub> + \u03bb<sub>ss</sub>)/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n* X=\u03bb<sub>ss</sub>/\u03bb<sub>ns</sub>=\u03bb<sub>sn</sub>/\u03bb<sub>nn</sub> -- super-spreading transmission ratio\n* f=\u03bb<sub>ss</sub>/(\u03bb<sub>sn</sub> + \u03bb<sub>ss</sub>) -- super-spreading fraction\n\n## BDSS-PN\n2 states: \n* N, standard infectious individual\n* S, superspreader\n\n8 parameters:\n* \u03bb<sub>nn</sub> -- transmission rate from N to N\n* \u03bb<sub>ns</sub> -- transmission rate from N to S\n* \u03bb<sub>sn</sub> -- transmission rate from S to N\n* \u03bb<sub>ss</sub> -- transmission rate from S to S\n\n (with a constraint that \u03bb<sub>ss</sub>/\u03bb<sub>ns</sub>=\u03bb<sub>sn</sub>/\u03bb<sub>nn</sub>)\n* \u03c8 -- removal rate of S and of N (the same)\n* p -- sampling probability upon removal (the same for N and S)\n* \u03c5 -- probability to notify partners upon sampling\n* \u03c6 -- notified partner removal and sampling rate: \u03c6 >> \u03c8 \n\nEpidemiological parameters:\n* R<sub>0</sub>=(\u03bb<sub>nn</sub> + \u03bb<sub>ss</sub>)/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n* X=\u03bb<sub>ss</sub>/\u03bb<sub>ns</sub>=\u03bb<sub>sn</sub>/\u03bb<sub>nn</sub> -- super-spreading transmission ratio\n* f=\u03bb<sub>ss</sub>/(\u03bb<sub>sn</sub> + \u03bb<sub>ss</sub>) -- super-spreading fraction\n* 1/\u03c6 -- notified partner removal time\n\n\n## Installation\n\nThere are 4 alternative ways to run __treesimulator__ on your computer: \nwith [docker](https://www.docker.com/community-edition), \n[apptainer](https://apptainer.org/),\nin Python3, or via command line (requires installation with Python3).\n\n\n### Installation in python3 or command-line\n\nYou could either install python (version 3.6 or higher) system-wide and then install treesimulator via pip:\n```bash\nsudo apt install -y python3 python3-pip python3-setuptools python3-distutils\npip3 install treesimulator\n```\n\nor alternatively, you could install python (version 3.6 or higher) and treesimulator via [conda](https://conda.io/docs/) (make sure that conda is installed first). \n\n(Optional) to install treesimulator in a new conda environment (e.g., called _phyloenv_ below), first create and activate the environment:\n```bash\nconda create --name phyloenv python=3.6\nconda activate phyloenv\n```\n\nInstall treesimulator with conda\n```bash\nconda install treesimulator\n```\n\n\n### Basic usage in a command line\nIf you installed __treesimulator__ in a conda environment (here named _phyloenv_), do not forget to first activate it, e.g.\n\n```bash\nconda activate phyloenv\n```\n\n\n#### BD and BD-PN\nThe following command simulates a tree with 200-500 tips under the BD model, with \u03bb=0.5, \u03c8=0.25, p=0.5,\nand saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:\n```bash\ngenerate_bd --min_tips 200 --max_tips 500 \\\n--la 0.5 --psi 0.25 --p 0.5 \\\n--nwk tree.nwk --log params.csv\n```\nThe following command simulates a tree with 200-500 tips under the BD-PN model, with \u03bb=0.5, \u03c8=0.25, p=0.5, \u03c6=2.5, \u03c5=0.2, \nand allowing to notify only the most recent partner of each sampled index case. \nThe simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:\n```bash\ngenerate_bd --min_tips 200 --max_tips 500 \\\n--la 0.5 --psi 0.25 --p 0.5 \\\n--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \\\n--nwk tree.nwk --log params.csv\n```\nTo see detailed options, run:\n```bash\ngenerate_bd --help\n```\n\n#### BDEI and BDEI-PN\nThe following command simulates a tree with 200-500 tips under the BDEI model, with \u03bc=1, \u03bb=0.5, \u03c8=0.25, p=0.5, \nand saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:\n```bash\ngenerate_bdei --min_tips 200 --max_tips 500 \\\n--mu 1 --la 0.5 --psi 0.25 --p 0.5 \\\n--nwk tree.nwk --log params.csv\n```\nThe following command simulates a tree with 200-500 tips under the BDEI-PN model, with \u03bc=1, \u03bb=0.5, \u03c8=0.25, p=0.5, \u03c6=2.5, \u03c5=0.2, \nand allowing to notify only the most recent partner of each sampled index case. \nThe simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:\n```bash\ngenerate_bdei --min_tips 200 --max_tips 500 \\\n--mu 1 --la 0.5 --psi 0.25 --p 0.5 \\\n--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \\\n--nwk tree.nwk --log params.csv\n```\nTo see detailed options, run:\n```bash\ngenerate_bdei --help\n```\n\n\n#### BDSS and BDSS-PN\nThe following command simulates a tree with 200-500 tips under the BDSS model, \nwith \u03bb<sub>nn</sub>=0.1, \u03bb<sub>ns</sub>=0.3, \u03bb<sub>sn</sub>=0.5, \u03bb<sub>ss</sub>=1.5, \u03c8=0.25, p=0.5, \nand saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:\n```bash\ngenerate_bdss --min_tips 200 --max_tips 500 \\\n--la_nn 0.1 --la_ns 0.3 --la_sn 0.5 --la_ss 1.5 --psi 0.25 --p 0.5 \\\n--nwk tree.nwk --log params.csv\n```\nThe following command simulates a tree with 200-500 tips under the BDSS-PN model, \nwith \u03bb<sub>nn</sub>=0.1, \u03bb<sub>ns</sub>=0.3, \u03bb<sub>sn</sub>=0.5, \u03bb<sub>ss</sub>=1.5, \u03c8=0.25, p=0.5, \u03c6=2.5, \u03c5=0.2, \nand allowing to notify only the most recent partner of each sampled index case. \nThe simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:\n```bash\ngenerate_bdss --min_tips 200 --max_tips 500 \\\n--la_nn 0.1 --la_ns 0.3 --la_sn 0.5 --la_ss 1.5 --psi 0.25 --p 0.5 \\\n--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \\\n--nwk tree.nwk --log params.csv\n```\nTo see detailed options, run:\n```bash\ngenerate_bdss --help\n```\n\n#### User-defined MTBD and MTBD-PN models\nThe following command simulates a tree with 200-500 tips under a generic MTBD model, with two states A and B, \nwith \u03bc<sub>aa</sub>=0.5, \u03bc<sub>ab</sub>=0.6, \u03bc<sub>ba</sub>=0.7, \u03bc<sub>bb</sub>=0.8, \n\u03bb<sub>aa</sub>=0.1, \u03bb<sub>ab</sub>=0.2, \u03bb<sub>ba</sub>=0.3, \u03bb<sub>bb</sub>=0.4, \n\u03c8<sub>a</sub>=0.05, \u03c8<sub>b</sub>=0.08,\np=<sub>a</sub>0.15, p=<sub>b</sub>0.65,\nand saves it to the file tree.nwk, while saving the parameters to the comma-separated file params.csv:\n```bash\ngenerate_mtbd --min_tips 200 --max_tips 500 \\\n--states A B \\\n--transition_rates 0.5 0.6 0.7 0.8 \\\n--transmission_rates 0.1 0.2 0.3 0.4 \\\n--removal_rates 0.05 0.08 \\\n--sampling_probabilities 0.15 0.65 \\\n--nwk tree.nwk --log params.csv\n```\nThe following command simulates a tree with 200-500 tips under a generic MTBD model, with two states A and B, \nwith \u03bc<sub>aa</sub>=0.5, \u03bc<sub>ab</sub>=0.6, \u03bc<sub>ba</sub>=0.7, \u03bc<sub>bb</sub>=0.8, \n\u03bb<sub>aa</sub>=0.1, \u03bb<sub>ab</sub>=0.2, \u03bb<sub>ba</sub>=0.3, \u03bb<sub>bb</sub>=0.4, \n\u03c8<sub>a</sub>=0.05, \u03c8<sub>b</sub>=0.08,\np=<sub>a</sub>0.15, p=<sub>b</sub>0.65,\n\u03c6=2.5, \u03c5=0.2, \nand allowing to notify only the most recent partner of each sampled index case. \nThe simulated tree is saved to the file tree.nwk, while the model parameters are saved to the comma-separated file params.csv:\n```bash\ngenerate_mtbd --min_tips 200 --max_tips 500 \\\n--states A B \\\n--transition_rates 0.5 0.6 0.7 0.8 \\\n--transmission_rates 0.1 0.2 0.3 0.4 \\\n--removal_rates 0.05 0.08 \\\n--sampling_probabilities 0.15 0.65 \\\n--phi 2.5 --upsilon 0.2 --max_notified_partners 1 \\\n--nwk tree.nwk --log params.csv\n```\nTo see detailed options, run:\n```bash\ngenerate_mtbd --help\n```\n\n\n#### Basic usage in Python3\nTo simulate trees with 200-500 tips under the above models and settings:\n```python3\nfrom treesimulator.generator import generate\nfrom treesimulator import save_forest\nfrom treesimulator.mtbd_models import Model, BirthDeathModel, BirthDeathExposedInfectiousModel, \\\n BirthDeathWithSuperSpreadingModel, PNModel\n\n# BD and BD-PN\nbd_model = BirthDeathModel(p=0.5, la=0.5, psi=0.25)\nprint(bd_model.get_epidemiological_parameters())\n[bd_tree], _, _ = generate(bd_model, min_tips=200, max_tips=500)\nsave_forest([bd_tree], 'BD_tree.nwk')\nbdpn_model = PNModel(model=bd_model, upsilon=0.2, partner_removal_rate=2.5)\n[bdpn_tree], _, _ = generate(bdpn_model, min_tips=200, max_tips=500)\nsave_forest([bdpn_tree], 'BDPN_tree.nwk')\n\n# BDEI and BDEI-PN\nbdei_model = BirthDeathExposedInfectiousModel(p=0.5, mu=1, la=0.5, psi=0.25)\nprint(bdei_model.get_epidemiological_parameters())\n[bdei_tree], _, _ = generate(bdei_model, min_tips=200, max_tips=500)\nsave_forest([bdei_tree], 'BDEI_tree.nwk')\nbdeipn_model = PNModel(model=bdei_model, upsilon=0.2, partner_removal_rate=2.5)\n[bdeipn_tree], _, _ = generate(bdeipn_model, min_tips=200, max_tips=500)\nsave_forest([bdeipn_tree], 'BDEIPN_tree.nwk')\n\n# BDSS and BDSS-PN\nbdss_model = BirthDeathWithSuperSpreadingModel(p=0.5, la_nn=0.1, la_ns=0.3, la_sn=0.5, la_ss=1.5, psi=0.25)\nprint(bdss_model.get_epidemiological_parameters())\n[bdss_tree], _, _ = generate(bdss_model, min_tips=200, max_tips=500)\nsave_forest([bdss_tree], 'BDSS_tree.nwk')\nbdsspn_model = PNModel(model=bdss_model, upsilon=0.2, partner_removal_rate=2.5)\n[bdsspn_tree], _, _ = generate(bdsspn_model, min_tips=200, max_tips=500)\nsave_forest([bdsspn_tree], 'BDSSPN_tree.nwk')\n\n# MTBD and MTBD-PN\nmtbd_model = Model(states=['A', 'B'], transition_rates=[[0.5, 0.6], [0.7, 0.8]], \n transmission_rates=[[0.1, 0.2], [0.3, 0.4]],\n removal_rates=[0.05, 0.08], ps=[0.15, 0.65])\n[mtbd_tree], _, _ = generate(mtbd_model, min_tips=200, max_tips=500)\nsave_forest([mtbd_tree], 'MTBD_tree.nwk')\nmtbdpn_model = PNModel(model=mtbd_model, upsilon=0.2, partner_removal_rate=2.5)\n[mtbdpn_tree], _, _ = generate(mtbdpn_model, min_tips=200, max_tips=500)\nsave_forest([mtbdpn_tree], 'MTBDPN_tree.nwk')\n```\n\n### Run with apptainer\n\nOnce [apptainer](https://apptainer.org/docs/user/latest/quick_start.html#installation) is installed, \nrun the following command:\n\n```bash\napptainer run docker://evolbioinfo/treesimlator\n```\n\nThis will launch a terminal session within the container, \nin which you can run treesimulator following the instructions for the command line (\"Basic usage in a command line\") above.\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Simulation of rooted phylogenetic trees under a given Multitype Birth\u2013Death model.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/evolbioinfo/treesimulator"
},
"split_keywords": [
"phylogenetics",
" tree generator",
" multitype birth-death model"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b4f90f8a25f8806127e3c1a42e1f696a79ccf521fef006c9b2d542e4225ab51",
"md5": "7681239c5d497115b18b19b465d3407f",
"sha256": "1db6b02f949d1f46d4a1402da8e7f900e4f3ffaf3199ebe403f543bf7f28551b"
},
"downloads": -1,
"filename": "treesimulator-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7681239c5d497115b18b19b465d3407f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32973,
"upload_time": "2024-09-06T13:11:44",
"upload_time_iso_8601": "2024-09-06T13:11:44.985822Z",
"url": "https://files.pythonhosted.org/packages/3b/4f/90f8a25f8806127e3c1a42e1f696a79ccf521fef006c9b2d542e4225ab51/treesimulator-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce92433a8b91fe6975bb77c3ec8ea63a06ed77f5ff1367e6b1924de819130311",
"md5": "f30380de79a653579480c4c4008e6997",
"sha256": "599507b62cce4d8f77a850fc0f84d003d13530ec39960afdf1efcf356df16176"
},
"downloads": -1,
"filename": "treesimulator-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f30380de79a653579480c4c4008e6997",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31445,
"upload_time": "2024-09-06T13:11:46",
"upload_time_iso_8601": "2024-09-06T13:11:46.698665Z",
"url": "https://files.pythonhosted.org/packages/ce/92/433a8b91fe6975bb77c3ec8ea63a06ed77f5ff1367e6b1924de819130311/treesimulator-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-06 13:11:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evolbioinfo",
"github_project": "treesimulator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "treesimulator"
}
JSON
