Running locally in a conda environment π
Short tutorial on running locally using an "Anaconda" environment.
Access model files
Follow all the steps in the Before any run section to ensure you have access to the correct files needed to run your model with flepiMoP.
Take note of the location of the directory on your local computer where you cloned the flepiMoP model code (which we'll call FLEPI_PATH
).
π§± Setup (do this once)
Installing the conda
environment
conda
environmentOne of simplest ways to get everything to work is to build an Anaconda environment. Install (or update) Anaconda on your computer. We find that it is easiest to create your conda environment by installing required python packages, then installing R packages separately once your conda environment has been built as not all R packages can be found on conda.
You can either use the command line (here) or the graphical user interface (you just tick the packages you want). With the command line it's this one-liner:
conda update conda # makes sure you have a recent conda instatllation
# be sure to copy the whole thing as a single line ! copy it to your text editor
conda create -c conda-forge -n flepimop-env numba pandas numpy seaborn tqdm matplotlib click confuse pyarrow sympy dask pytest scipy graphviz emcee xarray boto3 slack_sdk
Anaconda will take some time, to come up with a proposal that works with all dependencies. This creates a conda
environment named flepimop-env
that has all the necessary python packages.
The next step in preparing your environment is to install the necessary R packages. First, activate your environment, launch R and then install the following packages.
conda activate flepimop-env # this launches the environment you just created
R # to launch R from command line
# while in R
install.packages(c("readr","sf","lubridate","tidyverse","gridExtra","reticulate","truncnorm","xts","ggfortify","flextable","doParallel","foreach","optparse","arrow","devtools","cowplot","ggraph"))
If you'd like, you can install rstudio
as a package as well.
π Run the model
Activate your conda environment, which we built above.
conda activate flepimop-env
In this conda
environment, commands with R and python will uses this environment's R and python.
Define environment variables
Since you'll be navigating frequently between the folder that contains your project code and the folder that contains the core flepiMoP model code, it's helpful to define shortcuts for these file paths. You can do this by creating environmental variables that you can then quickly call instead of writing out the whole file path.
If you're on a Mac or Linux/Unix based operating system, define the FLEPI_PATH and PROJECT_PATH environmental variables to be your directory locations, for example
export FLEPI_PATH=/Users/YourName/Github/flepiMoP
export PROJECT_PATH=/Users/YourName/Github/flepiMoP/examples/tutorials
or, if you have already navigated to your flepiMoP directory
export FLEPI_PATH=$(pwd)
export PROJECT_PATH=$(pwd)/examples/tutorials
You can check that the variables have been set by either typing env
to see all defined environmental variables, or typing echo $FLEPI_PATH
to see the value of FLEPI_PATH
.
If you're on a Windows machine
set FLEPI_PATH=C:\Users\YourName\Github\flepiMoP
set PROJECT_PATH=C:\Users\YourName\Github\flepiMoP\examples\tutorials
or, if you have already navigated to your flepiMoP directory
set FLEPI_PATH=%CD%
set PROJECT_PATH=%CD%\examples\tutorials
You can check that the variables have been set by either typing set
to see all defined environmental variables, or typing echo $FLEPI_PATH$
to see the value of FLEPI_PATH
.
Other environmental variables can be set at any point in process of setting up your model run. These options are listed in ... ADD ENVAR PAGE
For example, some frequently used environmental variables we recommend setting are:
export FLEPI_RESET_CHIMERICS=TRUE
Run the code
Everything is now ready. π
The next step depends on what sort of simulation you want to run: One that includes inference (fitting model to data) or only a forward simulation (non-inference). Inference is run from R, while forward-only simulations are run directly from the Python package gempyor
.
In either case, navigate to the project folder and make sure to delete any old model output files that are there.
cd $PROJECT_PATH # goes to your project repository
rm -r model_output/ # delete the outputs of past run if there are
Inference run
An inference run requires a configuration file that has an inference
section. Stay in the $PROJECT_PATH
folder, and run the inference script, providing the name of the configuration file you want to run (ex. config.yml
).
flepimop-inference-main.R -c config.yml
This will run the model and create a lot of output files in $PROJECT_PATH/model_output/
.
The last few lines visible on the command prompt should be:
[[1]]
[[1]][[1]]
[[1]][[1]][[1]]
NULL
If you want to quickly do runs with options different from those encoded in the configuration file, you can do that from the command line, for example
flepimop-inference-main -j 1 -n 1 -k 1 -c config.yml
where:
n
is the number of parallel inference slots,j
is the number of CPU cores to use on your machine (ifj
>n
, onlyn
cores will actually be used. Ifj
<n
, some cores will run multiple slots in sequence)k
is the number of iterations per slots.
Non-inference run
Stay in the $PROJECT_PATH
folder, and run a simulation directly from forward-simulation Python package gempyor
. To do this, call flepimop simulate
providing the name of the configuration file you want to run (ex. config.yml
). An example config is provided in $PROJECT_PATH/config_sample_2pop_interventions.yml.
flepimop simulate config.yml
It is currently required that all configuration files have an interventions
section. There is currently no way to simulate a model with no interventions, though this functionality is expected soon. For now, simply create an intervention that has value zero.
You can also try to knit the Rmd file in flepiMoP/flepimop/gempyor_pkg/docs
which will show you how to analyze these files.
Last updated