phyloModels

Python-based library with utilities for modeling and calibration, with emphasis on exploiting phylogenetic data.

Documentation

Documentation is available at https://docs.idmod.org/projects/phylomodels/en/latest/.

Files

phyloModels contains the following folders:

calibration

Algorithms and tools for model calibration.

docs

Documentation and notes.

examples

Battery of examples and use-cases of modules.

features

Summary statistics for structured (e.g., time series) and unstructured (e.g., trees, graphs) data.

models

Algorithms and tools for disease transmission models.

network

Algorithms and utilities for generation and manipulation of graphs/trees/networks.

sampling

Algorithms and utilities for sampling model generated data.

test

Main programs that test the library and demonstrate its performance.

utilities

Miscellaneous functions (read/write from/to files, data conversions, etc.)

visualization

Functions and utilities for visualization.

Data structures

Structured data is represented using Pandas dataframes. Phylogenetic trees are represented using ETE3 tree objects.

Installation

  1. Download the library:

    git clone https://github.com/InstituteforDiseaseModeling/phyloModels

  2. Install dependencies.

    Packages not on PyPI will not be installed by setuptools in step 3 below. Hence, they should be installed separately. These packages include CUDA and History Matching (at this time, CUDA and History Matching are required only for the calibration module; functions in other modules can run without these libraries).

    We recommend using a virtual environment. You can configure a virtual environment using the Conda definition file that is included in this package, or you can create a virtual environment with the required dependencies from scratch. Follow one of the steps below:

    • Create and configure virtual environment using an environment definition file.

      A Conda environment definition file is provided with this package. This file, called phylomodels_env.yml, includes definitions of all requirements, even packages not on PyPI. To use it for installing dependencies, edit the first line to set the name of the environment, and then execute the following commands for installing and activating a conda environment that satisfies all required dependencies:

      conda env create -f phylomodels_env.yml
conda activate [environment name]`

      Note

      In some systems, the environment activation command is source activate [environment name] instead of conda activate [environment name].

    • Create and configure virtual environment using Conda.

      Other than CUDA libraries, which are only used for the calibration module, most of the dependencies can be installed during the installation step (see item 3 below). However, there is an exception with some of the dependencies of the ETE3 library, which is used for representing tree data structures. These dependencies and their required versions can be installed as follows:

      conda create --name [environment name] python==3.7
conda activate [environment name]
pip install PyQt5==5.11.3

    • Create and configure virtual environment using venv.

      The process is similar to creating a Conda virtual environment:

      python3 -m venv [environment name]
source [environment name]/bin/activate
pip install PyQt5==5.11.3

  3. Install the package:

    python3 setup.py develop

    Note

    Alternatively, you could run python3 setup.py install if you plan on using the package as is, without making any changes to the code.

  4. Register environment as jupyter kernel (optional).

    You may need to manually add the new environment as a jupyter kernel. With the conda environment activated, this can be done as follows:

    python -m ipykernel install --user --name [environment name] --display-name "Python ([environment name])"

Requirements/Dependencies

See dependencies in setup.py and phylomodels_env.yml.

Examples

  • Computing summary statistics on phylogenetic trees: phylomodels/examples/features_computeTreeFeatures/features_computeTreeFeatures.ipynb

  • Model calibration using History Matching: phylomodels/examples/calibration_historyMatching_featureSelectionForSIR/calibration_historyMatching_featureSelectionForSIR.ipynb