# PyBDEI
Tools for fast and accurate maximum likelihood estimation
of Birth-Death Exposed-Infectious (BDEI) epidemiological
model parameters from phylogenetic trees.
The birth-death exposed-infectious (BDEI) model [[Stadler _et al._ 2014]](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4205153/)
describes the transmission of pathogens
that feature an incubation period (when the host is already infected but not yet infectious),
for example Ebola or SARS-CoV-2. In a phylodynamics framework, it allows to infer such epidemiological
parameters as the basic reproduction number R<sub>0</sub>, incubation period and infectious time
from a phylogenetic tree (a genealogy of pathogen sequences).
This implementation of the BDEI model solves the computational bottlenecks (due to high complexity of differential equations used in phylodynamics models,
previous implementations [[Stadler and Bonhoeffer 2013](https://royalsocietypublishing.org/doi/10.1098/rstb.2012.0198) and [Barido-Sottani _et al._ 2018](https://doi.org/10.1101/440982) ] sometimes suffered from numerical instability and were only applicable to medium datasets of <500 samples).
Our fast and accurate estimator is applicable to very large datasets (10, 000 samples) allowing phylodynamics to
catch up with pathogen sequencing efforts.
[](https://doi.org/10.1093/sysbio/syad059)
[](https://github.com/evolbioinfo/bdei/releases)
[](https://pypi.org/project/pybdei/)
[](https://pypi.org/project/pybdei/)
[](https://hub.docker.com/r/evolbioinfo/bdei/tags)
#### Article
A Zhukova, F Hecht, Y Maday, and O Gascuel. *Fast and Accurate Maximum-Likelihood Estimation of Multi-Type Birth-Death Epidemiological Models from Phylogenetic Trees* Syst Biol. 2023 Sep 13:syad059. doi: [10.1093/sysbio/syad059](https://doi.org/10.1093/sysbio/syad059)
# Input data
As an input, one needs to provide a **rooted** phylogenetical tree in [newick](https://en.wikipedia.org/wiki/Newick_format) format,
and the value of one of the model parameters (for identifiability):
* µ – becoming infectious rate corresponding to a state transition from E (exposed) to I (infectious)
_(can be fixed via the --mu argument)_,
* λ – transmission rate, from a transmitter in the state I to a newly infected recipient, whose state is E
_(can be fixed via the --la argument)_,
* ψ – removal rate, corresponding to individuals in the state I exiting the study
(e.g. due to healing, death or starting a treatment) _(can be fixed via the --psi argument)_,
* ρ – sampling probability (upon removal) _(can be fixed via the --p argument)_.
# Installation
There are 4 alternative ways to run __PyBDEI__ on your computer:
with [docker](https://www.docker.com/community-edition),
[singularity](https://www.sylabs.io/singularity),
in Python3 (only on linux systems), or via command line (only on linux systems, requires installation with Python3).
## Run with docker
### Basic usage
Once [docker](https://www.docker.com/community-edition) is installed, run the following command
(here we assume that the sampling probability value is known and fixed to 0.3):
```bash
docker run -v <path_to_the_folder_containing_the_tree>:/data:rw -t evolbioinfo/bdei --nwk /data/<tree_file.nwk> --p 0.3 --CI_repetitions 100 --log <file_to_store_the_estimated_parameters.tab>
```
This will produce a file <file_to_store_the_estimated_parameters.tab> in the <path_to_the_folder_containing_the_tree> folder,
containing a tab-separated table with the estimated parameter values and their CIs (can be viewed with a text editor, Excel or Libre Office Calc).
#### Help
To see advanced options, run
```bash
docker run -t evolbioinfo/bdei -h
```
## Run with singularity
### Basic usage
Once [singularity](https://www.sylabs.io/guides/2.6/user-guide/quick_start.html#quick-installation-steps) is installed,
run the following command
(here we assume that the sampling probability value is known and fixed to 0.3):
```bash
singularity run docker://evolbioinfo/bdei --nwk <path/to/tree_file.nwk> --p 0.3 --CI_repetitions 100 --log <path/to/file_to_store_the_estimated_parameters.tab>
```
This will produce a file <path/to/file_to_store_the_estimated_parameters.tab>,
containing a tab-separated table with the estimated parameter values and their CIs (can be viewed with a text editor, Excel or Libre Office Calc).
#### Help
To see advanced options, run
```bash
singularity run docker://evolbioinfo/bdei -h
```
## Run in python3 or command-line (for linux systems, recommended Ubuntu 21 or newer versions)
### 1. Install the C++ dependencies
You would need to install g++ and [NLOpt](https://nlopt.readthedocs.io/en/latest/) C++ libraries:
```bash
sudo apt update --fix-missing
sudo apt install -y g++ libnlopt-cxx-dev
```
### 2. Install python 3
You could either install python (version 3.9 or higher) system-wide:
```bash
sudo apt install -y python3 python3-pip python3-setuptools python3-distutils
```
or alternatively, you could install python (version 3.9 or higher) via [conda](https://conda.io/docs/) (make sure that conda is installed first).
Here we will create a conda environment called _pybdeienv_:
```bash
conda create --name pybdeienv python=3.9
conda activate pybdeienv
pip3 install setuptools
```
### 3. Install numpy and PyBDEI
```bash
pip3 install numpy
pip3 install pybdei
```
### Basic usage in a command line
If you installed __PyBDEI__ via conda, do not forget to first activate the dedicated environment (here named _pybdeienv_), e.g.
```bash
conda activate pybdeienv
```
To run __PyBDEI__
(here we assume that the sampling probability value is known and fixed to 0.3):
```bash
bdei_infer --nwk <path/to/tree_file.nwk> --p 0.3 --CI_repetitions 100 --log <path/to/file_to_store_the_estimated_parameters.tab>
```
This will produce a file <path/to/file_to_store_the_estimated_parameters.tab>,
containing a tab-separated table with the estimated parameter values and their CIs (can be viewed with a text editor, Excel or Libre Office Calc).
#### Help
To see advanced options, run:
```bash
bdei_infer -h
```
### Basic usage in python3
```python
from pybdei import infer
# Path to the tree in newick format
tree = "tree.nwk"
result, time = infer(nwk=tree, p=0.3, CI_repetitions=100)
print('Inferred transition rate is', result.mu, result.mu_CI)
print('Inferred transmission rate is', result.la, result.la_CI)
print('Inferred removal rate is', result.psi, result.psi_CI)
print('Inferred reproductive number is', result.R_naught)
print('Inferred incubation period is', result.incubation_period)
print('Inferred infectious time is', result.infectious_time)
print('Converged in', time.CPU_time, 's and', time.iterations, 'iterations')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/evolbioinfo/BDEI",
"name": "pybdei",
"maintainer": "Anna Zhukova",
"docs_url": null,
"requires_python": null,
"maintainer_email": "anna.zhukova@pasteur.fr",
"keywords": "BDEI, phylodynamics, epidemiological parameters",
"author": "Fr\u00e9d\u00e9ric Heicht",
"author_email": "frederic.hecht@sorbonne-universite.fr",
"download_url": "https://files.pythonhosted.org/packages/97/e1/e230d11f2558ab7a3e712de5fff24faf559d568cb0a106dd631d350954fd/pybdei-0.13.tar.gz",
"platform": null,
"description": "# PyBDEI\n\nTools for fast and accurate maximum likelihood estimation\nof Birth-Death Exposed-Infectious (BDEI) epidemiological\nmodel parameters from phylogenetic trees.\n\nThe birth-death exposed-infectious (BDEI) model [[Stadler _et al._ 2014]](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4205153/) \ndescribes the transmission of pathogens \nthat feature an incubation period (when the host is already infected but not yet infectious), \nfor example Ebola or SARS-CoV-2. In a phylodynamics framework, it allows to infer such epidemiological\nparameters as the basic reproduction number R<sub>0</sub>, incubation period and infectious time \nfrom a phylogenetic tree (a genealogy of pathogen sequences). \n\nThis implementation of the BDEI model solves the computational bottlenecks (due to high complexity of differential equations used in phylodynamics models,\nprevious implementations [[Stadler and Bonhoeffer 2013](https://royalsocietypublishing.org/doi/10.1098/rstb.2012.0198) and [Barido-Sottani _et al._ 2018](https://doi.org/10.1101/440982) ] sometimes suffered from numerical instability and were only applicable to medium datasets of <500 samples). \nOur fast and accurate estimator is applicable to very large datasets (10, 000 samples) allowing phylodynamics to\ncatch up with pathogen sequencing efforts.\n\n\n\n[](https://doi.org/10.1093/sysbio/syad059)\n[](https://github.com/evolbioinfo/bdei/releases)\n[](https://pypi.org/project/pybdei/)\n[](https://pypi.org/project/pybdei/)\n[](https://hub.docker.com/r/evolbioinfo/bdei/tags)\n\n\n#### Article\n\nA Zhukova, F Hecht, Y Maday, and O Gascuel. *Fast and Accurate Maximum-Likelihood Estimation of Multi-Type Birth-Death Epidemiological Models from Phylogenetic Trees* Syst Biol. 2023 Sep 13:syad059. doi: [10.1093/sysbio/syad059](https://doi.org/10.1093/sysbio/syad059)\n\n# Input data\nAs an input, one needs to provide a **rooted** phylogenetical tree in [newick](https://en.wikipedia.org/wiki/Newick_format) format,\nand the value of one of the model parameters (for identifiability):\n* \u00b5 \u2013 becoming infectious rate corresponding to a state transition from E (exposed) to I (infectious) \n_(can be fixed via the --mu argument)_,\n* \u03bb \u2013 transmission rate, from a transmitter in the state I to a newly infected recipient, whose state is E \n_(can be fixed via the --la argument)_,\n* \u03c8 \u2013 removal rate, corresponding to individuals in the state I exiting the study \n(e.g. due to healing, death or starting a treatment) _(can be fixed via the --psi argument)_,\n* \u03c1 \u2013 sampling probability (upon removal) _(can be fixed via the --p argument)_.\n\n\n# Installation\n\nThere are 4 alternative ways to run __PyBDEI__ on your computer: \nwith [docker](https://www.docker.com/community-edition), \n[singularity](https://www.sylabs.io/singularity),\nin Python3 (only on linux systems), or via command line (only on linux systems, requires installation with Python3).\n\n\n## Run with docker\n\n### Basic usage\nOnce [docker](https://www.docker.com/community-edition) is installed, run the following command \n(here we assume that the sampling probability value is known and fixed to 0.3):\n\n```bash\ndocker run -v <path_to_the_folder_containing_the_tree>:/data:rw -t evolbioinfo/bdei --nwk /data/<tree_file.nwk> --p 0.3 --CI_repetitions 100 --log <file_to_store_the_estimated_parameters.tab>\n```\n\nThis will produce a file <file_to_store_the_estimated_parameters.tab> in the <path_to_the_folder_containing_the_tree> folder,\n containing a tab-separated table with the estimated parameter values and their CIs (can be viewed with a text editor, Excel or Libre Office Calc).\n\n#### Help\n\nTo see advanced options, run\n```bash\ndocker run -t evolbioinfo/bdei -h\n```\n\n## Run with singularity\n\n### Basic usage\nOnce [singularity](https://www.sylabs.io/guides/2.6/user-guide/quick_start.html#quick-installation-steps) is installed, \nrun the following command \n(here we assume that the sampling probability value is known and fixed to 0.3):\n\n```bash\nsingularity run docker://evolbioinfo/bdei --nwk <path/to/tree_file.nwk> --p 0.3 --CI_repetitions 100 --log <path/to/file_to_store_the_estimated_parameters.tab>\n```\n\nThis will produce a file <path/to/file_to_store_the_estimated_parameters.tab>,\n containing a tab-separated table with the estimated parameter values and their CIs (can be viewed with a text editor, Excel or Libre Office Calc).\n\n\n#### Help\n\nTo see advanced options, run\n```bash\nsingularity run docker://evolbioinfo/bdei -h\n```\n\n## Run in python3 or command-line (for linux systems, recommended Ubuntu 21 or newer versions)\n\n### 1. Install the C++ dependencies\nYou would need to install g++ and [NLOpt](https://nlopt.readthedocs.io/en/latest/) C++ libraries:\n\n```bash\nsudo apt update --fix-missing \nsudo apt install -y g++ libnlopt-cxx-dev\n```\n\n### 2. Install python 3\n\nYou could either install python (version 3.9 or higher) system-wide:\n```bash\nsudo apt install -y python3 python3-pip python3-setuptools python3-distutils\n```\n\nor alternatively, you could install python (version 3.9 or higher) via [conda](https://conda.io/docs/) (make sure that conda is installed first). \nHere we will create a conda environment called _pybdeienv_:\n```bash\nconda create --name pybdeienv python=3.9\nconda activate pybdeienv\npip3 install setuptools\n```\n\n### 3. Install numpy and PyBDEI\n```bash\npip3 install numpy \npip3 install pybdei\n```\n\n\n### Basic usage in a command line\nIf you installed __PyBDEI__ via conda, do not forget to first activate the dedicated environment (here named _pybdeienv_), e.g.\n\n```bash\nconda activate pybdeienv\n```\n\nTo run __PyBDEI__\n(here we assume that the sampling probability value is known and fixed to 0.3):\n\n```bash\nbdei_infer --nwk <path/to/tree_file.nwk> --p 0.3 --CI_repetitions 100 --log <path/to/file_to_store_the_estimated_parameters.tab>\n```\n\nThis will produce a file <path/to/file_to_store_the_estimated_parameters.tab>,\n containing a tab-separated table with the estimated parameter values and their CIs (can be viewed with a text editor, Excel or Libre Office Calc).\n\n#### Help\n\nTo see advanced options, run:\n```bash\nbdei_infer -h\n```\n\n### Basic usage in python3\n\n```python\nfrom pybdei import infer\n# Path to the tree in newick format\ntree = \"tree.nwk\"\nresult, time = infer(nwk=tree, p=0.3, CI_repetitions=100)\nprint('Inferred transition rate is', result.mu, result.mu_CI)\nprint('Inferred transmission rate is', result.la, result.la_CI)\nprint('Inferred removal rate is', result.psi, result.psi_CI)\nprint('Inferred reproductive number is', result.R_naught)\nprint('Inferred incubation period is', result.incubation_period)\nprint('Inferred infectious time is', result.infectious_time)\nprint('Converged in', time.CPU_time, 's and', time.iterations, 'iterations')\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Fast and accurate epidemiological parameter estimation from phylogenetic trees with the Birth-Death Exposed-Infectious (BDEI) model.",
"version": "0.13",
"project_urls": {
"Download": "https://github.com/evolbioinfo/BDEI",
"Homepage": "https://github.com/evolbioinfo/BDEI"
},
"split_keywords": [
"bdei",
" phylodynamics",
" epidemiological parameters"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97e1e230d11f2558ab7a3e712de5fff24faf559d568cb0a106dd631d350954fd",
"md5": "8a4368be141d009236e220131a0f3e3e",
"sha256": "4fcd3950aa60a25538bb8716a88ed5d5b24f63b1deebf1828e2e0ea9ac45441f"
},
"downloads": -1,
"filename": "pybdei-0.13.tar.gz",
"has_sig": false,
"md5_digest": "8a4368be141d009236e220131a0f3e3e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 41091,
"upload_time": "2024-08-06T14:23:29",
"upload_time_iso_8601": "2024-08-06T14:23:29.935068Z",
"url": "https://files.pythonhosted.org/packages/97/e1/e230d11f2558ab7a3e712de5fff24faf559d568cb0a106dd631d350954fd/pybdei-0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-06 14:23:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evolbioinfo",
"github_project": "BDEI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pybdei"
}
JSON
