Before any run

⇅ Get set up to use Github

You need to interact with Github to run and edit flepimop code. Github is a web platform for people to share and manage software, and it is based on a 'version control' software called git that helps programmers keep track of changes to code. Flepimop core code as well as example projects using flepimop code are all stored on Github, and frequently being updated. The first step to using flepimop for your own project is making sure you're set up to interact with code shared on Github.

If you are totally new to Github, navigate to Github.com and Sign Up for a new account. Read about the basics of git.

To work with flepimop code, you can do some tasks from the Github website, but you'll also need a way to 'clone' the code to your own local computer and keep it up to date with versions hosted online. You can do this either using a user interface like Github Desktop, or, using git commands from the command line. Make sure you have one or both installed.

If you are a veteran user, make sure you're signed in on Github.com and through whatever method you use locally on your computer to interact with Github.

🧺 Organizing your folders

In order to run any model with flepiMoP, you need access to two separate directories: One containing the flepiMoP code (code directory), and another containing the specific input files to run the model of your choosing (and to save the output from that model) (project directory). The flepiMoP code is available in a public repository on Github which can be pulled locally to serve as the code directory. We highly recommend also using Github to create your project directory. To get familiar with the code, we recommend starting with our example configurations by making a fork of flepimop_sample. If you need to create your own project repository from scratch, see instructions below.

For both the project repository and flepiMoP code repository, make sure you're on the correct branch, then pull updates from Github. Take note of the local file path to each directory.

These directories can be located on your computer wherever you prefer, since you can tell flepiMoP where they are, but we recommend you clone these flat, e.g.

parentdirectory
├── flepiMoP
├── flepimop_sample
└── project_directory_1

🔐 Access the flepiMoP model code

To get access to the flepiMoP model code - stored as a repository on Github.com - you need to copy it to your local computer (called "cloning" in git lingo).

To clone the flepimop code repository

• If you're using the command line in a terminal, first navigate to your local directory you'll use as the parent directory for all these files. Then, use the command: git clone https://github.com/HopkinsIDD/flepiMoP

• If you're using Github Desktop, go File -> Clone Repository, switch to the "URL" tab and copy the URL https://github.com/HopkinsIDD/flepiMoP there. For the "Local Path" option, make sure you choose your desired parent directory.

📂 Create a project repository from flepimop_sample

The flepimop_sample repository contains example configuration files you can use to run simple models, as well as structured model inputs (e.g., population sizes, initial conditions) organized as we recommend organizing your own project repositories. A good way to start out with flepimop is to try running these simple models, or use them as a template to make more complex ones ;

In order to create a sample project repository from the flepimop_sample repository you can follow these steps:

1. Fork the sample project repository, flepimop_sample, to your desired Github account and give it a repository name. Instructions for forking a repository are available here. Copy the URL of your forked version of the repository.

2. Clone the sample project repository locally.

   • If you're using the command line in a terminal, first navigate to your local directory you'll use as the parent directory for all these files. Then, use the command: git clone <my flepimop_sample repository URL>

   • If you're using Github Desktop, go File -> Clone Repository and either find the repository name under the Github.com list, or switch to the "URL" tab and copy the URL there. For the "Local Path" option, make sure you choose your desired parent directory.

   • In either case, make you are cloning your forked version of the repository, not the version owned by HopkinsIDD

3. Make sure the sample project repository files are up to date

   • To make sure that changes in the core flepimop code are always in sync with our example configuration files, we keep the newest versions of the sample code in the flepimop repository (in the examples directory). We try to keep flepimop_sample repository up to date, but in case we haven't kept up, it's best to copy the most up to date files over yourself

   • Copy all the contents of the examples/tutorials directory into your local version of flepimop_sample . You can do this by copying and pasting the files, or, by running the following at the command line in your terminal (assuming you have navigated to the parent directory that contains both your repositories):

     • cp -a ./flepiMoP/examples/tutorials/. ./flepimop_sample/

   • You will see if there are any changes to flepimop_sample files by looking at Github's change tracking feature locally ;

📂 Create a project repository from scratch

Create a repository for your project on Github, naming it something other than flepiMoP. This repository will eventually contain the configuration file specifying your model, any other input files or data, and will be where the model output will be stored. These files are always kept completely separately from the universal flepimop code that runs the model.

How to create a repository on Github: https://docs.github.com/en/get-started/quickstart/create-a-repo

Clone the repository locally (as above), either before or after populating it with files described below.

👨‍👩‍👧‍👦 Populate the repository

Add config file

Put your model configuration file(s) directly in this repository.

Create a folder for model inputs

This folder (which can have any name, but for simplicity can just be called model_input) should contain your files specifying the population structure, population mixing, seeding/initial conditions, and optional input such as time-series parameters.

Now you area ready to run the code using your desired method (see below)!

🏃🏽‍♀️ Running the code

If you have any trouble or questions while trying to run flepimop, please report them on the GitHub Q&A.

🤔 Deciding how to run

The code is written in a combination of R and Python. The Python part of the model is a package called gempyor, and includes all the code to simulate the epidemic model and the observational model and apply time-dependent interventions. The R component conducts the (optional) parameter inference, and all the (optional) provided pre and post processing scripts are also written in R. Most uses of the code require interacting with components written in both languages, and thus making sure that both are installed along with a set of required packages. However, Python alone can be used to do forward simulations of the model using gempyor.

Because of the need for multiple software packages and dependencies, we describe different ways you can run the model, depending on the requirements of your model setup. See Quick Start Guide for a quick introduction to using gempyor and flepiMoP. We also provide some more advanced ways to run our model, particularly for doing more complex model inference tasks.

Final notes

Since you will be editing files in your project repository frequently, get in the habit of using the git workflow - committing those changes when you've completed a concrete task, pushing your changes to the remote (online) version of your repository on Github.com, and making sure to fetch changes from the remote version to download to your local version before you start a new task (if you share your project with others or switch computers).

The setup described above assumes that a typical user will not be editing the core flepimop user code. If however you are involved in the project in a way that you do plan on editing code, or if you want to add your own enhancements, please consider forking the repository and create a version in your own account, instead of just cloning our (user:HopkinsIDD) version. Set your fork to be synced with the HopkinsIDD version though, so that you get notified of code updates or bug fixes that may also impact your fork.