Installation

Using Docker (Recommended)

Because of the large number of dependencies, our strong recommendation for installation/usage simplicity is to run FAVITES via the Docker image. For your convenience, we have created a script, run_favites_docker.py, which handles all Docker-related issues for you (e.g. mounting files, pulling the proper image, etc.) and is cross-platform compatible (although Windows usage has not been thoroughly tested). Thus, our recommended installation procedure is as follows:

1. Install Docker and Python 3 on your machine
2. Download run_favites_docker.py (ideally somewhere in your PATH) and make it executable (via chmod):

   DIR='/usr/local/bin' # installation directory
   curl https://raw.githubusercontent.com/niemasd/FAVITES/master/run_favites_docker.py > $DIR/run_favites_docker.py
   chmod a+x $DIR/run_favites_docker.py

Using Singularity (Recommended for HPC)

For security reasons, many high performance computing resources (e.g. TSCC, SDSC, Comet, etc.) disallow Docker usage. Instead, many of these platforms support Singularity, which is very similar to Docker. Thus, if you are using a compute resource that supports Singularity, you can use the run_favites_singularity.py script, which handles all Singularity-related issues for you (e.g. mounting files, pulling the proper image, etc.). Thus, if you cannot use Docker and want to instead use Singularity instead, the recommended installation procedure is as follows:

1. Download run_favites_singularity.py (ideally somewhere in your PATH) and make it executable (via chmod):

   DIR='/usr/local/bin' # installation directory
   curl https://raw.githubusercontent.com/niemasd/FAVITES/master/run_favites_docker.py > $DIR/run_favites_docker.py
   chmod a+x $DIR/run_favites_docker.py

2. Load Singularity and Python 3 on your compute cluster (if applicable). This must be done each time you log in (or you can add it to your .bashrc for convenience). For example, on TSCC and Comet:

   module load singularity # load Singularity
   module load python      # load Python (and Python 3)

Note that, when you first run a specific version of FAVITES, Singularity must build the Singularity image on your machine, which may take a few minutes! However, subsequent executions of the same version of FAVITES will be fast.

Manually Installing FAVITES and Dependencies (Advanced)

If you do not wish to or are unable to use the Docker version of FAVITES (e.g. Docker is disallowed on your compute cluster), you can install FAVITES by cloning it anywhere. However, note that you will need to set up the (many) FAVITES dependencies on your own, which can be tedious. Note that you only need to set up the dependencies required by the module implementations you intend to use. Assuming you have already set up all of the required dependencies, simply clone the FAVITES repository to the desired location on your machine. Below is a comprehensive list of dependencies across all module implementations:

• Software:
  • ART
  • Dual-Birth Simulator
  • DWGSIM
  • GEMF
  • Grinder
  • HMMER
  • Java
  • msms
  • 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
  • TreeSAP: pip3 install treesap
  • TreeSwift: pip3 install treeswift
• R Modules:
  • PANGEA.HIV.sim

The Dockerfile we use to generate the FAVITES Docker images may prove to be a useful reference in setting up the dependencies, as it is essentially a series of Debian/Ubuntu commands, annotated by dependency.