Configuration Files

Designing a Configuration File

The configuration file is a JSON file that parameterizes an entire FAVITES simulation run. Within the configuration file, the user must specify all module implementation and parameter choices, which can become somewhat tedious due to the complexity of the framework. To assist users, we have created the Config Designer, a cross-platform Python 3 GUI that simplifies the configuration file creation process. The script is standalone and pulls its information directly from the GitHub repository, meaning it can be downloaded and used locally without needing to be updated. To set it up, simply download it (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/config_designer.py > $DIR/config_designer.py
chmod a+x $DIR/config_designer.py

Alternatively, you can simply download the script anywhere and run it via Python 3: python3 config_designer.py

Note that some module implementations depend on others, meaning not all combinations of module implementation choices are valid, and also note that some parameter choices are invalid (e.g. probabilities should be between 0 and 1, etc.), but the Config Designer does not check your choices for validity: it only checks that you have selected an implementation for all modules. However, there are many validity checks within FAVITES itself, so you will be able to receive descriptive error messages when you try running FAVITES on the configuration file you designed.

Configuration File Format

The configuration file is a JSON file containing all module implementation and parameter choices. Specifically, for each FAVITES module, the configuration file must have a key (the module's name) whose value is the corresponding module implementation choice, and for each parameter required by any chosen module implementation, the configuration file must have a key (the parameter's name) whose value is the corresponding parameter choice. Below is an example:

{
    # Module Implementations
    "Driver": "Default",
    "Logging": "STDOUT",
    "TreeNode": "Simple",
    "ContactNetwork": "NetworkX",
    "ContactNetworkGenerator": "Complete",
    "SeedSelection": "Random",
    "SeedSequence": "Random",
    "EndCriteria": "Transmissions",
    "TransmissionTimeSample": "Fixed",
    "TransmissionNodeSample": "RandomSingleInfection",
    "NodeEvolution": "VirusTreeSimulator",
    "SequenceEvolution": "NoMutation",
    "SourceSample": "Random",
    "NumTimeSample": "Once",
    "TimeSample": "End",
    "NumBranchSample": "Single",
    "TreeUnit": "LogNormal",
    "NodeAvailability": "Perfect",
    "Sequencing": "Perfect",

    # Parameter Choices
    "end_transmissions": 5,
    "fixed_transmission_time_delta": 0.5,
    "java_path": "java",
    "num_cn_nodes": 100,
    "num_seeds": 1,
    "out_dir": "FAVITES_output",
    "seed_sequence_length": 20,
    "tree_rate_mean": -6.164,
    "tree_rate_stdev": 0.3,
    "vts_growthRate": 2.851904,
    "vts_max_attempts": 10,
    "vts_model": "logistic",
    "vts_n0": 1,
    "vts_t50": -2
}

Examples of Configuration Files and Results

FAVITES has been used to perform simulation experiments in the following manuscripts:

• Moshiri N, Ragonnet-Cronin M, Wertheim JO, Mirarab S. "FAVITES: simultaneous simulation of transmission networks, phylogenetic trees, and sequences." Bioinformatics. doi:10.1093/bioinformatics/bty921
  • All simulated data
  • Default study parameters