- For an overview of our e3SIM, please refer to our manuscript: e3SIM: Epidemiological-ecological-evolutionary simulation framework for genetic epidemiology.
- For the codes and configuration files used in the manunscript, please refer to Zenodo at doi:10.5281/zenodo.11715269.
- For a detailed manual of e3SIM, please refer to: Manual.
-
Find a directory on your device for the software and clone the repository from the terminal.
git clone https://github.com/EpiEvoSoftware/original_pipeline
-
Create a conda environment with the provided environment file. For MacOS users, replace
${ENV_YML}
withe3SIM_mac.yml
. For Linux users, replace${ENV_YML}
withe3SIM_linux.yml
. This step took 2.5 minutes on a M2 pro macbook.cd original_pipeline conda env create --name e3SIM --file ${ENV_YML}
-
Activate the conda environment.
conda activate e3SIM
-
Install R and R packages (ONLY Required for MacOS). Note that R has to be directly callable without the full path (test by running
Rscript --help
)
Download and install R from here: https://cran.r-project.org/. After successful installation of R, run the following command one by one to install required R packages.R install.packages("phylobase") install.packages("ape") install.packages("ggplot2") install.packages("R.utils") install.packages("data.table") if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install("ggtree") BiocManager::install("Biostrings") q()
-
Test whether
$\text{e3SIM}$ is successfully installed by running a simple model. This testing took ~2 minutes on a M2 pro macbook.cd e3SIM e3SIM=${PWD} cd ../test/test_installation python update_config.py # To update the test_config.json with user's directory python ${e3SIM}/outbreak_simulator.py -config test_config.json # To run the simulation
Standard output in the terminal should show progress of the simulator. After the simulation ends, output files(e.g.,
all_SEIR_trajectory.png
) are expected in the directory (test_installation) if the installation is successful.
-
Find a working directory (in most circumstances, create a new empty directory outside the github repo you cloned). This directory will be your "working directory" for one simulation --- the generated input files and simulated results will be saved here. Save the path to variable
WKDIR
by replacing${YOUR_WORKING_DIRECTORY}
with your actual working directory.WKDIR=${YOUR_WORKING_DIRECTORY}
-
Generate a configuration file and all pre-requisite files for one simulation.
-
GUI
We provide an interactive graphical user interface (GUI) option for the pre-simulation data generation. To access the GUI, please run the following command under your
original_pipeline
directory.python gui
A window will pop up and you will be asked to navigate to your working directory in the first tab. By going through all the tabs, a configuation file called
simulation_config.json
will be generated in the working directory according to the given inputs. Please refer to Chapter 7 in the manual for more details on the GUI application. -
Command Line
Command line tools for the pre-simulatuion programs includes NetworkGenerator, SeedGenerator, GeneticEffectGenerator, and SeedHostMatcher. Please refer to the manual chapter 2 for how to run them sequentially. After running these programs, you need to create a configuration file by modifying the config file template. For explanations on the configuration file, please refer to Manual chapter 3.2. The following commands copy the template to your designated working directory.
cp ${e3SIM}/config_template/slim_only_template.json ${WKDIR}/simulation_config.json
Then manually change the configuration in
${WKDIR}/simulation_config.json
.
-
-
Run the simulation
python ${e3SIM}/outbreak_simulator.py -config ${WKDIR}/simulation_config.json
-
(Alternative to 2 & 3) Run the pre-simulation programs and the simulation together in one command. You need to fill out a bigger configuration file.
cp ${e3SIM}/config_template/base_params.json ${WKDIR}/simulation.config
Then manually change the configuration in
${WKDIR}/simulation.config
and runpython ${e3SIM}/enivol.py -config ${WKDIR}/simulation.config
-
Working examples: There are two working example runs of the simulation that are described in the Manual Chapter 5 step-by-step. It is recommended to read Chapter 5 and try out the whole pipeline as instructed to understand the whole workflow since e3SIM contains a lot of information to be digest for a first-time-user.
Copyright © 2024 Jaehee Kim. All rights reserved.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.