Home

FAVITES (FrAmework for VIral Transmission and Evolution Simulation) is a robust modular framework for the simultaneous simulation of a transmission network and viral evolution, as well as simulation of sampling imperfections of the transmission network and of the sequencing process. The framework is robust in that the simulation process has been broken down into a series of interactions between abstract module classes, and the user can simply plug in each desired module implementation (or implement one from scratch) to customize any stage of the simulation process.

Contents

• Installing
• Requirements
• Usage
• Designing a Configuration File
• Network Visualization
• General Workflow
• File Formats
• Modules
• Development Guide

Installing

Assuming you have already set up all of the required dependencies, simply clone the FAVITES repository to the desired location on your machine.

git clone https://github.com/niemasd/FAVITES.git

For your convenience, we have also packaged FAVITES and all of its dependencies into a Docker image, which will automatically rebuild as updates are pushed to the FAVITES repository. Further, we created a standalone script that runs the Docker image without any user configuration needed aside from actually setting up Docker itself. Simply download it anywhere (ideally in your PATH):

curl https://raw.githubusercontent.com/niemasd/FAVITES/master/run_favites_docker.py > /usr/local/bin/run_favites_docker.py
chmod a+x /usr/local/bin/run_favites_docker.py

Requirements

To run FAVITES, you must use Python 3. Because of the many dependencies, we recommend that you use our Docker image (via run_favites_docker.py), but if you are unable to use Docker, you will need to install each selected module's own dependencies before usage (see corresponding module pages for more information). If you are missing some dependencies, FAVITES can still run if you do not choose modules with missing dependencies. To guarantee that your setup works with all module implementations, here is a comprehensive list of dependencies across all current module implementations:

• Software:
  • ART
  • DWGSIM
  • GEMF (C version)
  • Grinder
  • HMMER
  • Java
  • Newick Utilities
  • R
  • Seq-Gen
• Python 3 Modules:
  • DendroPy: pip3 install dendropy
  • NetworkX: pip3 install networkx
  • NumPy: pip3 install numpy
  • Pyvolve: pip3 install pyvolve
  • SciPy: pip3 install scipy
• R Modules:
  • PANGEA.HIV.sim

Usage

If you cloned the repository and set up the dependencies yourself, you can use run_favites.py:

run_favites.py [-h] -c CONFIG [-v]
  -h, --help                   show help message and exit
  -c CONFIG, --config CONFIG   Configuration file
  -v, --verbose                Print verbose messages to stderr (default: False)

For the Docker image, if you have already downloaded the script to somewhere in your PATH, simply run as follows:

run_favites_docker.py [-h] -c CONFIG [-v]
  -h, --help                   show help message and exit
  -c CONFIG, --config CONFIG   Configuration file
  -v, --verbose                Print verbose messages to stderr (default: False)

Note that, to use FAVITES, you must have a configuration file (CONFIG in the usage message) in the format we require. We have included an example configuration file as well as examples of other FAVITES files in the example folder. Refer to the File Formats section of the Wiki for more information.

Designing a Configuration File

The configuration file is what dictates the parameters of a given simulation experiment. As mentioned in the File Formats section of the Wiki, the configuration file is a JSON file in which keys are module or module parameter names, and values are the desired value for the given module or module parameter. Because there are so many options, it might be difficult to design the entire configuration file at once. Instead, I recommend the following process:

1. Start with an empty JSON file (i.e., a file only containing {})
2. Try running FAVITES, and it will complain about a specific missing key (either a module or a module parameter)
3. Look at the Modules page, determine the appropriate choice for the missing key based on your experiment design, and update the configuration file to include your choice for the specified missing key
4. Repeat steps 2 and 3 until FAVITES no longer complains (all keys are specified)

Helper Scripts and Post-Validation

In addition to the main FAVITES workflow, we have included numerous tools that may be helpful for running FAVITES and interpreting the results. We have a series of Helper Scripts that perform various basic miscellaneous tasks (e.g. converting between filetypes, computing interpretable statistics on files, etc.) as well as a series of Post-Validation tools that allow you to gauge how realistic your simulated output looks (e.g. comparing simulated phylogenetic trees against a realistic tree, comparing simulated sequence data against real sequences, etc.).

Network Visualization

FAVITES outputs the transmission network in two formats: the FAVITES format and the GEXF format. To visualize the transmission network, we recommend opening the GEXF transmission network in Gephi, a popular cross-platform open-source tool. The GEXF transmission network FAVITES outputs is a dynamic network, meaning you can use Gephi to visualize the growth of the transmission network over time.

In the GEXF file, each node is given a single attribute, "infected," which is set to false at time 0 and is set to true upon infection, and each edge is given a single attribute, "transmission," which is set to false at time 0 and is set to true upon a transmission event along that edge. Simply load the GEXF file outputted by FAVITES in Gephi, go to the "Appearance" box, go to the "Nodes" tab to set the desired colors for infected and uninfected (which would be "true" and "false" for the "infected" attribute, respectively), go to the "Edges" tab to set the desired colors for transmission edges and normal contact network edges (which would be "true" and "false" for the "transmission" attribute, respectively), and set "Enable auto transformation - applied continuously" to have the colors change automatically in the timeline view.