# 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]](https://royalsocietypublishing.org/doi/10.1098/rstb.2012.0198).
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)).
## BD
3 parameters:
* λ -- transmission rate
* ψ -- removal rate
* p -- sampling probability upon removal
Epidemiological parameters:
* R<sub>0</sub>=λ/ψ -- 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<sub>0</sub>=λ/ψ -- reproduction number
* 1/ψ -- infectious time
* 1/μ -- incubation period
## 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
## Installation
To install treesimulator:
```bash
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:
```bash
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:
```bash
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:
```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
```
To seee detailed options, run:
```bash
generate_bdei --help
```
## BDSS
The following command simulates a tree with 200-500 tips under 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 a file tree.nwk, while saving the parameters to a 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
```
To seee detailed options, run:
```bash
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 μ<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 a file tree.nwk, while saving the parameters to a comma-separated file params.csv:
```bash
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:
```bash
generate_mtbd --help
```
### Python3
To simulate trees with 200-500 tips under the above models and settings:
```python
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')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/evolbioinfo/treesimulator",
"name": "treesimulator",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "phylogenetics,tree generator,multitype birth-death model",
"author": "Anna Zhukova",
"author_email": "anna.zhukova@pasteur.fr",
"download_url": "https://files.pythonhosted.org/packages/3e/a8/dbf18ea8253035f804c10f5930febdc9619f21f684b203f89d6e2286992c/treesimulator-0.1.9.tar.gz",
"platform": null,
"description": "# treesimulator\n\nSimulation of rooted phylogenetic trees under a given Multitype Birth\u2013Death (MTBD) model.\nThe MTBD models were introduced by Stadler & Bonhoeffer [[_Philos. Trans. R. Soc. B_ 2013]](https://royalsocietypublishing.org/doi/10.1098/rstb.2012.0198).\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)). \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## BDEI\n2 compartments: \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## 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\n\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## Installation\nTo install treesimulator:\n```bash\npip3 install treesimulator\n```\n\n## Usage\n### Command line \n\n## BD\nThe following command simulates a tree with 200-500 tips under BD model, with \u03bb=0.5, \u03c8=0.25, p=0.5, \nand saves it to a file tree.nwk, while saving the parameters to a comma-separated file params.csv:\n```bash\ngenerate_bd --min_tips 200 --max_tips 500 --la 0.5 --psi 0.25 --p 0.5 --nwk tree.nwk --log params.csv\n```\nTo seee detailed options, run:\n```bash\ngenerate_bd --help\n```\n\n## BDEI\nThe following command simulates a tree with 200-500 tips under BDEI model, with \u03bc=1, \u03bb=0.5, \u03c8=0.25, p=0.5, \nand saves it to a file tree.nwk, while saving the parameters to a comma-separated file params.csv:\n```bash\ngenerate_bdei --min_tips 200 --max_tips 500 --mu 1 --la 0.5 --psi 0.25 --p 0.5 --nwk tree.nwk --log params.csv\n```\nTo seee detailed options, run:\n```bash\ngenerate_bdei --help\n```\n\n\n## BDSS\nThe following command simulates a tree with 200-500 tips under 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 a file tree.nwk, while saving the parameters to a comma-separated file params.csv:\n```bash\ngenerate_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\n```\nTo seee detailed options, run:\n```bash\ngenerate_bdss --help\n```\n\n## User-defined MTBD model\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 a file tree.nwk, while saving the parameters to a comma-separated file params.csv:\n```bash\ngenerate_mtbd --min_tips 200 --max_tips 500 --nwk tree.nwk --log params.csv \\\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```\nTo seee detailed options, run:\n```bash\ngenerate_mtbd --help\n```\n\n\n### Python3\nTo simulate trees with 200-500 tips under the above models and settings:\n```python\nfrom treesimulator.generator import generate\nfrom treesimulator import save_forest\nfrom treesimulator.mtbd_models import Model, BirthDeathModel, BirthDeathExposedInfectiousModel, BirthDeathWithSuperSpreadingModel\n\nbd_model = BirthDeathModel(p=0.5, la=0.5, psi=0.25)\nprint(bd_model.get_epidemiological_parameters())\n[bd_tree], (bd_total_tips, _, bd_total_time) = generate(bd_model, min_tips=200, max_tips=500)\nsave_forest([bd_tree], 'BD_tree.nwk')\n\nbdei_model = BirthDeathExposedInfectiousModel(p=0.5, mu=1, la=0.5, psi=0.25)\nprint(bdei_model.get_epidemiological_parameters())\n[bdei_tree], (bdei_total_tips, _, bdei_total_time) = generate(bdei_model, min_tips=200, max_tips=500)\nsave_forest([bdei_tree], 'BDEI_tree.nwk')\n\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], (bdss_total_tips, _, bdss_total_time) = generate(bdss_model, min_tips=200, max_tips=500)\nsave_forest([bdss_tree], 'BDSS_tree.nwk')\n\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], (mtbd_total_tips, _, mtbd_total_time) = generate(mtbd_model, min_tips=200, max_tips=500)\nsave_forest([mtbd_tree], 'MTBD_tree.nwk')\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Simulation of rooted phylogenetic trees under a given Multitype Birth\u2013Death model.",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/evolbioinfo/treesimulator"
},
"split_keywords": [
"phylogenetics",
"tree generator",
"multitype birth-death model"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "460dbb9fe97da4ffbe539c303383861f65e739d5bb1737ffe1b26aaadd19993b",
"md5": "b68ebefb5b4083c00bf972cb0c986166",
"sha256": "3af5e4f88a56c5a3fc2705219fa6cf62c3eb589833ba65e934128fee7e467b9c"
},
"downloads": -1,
"filename": "treesimulator-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b68ebefb5b4083c00bf972cb0c986166",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 30760,
"upload_time": "2024-01-15T13:16:34",
"upload_time_iso_8601": "2024-01-15T13:16:34.047135Z",
"url": "https://files.pythonhosted.org/packages/46/0d/bb9fe97da4ffbe539c303383861f65e739d5bb1737ffe1b26aaadd19993b/treesimulator-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ea8dbf18ea8253035f804c10f5930febdc9619f21f684b203f89d6e2286992c",
"md5": "8c5a53216a2410560f28514d8061dd37",
"sha256": "38e29e0b1c2f896e09f3ebecf0798c5f4eec9b442bb87a17c1e435673990c97d"
},
"downloads": -1,
"filename": "treesimulator-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "8c5a53216a2410560f28514d8061dd37",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27387,
"upload_time": "2024-01-15T13:16:35",
"upload_time_iso_8601": "2024-01-15T13:16:35.346574Z",
"url": "https://files.pythonhosted.org/packages/3e/a8/dbf18ea8253035f804c10f5930febdc9619f21f684b203f89d6e2286992c/treesimulator-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-15 13:16:35",
"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
