pybdei 0.13

Description:

pybdei 0.13

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]
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 R0, 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 and Barido-Sottani et al. 2018 ] 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.





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
Input data
As an input, one needs to provide a rooted phylogenetical tree in newick 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,
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 is installed, run the following command
(here we assume that the sampling probability value is known and fixed to 0.3):
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
docker run -t evolbioinfo/bdei -h

Run with singularity
Basic usage
Once singularity is installed,
run the following command
(here we assume that the sampling probability value is known and fixed to 0.3):
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
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 C++ libraries:
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:
sudo apt install -y python3 python3-pip python3-setuptools python3-distutils

or alternatively, you could install python (version 3.9 or higher) via conda (make sure that conda is installed first).
Here we will create a conda environment called pybdeienv:
conda create --name pybdeienv python=3.9
conda activate pybdeienv
pip3 install setuptools

3. Install numpy and PyBDEI
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.
conda activate pybdeienv

To run PyBDEI
(here we assume that the sampling probability value is known and fixed to 0.3):
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:
bdei_infer -h

Basic usage in python3
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')