# PhyloDeep
PhyloDeep is a python library for parameter estimation and model selection from phylogenetic trees, based on deep learning.
## Article
Voznica J, Zhukova A, Boskova V, Saulnier E, Lemoine F, Moslonka-Lefebvre M, Gascuel O.
__Deep learning from phylogenies to uncover the transmission dynamics of epidemics__. [Nat Commun 13, 3.86 (2022)](https://www.nature.com/articles/s41467-022-31511-0)
## Installation
The installation time of the package can be up to several minutes, including downloading dependencies. The run time
should be a couple of seconds. The package was tested in Linux (Ubuntu 18.08), Windows 10 and MacOS.
### Windows
For **Windows** users, we recommend installing __phylodeep__ via [Cygwin environment](https://www.cygwin.com/).
First install Python>=3.8 and pip3 from the Cygwin packages. Then install __phylodeep__:
```bash
pip3 install phylodeep
```
### All other platforms
You can install __phylodeep__ for Python (version 3.8 or higher) with or without [conda](https://conda.io/docs/), following the procedures described below:
#### Installing with conda
Once you have conda installed, create an environment for __phylodeep__ with Python>=3.8 (here we name it phyloenv):
```bash
conda create --name phyloenv python=3.8
```
Then activate it:
```bash
conda activate phyloenv
```
Then install __phylodeep__ in it:
```bash
pip install phylodeep
```
#### Installing without conda
Make sure that Python>=3.8 and pip3 are installed, then install __phylodeep__:
```bash
pip3 install phylodeep
```
## Usage
If you installed __phylodeep__ with conda, do not forget to activate the corresponding environment (e.g. phyloenv) before using PhyloDeep:
```bash
conda activate phyloenv
```
We recommend to perform a priori model adequacy first to assess whether the input data resembles well the
simulations on which the neural networks were trained.
### Example data
Here, we use an HIV tree reconstructed from 200 sequences, published in "Phylodynamics on local sexual contact networks"
by 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 [test_tree_HIV_Zurich/Zurich.trees](https://github.com/evolbioinfo/phylodeep/blob/main/test_tree_HIV_Zurich/Zurich.trees).
### Python
```python
from phylodeep import BD, BDEI, BDSS, FULL
from phylodeep.checkdeep import checkdeep
from phylodeep.modeldeep import modeldeep
from phylodeep.paramdeep import paramdeep
path_to_tree = './Zurich.trees'
# set presumed sampling probability
sampling_proba = 0.25
# a priori check for models BD, BDEI, BDSS
checkdeep(path_to_tree, model=BD, outputfile_png='BD_a_priori_check.png')
checkdeep(path_to_tree, model=BDEI, outputfile_png='BDEI_a_priori_check.png')
checkdeep(path_to_tree, model=BDSS, outputfile_png='BDSS_a_priori_check.png')
# model selection
model_BDEI_vs_BD_vs_BDSS = modeldeep(path_to_tree, sampling_proba, vector_representation=FULL)
# the selected model is BDSS
# parameter inference
param_BDSS = paramdeep(path_to_tree, sampling_proba, model=BDSS, vector_representation=FULL,
ci_computation=True)
# for the interpretation of results, please see below
```
### Command line
```bash
# we use here a tree of 200 tips
# a priori model adequacy check: highly recommended
checkdeep -t ./Zurich.trees -m BD -o BD_model_adequacy.png
checkdeep -t ./Zurich.trees -m BDEI -o BDEI_model_adequacy.png
checkdeep -t ./Zurich.trees -m BDSS -o BDSS_model_adequacy.png
# model selection
modeldeep -t ./Zurich.trees -p 0.25 -v CNN_FULL_TREE -o model_selection.csv
# parameter inference
paramdeep -t ./Zurich.trees -p 0.25 -m BDSS -v FFNN_SUMSTATS -o HIV_Zurich_BDSS_FFNN.csv
paramdeep -t ./Zurich.trees -p 0.25 -m BDSS -v CNN_FULL_TREE -o HIV_Zurich_BDSS_CNN_CI.csv -c
```
### Example of output and interpretations
The a priori model adequacy check results in the following figures:
#### BD model adequacy test
#### BDEI model adequacy test
#### BDSS model adequacy test
For the three models (BD, BDEI and BDSS), HIV tree datapoint (represented by a red star) is well inside the data cloud
of simulations, where warm colors correspond to high density of simulations. The simulations and HIV tree datapoint were
in the form of summary statistics prior to applying PCA. All three models thus pass the model adequacy check.
We then apply model selection using the full tree representation and obtain the following result:
| Model | Probability BDEI | Probability BD | Probability BDSS |
| -------- | ------------- | ------------- | ------------- |
| __Predicted probability__ | 0.00 | 0.00 | 1.00 |
The BDSS probability is by far the highest: it is the BDSS model that is confidently selected
Finally, under the selected model BDSS, we predict parameter values together with 95% CIs:
| | R naught | Infectious period | X transmission | Superspreading fraction |
| ------------- | ------------- | ------------- | ------------- | ------- |
| __predicted value__ | 1.69 | 9.78 | 9.34 | 0.079 |
| __CI 2.5%__ | 1.40 | 8.12 | 6.65 | 0.050 |
| __CI 97.5%__ | 2.08 | 12.26 | 10 | 0.133 |
The point estimates for parameters that are no time related (R naught, X transmission and Superspreading fraction) are
well inside the parameter ranges of simulations and thus seem valid (R naught between 1 and 5, x transmission between 3
and 10, superspreading fraction between 0.05 and 0.20).
The time related parameters (infectious and eventually incubation period for BDEI model) are in the same units as the
branches of input tree, here in years (9.78 years). The covered parameter space for time related parameters is large
due to internal rescaling of all input trees. It should apply to any tree.
Raw data
{
"_id": null,
"home_page": "https://github.com/evolbioinfo/phylodeep",
"name": "phylodeep",
"maintainer": "Anna Zhukova",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "anna.zhukova@pasteur.fr",
"keywords": "phylodynamics, molecular epidemiology, phylogeny, model selection, paramdeep, phylodeep, deep learning, convolutional networks",
"author": "Jakub Voznica",
"author_email": "jakub.voznica@pasteur.fr",
"download_url": "https://files.pythonhosted.org/packages/59/c1/1d54e1f9a3bc872f18ab3de84ff944b73c3d09e6a83e9b5d6e02811a3a30/phylodeep-0.9.tar.gz",
"platform": null,
"description": "# PhyloDeep\n\nPhyloDeep is a python library for parameter estimation and model selection from phylogenetic trees, based on deep learning.\n\n## Article\n\nVoznica J, Zhukova A, Boskova V, Saulnier E, Lemoine F, Moslonka-Lefebvre M, Gascuel O.\n__Deep learning from phylogenies to uncover the transmission dynamics of epidemics__. [Nat Commun 13, 3.86 (2022)](https://www.nature.com/articles/s41467-022-31511-0)\n\n\n## Installation\n\nThe installation time of the package can be up to several minutes, including downloading dependencies. The run time \nshould be a couple of seconds. The package was tested in Linux (Ubuntu 18.08), Windows 10 and MacOS.\n\n### Windows\nFor **Windows** users, we recommend installing __phylodeep__ via [Cygwin environment](https://www.cygwin.com/).\nFirst install Python>=3.8 and pip3 from the Cygwin packages. Then install __phylodeep__:\n```bash\npip3 install phylodeep\n```\n\n### All other platforms\n\nYou can install __phylodeep__ for Python (version 3.8 or higher) with or without [conda](https://conda.io/docs/), following the procedures described below:\n\n#### Installing with conda\n\nOnce you have conda installed, create an environment for __phylodeep__ with Python>=3.8 (here we name it phyloenv):\n\n```bash\nconda create --name phyloenv python=3.8\n```\n\nThen activate it:\n```bash\nconda activate phyloenv\n```\n\nThen install __phylodeep__ in it:\n\n```bash\npip install phylodeep\n```\n\n#### Installing without conda\n\nMake sure that Python>=3.8 and pip3 are installed, then install __phylodeep__:\n\n```bash\npip3 install phylodeep\n```\n\n## Usage \n\nIf you installed __phylodeep__ with conda, do not forget to activate the corresponding environment (e.g. phyloenv) before using PhyloDeep:\n```bash\nconda activate phyloenv\n```\n\nWe recommend to perform a priori model adequacy first to assess whether the input data resembles well the \nsimulations on which the neural networks were trained.\n\n### Example data\n\nHere, we use an HIV tree reconstructed from 200 sequences, published in \"Phylodynamics on local sexual contact networks\" \nby 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 [test_tree_HIV_Zurich/Zurich.trees](https://github.com/evolbioinfo/phylodeep/blob/main/test_tree_HIV_Zurich/Zurich.trees). \n\n### Python\n\n```python\nfrom phylodeep import BD, BDEI, BDSS, FULL\nfrom phylodeep.checkdeep import checkdeep\nfrom phylodeep.modeldeep import modeldeep\nfrom phylodeep.paramdeep import paramdeep\n\n\npath_to_tree = './Zurich.trees'\n\n# set presumed sampling probability\nsampling_proba = 0.25\n\n# a priori check for models BD, BDEI, BDSS\ncheckdeep(path_to_tree, model=BD, outputfile_png='BD_a_priori_check.png')\ncheckdeep(path_to_tree, model=BDEI, outputfile_png='BDEI_a_priori_check.png')\ncheckdeep(path_to_tree, model=BDSS, outputfile_png='BDSS_a_priori_check.png')\n\n\n# model selection\nmodel_BDEI_vs_BD_vs_BDSS = modeldeep(path_to_tree, sampling_proba, vector_representation=FULL)\n\n# the selected model is BDSS\n\n# parameter inference\nparam_BDSS = paramdeep(path_to_tree, sampling_proba, model=BDSS, vector_representation=FULL, \n ci_computation=True)\n\n# for the interpretation of results, please see below\n```\n\n### Command line\n\n```bash\n\n# we use here a tree of 200 tips\n\n# a priori model adequacy check: highly recommended\ncheckdeep -t ./Zurich.trees -m BD -o BD_model_adequacy.png\ncheckdeep -t ./Zurich.trees -m BDEI -o BDEI_model_adequacy.png\ncheckdeep -t ./Zurich.trees -m BDSS -o BDSS_model_adequacy.png\n\n# model selection\nmodeldeep -t ./Zurich.trees -p 0.25 -v CNN_FULL_TREE -o model_selection.csv\n\n# parameter inference\nparamdeep -t ./Zurich.trees -p 0.25 -m BDSS -v FFNN_SUMSTATS -o HIV_Zurich_BDSS_FFNN.csv\nparamdeep -t ./Zurich.trees -p 0.25 -m BDSS -v CNN_FULL_TREE -o HIV_Zurich_BDSS_CNN_CI.csv -c\n```\n\n### Example of output and interpretations\n\nThe a priori model adequacy check results in the following figures:\n\n#### BD model adequacy test\n\n\n#### BDEI model adequacy test\n\n\n#### BDSS model adequacy test\n\n\nFor the three models (BD, BDEI and BDSS), HIV tree datapoint (represented by a red star) is well inside the data cloud\nof simulations, where warm colors correspond to high density of simulations. The simulations and HIV tree datapoint were\nin the form of summary statistics prior to applying PCA. All three models thus pass the model adequacy check.\n\nWe then apply model selection using the full tree representation and obtain the following result:\n\n| Model | Probability BDEI | Probability BD | Probability BDSS |\n| -------- | ------------- | ------------- | ------------- |\n| __Predicted probability__ | 0.00 | 0.00 | 1.00 |\n\nThe BDSS probability is by far the highest: it is the BDSS model that is confidently selected\n\nFinally, under the selected model BDSS, we predict parameter values together with 95% CIs:\n\n| | R naught | Infectious period | X transmission | Superspreading fraction |\n| ------------- | ------------- | ------------- | ------------- | ------- |\n| __predicted value__ | 1.69 | 9.78 | 9.34 | 0.079 |\n| __CI 2.5%__ | 1.40 | 8.12 | 6.65 | 0.050 |\n| __CI 97.5%__ | 2.08 | 12.26 | 10 | 0.133 |\n\nThe point estimates for parameters that are no time related (R naught, X transmission and Superspreading fraction) are\nwell inside the parameter ranges of simulations and thus seem valid (R naught between 1 and 5, x transmission between 3 \nand 10, superspreading fraction between 0.05 and 0.20). \n\n\nThe time related parameters (infectious and eventually incubation period for BDEI model) are in the same units as the \nbranches of input tree, here in years (9.78 years). The covered parameter space for time related parameters is large \ndue to internal rescaling of all input trees. It should apply to any tree.\n",
"bugtrack_url": null,
"license": null,
"summary": "Phylodynamic paramater and model inference using pretrained deep neural networks.",
"version": "0.9",
"project_urls": {
"Homepage": "https://github.com/evolbioinfo/phylodeep"
},
"split_keywords": [
"phylodynamics",
" molecular epidemiology",
" phylogeny",
" model selection",
" paramdeep",
" phylodeep",
" deep learning",
" convolutional networks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0fa9b077066790e26869f8affb56f5160bcfd7593bd67b626c798cebd60f003a",
"md5": "a92e9e6b27254f61a55745c3b74a036d",
"sha256": "1f3cf180cb4b70abfeaf9fe4f9d3488c02c2d46c0d12e58441c3c46cf7b6e85e"
},
"downloads": -1,
"filename": "phylodeep-0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a92e9e6b27254f61a55745c3b74a036d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4537216,
"upload_time": "2024-09-20T14:44:49",
"upload_time_iso_8601": "2024-09-20T14:44:49.675868Z",
"url": "https://files.pythonhosted.org/packages/0f/a9/b077066790e26869f8affb56f5160bcfd7593bd67b626c798cebd60f003a/phylodeep-0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59c11d54e1f9a3bc872f18ab3de84ff944b73c3d09e6a83e9b5d6e02811a3a30",
"md5": "618a92e5f390995ec2e4bd4fecd8dfa0",
"sha256": "123365b279c706b9b2c0f4c8b215bc3f9943b8c52a02f76bb0e9a2bc91cf5d47"
},
"downloads": -1,
"filename": "phylodeep-0.9.tar.gz",
"has_sig": false,
"md5_digest": "618a92e5f390995ec2e4bd4fecd8dfa0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4495420,
"upload_time": "2024-09-20T14:44:52",
"upload_time_iso_8601": "2024-09-20T14:44:52.123171Z",
"url": "https://files.pythonhosted.org/packages/59/c1/1d54e1f9a3bc872f18ab3de84ff944b73c3d09e6a83e9b5d6e02811a3a30/phylodeep-0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-20 14:44:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evolbioinfo",
"github_project": "phylodeep",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "phylodeep"
}
JSON
