# bdpn
Estimator of BD-PN model parameters from phylogenetic trees and a non-parametric PN detection test.
[//]: # ([](https://doi.org/10.1093/sysbio/syad059))
[//]: # ([](https://github.com/evolbioinfo/bdpn/releases))
[](https://pypi.org/project/bdpn/)
[](https://pypi.org/project/bdpn/)
[](https://hub.docker.com/r/evolbioinfo/bdpn/tags)
## BD-PN model
BD-PN model extends the classical birth-death (BD) model with incomplete sampling [[Stadler 2009]](https://pubmed.ncbi.nlm.nih.gov/19631666/), by adding partner notification (PN).
Under this model, infected individuals can transmit their pathogen with a constant rate λ,
get removed (become non-infectious) with a constant rate ψ,
and their pathogen can be sampled upon removal
with a constant probability ρ. On top of that, in the BD-PN model,
at the moment of sampling the sampled individual
might notify their most recent partner with a constant probability υ.
Upon notification, the partner is removed almost instantaneously (modeled via a constant notified
removal rate φ >> ψ) and their pathogen is sampled.
BD-PN model therefore has 5 parameters:
* λ -- transmission rate
* ψ -- removal rate
* ρ -- sampling probability upon removal
* υ -- probability to notify the last partner upon sampling
* φ -- removal (and sampling) rate after notification
These parameters can be expressed in terms of the following epidemiological parameters:
* R<sub>0</sub>=λ/ψ -- reproduction number
* 1/ψ -- infectious time
* 1/φ -- partner removal time
BD-PN model makes 3 assumptions:
1. only observed individuals can notify (instead of any removed individual);
2. notified individuals are always observed upon removal;
3. only the most recent partner can get notified.
For identifiability, BD-PN model requires one of the three BD model parameters (λ, ψ, ρ) to be fixed.
## BD-PN parameter estimator
The bdpn package provides a classical BD and a BD-PN model maximum-likelihood parameter estimator
from a user-supplied time-scaled phylogenetic tree.
User must also provide a value for one of the three BD model parameters (λ, ψ, or ρ).
We recommend providing the sampling probability ρ,
which could be estimated as the number of tree tips divided by the number of declared cases for the same time period.
## PN test
The bdpn package provides a non-parametric test detecting presence/absence of partner notification in a user-supplied time-scaled phylogenetic tree.
It outputs a p-value.
## Input data
One needs to supply a time-scaled phylogenetic tree in newick format.
In the examples below we will use an HIV tree reconstructed from 200 sequences,
published in [[Rasmussen _et al._ PLoS Comput. Biol. 2017]](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005448),
which you can find at [PairTree GitHub](https://github.com/davidrasm/PairTree)
and in [hiv_zurich/Zurich.nwk](hiv_zurich/Zurich.nwk).
## Installation
There are 4 alternative ways to run __bdpn__ 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).
### Run in python3 or command-line (for linux systems, recommended Ubuntu 21 or newer versions)
You could either install python (version 3.9 or higher) system-wide and then install bdpn via pip:
```bash
sudo apt install -y python3 python3-pip python3-setuptools python3-distutils
pip3 install bdpn
```
or alternatively, you could install python (version 3.9 or higher) and bdpn via [conda](https://conda.io/docs/) (make sure that conda is installed first).
Here we will create a conda environment called _bdpnenv_:
```bash
conda create --name bdpnenv python=3.9
conda activate bdpnenv
pip install bdpn
```
#### Basic usage in a command line
If you installed __bdpn__ in a conda environment (here named _bdpnenv_), do not forget to first activate it, e.g.
```bash
conda activate bdpnenv
```
Run the following commands to check for the presence of partner notification and estimate BD-PN model parameters.
The first command applies the PN test to a tree Zurich.nwk and saves the PN-test value to the file cherry_test.txt
The second command estimated the BD-PN parameters and their 95% CIs for this tree, assuming the sampling probability of 0.25,
and saves the estimated parameters to a comma-separated file estimates_bdpn.csv.
The third command estimated the classical BD parameters and their 95% CIs for this tree, assuming the sampling probability of 0.25,
and saves the estimated parameters to a comma-separated file estimates_bd.csv.
```bash
pn_test --nwk Zurich.nwk --log cherry_test.txt
bdpn_infer --nwk Zurich.nwk --ci --p 0.25 --log estimates_bdpn.csv
bd_infer --nwk Zurich.nwk --ci --p 0.25 --log estimates_bd.csv
```
#### Help
To see detailed options, run:
```bash
pn_test --help
bdpn_infer --help
bd_infer --help
```
### Run with docker
#### Basic usage
Once [docker](https://www.docker.com/community-edition) is installed,
run the following command to estimate BD-PN model parameters:
```bash
docker run -v <path_to_the_folder_containing_the_tree>:/data:rw -t evolbioinfo/bdpn --nwk /data/Zurich.nwk --ci --p 0.25 --log /data/estimates.csv
```
This will produce a comma-separated file estimates.csv in the <path_to_the_folder_containing_the_tree> folder,
containing the estimated parameter values and their 95% CIs (can be viewed with a text editor, Excel or Libre Office Calc).
#### Help
To see advanced options, run
```bash
docker run -t evolbioinfo/bdpn -h
```
### Run with apptainer
#### Basic usage
Once [apptainer](https://apptainer.org/docs/user/latest/quick_start.html#installation) is installed,
run the following command to estimate BD-PN model parameters (from the folder where the Zurich.nwk tree is contained):
```bash
apptainer run docker://evolbioinfo/bdpn --nwk Zurich.nwk --ci --p 0.25 --log estimates.csv
```
This will produce a comma-separated file estimates.csv,
containing the estimated parameter values and their 95% CIs (can be viewed with a text editor, Excel or Libre Office Calc).
#### Help
To see advanced options, run
```bash
apptainer run docker://evolbioinfo/bdpn -h
```
Raw data
{
"_id": null,
"home_page": "https://github.com/evolbioinfo/bdpn",
"name": "bdext",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "phylogenetics, birth-death model, partner notification, contact tracing",
"author": "Anna Zhukova",
"author_email": "anna.zhukova@pasteur.fr",
"download_url": "https://files.pythonhosted.org/packages/94/a3/c13491ecb000df2c2fa3f9d6f0d2f8308fba8d9927871d1ea1e373b1e16e/bdext-0.1.16.tar.gz",
"platform": null,
"description": "# bdpn\n\nEstimator of BD-PN model parameters from phylogenetic trees and a non-parametric PN detection test. \n\n\n\n[//]: # ([](https://doi.org/10.1093/sysbio/syad059))\n[//]: # ([](https://github.com/evolbioinfo/bdpn/releases))\n[](https://pypi.org/project/bdpn/)\n[](https://pypi.org/project/bdpn/)\n[](https://hub.docker.com/r/evolbioinfo/bdpn/tags)\n\n## BD-PN model\n\nBD-PN model extends the classical birth-death (BD) model with incomplete sampling [[Stadler 2009]](https://pubmed.ncbi.nlm.nih.gov/19631666/), by adding partner notification (PN).\nUnder this model, infected individuals can transmit their pathogen with a constant rate \u03bb, \nget removed (become non-infectious) with a constant rate \u03c8, \nand their pathogen can be sampled upon removal \nwith a constant probability \u03c1. On top of that, in the BD-PN model, \nat the moment of sampling the sampled individual \nmight notify their most recent partner with a constant probability \u03c5. \nUpon notification, the partner is removed almost instantaneously (modeled via a constant notified\nremoval rate \u03c6 >> \u03c8) and their pathogen is sampled.\n\nBD-PN model therefore has 5 parameters:\n* \u03bb -- transmission rate\n* \u03c8 -- removal rate\n* \u03c1 -- sampling probability upon removal\n* \u03c5 -- probability to notify the last partner upon sampling\n* \u03c6 -- removal (and sampling) rate after notification\n\nThese parameters can be expressed in terms of the following epidemiological parameters:\n* R<sub>0</sub>=\u03bb/\u03c8 -- reproduction number\n* 1/\u03c8 -- infectious time\n* 1/\u03c6 -- partner removal time\n\nBD-PN model makes 3 assumptions:\n1. only observed individuals can notify (instead of any removed individual);\n2. notified individuals are always observed upon removal;\n3. only the most recent partner can get notified.\n\nFor identifiability, BD-PN model requires one of the three BD model parameters (\u03bb, \u03c8, \u03c1) to be fixed.\n\n## BD-PN parameter estimator\n\nThe bdpn package provides a classical BD and a BD-PN model maximum-likelihood parameter estimator \nfrom a user-supplied time-scaled phylogenetic tree. \nUser must also provide a value for one of the three BD model parameters (\u03bb, \u03c8, or \u03c1). \nWe recommend providing the sampling probability \u03c1, \nwhich could be estimated as the number of tree tips divided by the number of declared cases for the same time period.\n\n## PN test\n\nThe bdpn package provides a non-parametric test detecting presence/absence of partner notification in a user-supplied time-scaled phylogenetic tree. \nIt outputs a p-value. \n\n## Input data\nOne needs to supply a time-scaled phylogenetic tree in newick format. \nIn the examples below we will use an HIV tree reconstructed from 200 sequences, \npublished in [[Rasmussen _et al._ PLoS Comput. Biol. 2017]](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005448), \nwhich you can find at [PairTree GitHub](https://github.com/davidrasm/PairTree) \nand in [hiv_zurich/Zurich.nwk](hiv_zurich/Zurich.nwk). \n\n## Installation\n\nThere are 4 alternative ways to run __bdpn__ 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\n### Run in python3 or command-line (for linux systems, recommended Ubuntu 21 or newer versions)\n\nYou could either install python (version 3.9 or higher) system-wide and then install bdpn via pip:\n```bash\nsudo apt install -y python3 python3-pip python3-setuptools python3-distutils\npip3 install bdpn\n```\n\nor alternatively, you could install python (version 3.9 or higher) and bdpn via [conda](https://conda.io/docs/) (make sure that conda is installed first). \nHere we will create a conda environment called _bdpnenv_:\n```bash\nconda create --name bdpnenv python=3.9\nconda activate bdpnenv\npip install bdpn\n```\n\n\n#### Basic usage in a command line\nIf you installed __bdpn__ in a conda environment (here named _bdpnenv_), do not forget to first activate it, e.g.\n\n```bash\nconda activate bdpnenv\n```\n\nRun the following commands to check for the presence of partner notification and estimate BD-PN model parameters.\nThe first command applies the PN test to a tree Zurich.nwk and saves the PN-test value to the file cherry_test.txt\nThe second command estimated the BD-PN parameters and their 95% CIs for this tree, assuming the sampling probability of 0.25, \nand saves the estimated parameters to a comma-separated file estimates_bdpn.csv.\nThe third command estimated the classical BD parameters and their 95% CIs for this tree, assuming the sampling probability of 0.25, \nand saves the estimated parameters to a comma-separated file estimates_bd.csv.\n```bash\npn_test --nwk Zurich.nwk --log cherry_test.txt\nbdpn_infer --nwk Zurich.nwk --ci --p 0.25 --log estimates_bdpn.csv\nbd_infer --nwk Zurich.nwk --ci --p 0.25 --log estimates_bd.csv\n```\n\n#### Help\n\nTo see detailed options, run:\n```bash\npn_test --help\nbdpn_infer --help\nbd_infer --help\n```\n\n\n### Run with docker\n\n#### Basic usage\nOnce [docker](https://www.docker.com/community-edition) is installed, \nrun the following command to estimate BD-PN model parameters:\n```bash\ndocker run -v <path_to_the_folder_containing_the_tree>:/data:rw -t evolbioinfo/bdpn --nwk /data/Zurich.nwk --ci --p 0.25 --log /data/estimates.csv\n```\n\nThis will produce a comma-separated file estimates.csv in the <path_to_the_folder_containing_the_tree> folder,\n containing the estimated parameter values and their 95% 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/bdpn -h\n```\n\n\n\n### Run with apptainer\n\n#### Basic usage\nOnce [apptainer](https://apptainer.org/docs/user/latest/quick_start.html#installation) is installed, \nrun the following command to estimate BD-PN model parameters (from the folder where the Zurich.nwk tree is contained):\n\n```bash\napptainer run docker://evolbioinfo/bdpn --nwk Zurich.nwk --ci --p 0.25 --log estimates.csv\n```\n\nThis will produce a comma-separated file estimates.csv,\n containing the estimated parameter values and their 95% 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\napptainer run docker://evolbioinfo/bdpn -h\n```\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Estimation of BDPN parameters from phylogenetic trees.",
"version": "0.1.16",
"project_urls": {
"Homepage": "https://github.com/evolbioinfo/bdpn"
},
"split_keywords": [
"phylogenetics",
" birth-death model",
" partner notification",
" contact tracing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1350610ee7fd26af9f2897118c50b4fe07c5d43b09cea407c1f2d01fd7b900ba",
"md5": "aac3ffc2f2c873c56cdd656ce51ed54b",
"sha256": "65750572481ac24da639beb7ad01af93747fcf011d6d0791695059baecea233c"
},
"downloads": -1,
"filename": "bdext-0.1.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aac3ffc2f2c873c56cdd656ce51ed54b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 48424,
"upload_time": "2024-12-17T15:07:08",
"upload_time_iso_8601": "2024-12-17T15:07:08.702424Z",
"url": "https://files.pythonhosted.org/packages/13/50/610ee7fd26af9f2897118c50b4fe07c5d43b09cea407c1f2d01fd7b900ba/bdext-0.1.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94a3c13491ecb000df2c2fa3f9d6f0d2f8308fba8d9927871d1ea1e373b1e16e",
"md5": "de02f28c1237d33137bccb9e555a5b81",
"sha256": "a8c345f86cc57e67f7648056927ab085629dc49761e2308d90e31d37de25ffcb"
},
"downloads": -1,
"filename": "bdext-0.1.16.tar.gz",
"has_sig": false,
"md5_digest": "de02f28c1237d33137bccb9e555a5b81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 41014,
"upload_time": "2024-12-17T15:07:11",
"upload_time_iso_8601": "2024-12-17T15:07:11.388318Z",
"url": "https://files.pythonhosted.org/packages/94/a3/c13491ecb000df2c2fa3f9d6f0d2f8308fba8d9927871d1ea1e373b1e16e/bdext-0.1.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 15:07:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evolbioinfo",
"github_project": "bdpn",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bdext"
}
JSON
