Process Schematic 0 Getting Started

This wiki page will detail the steps needed to run the NEEMA Model, including process scripts included with each process subsection (Identification, Testing, etc) and a full model run. It is recommended that you use an R gui like RStudio when working through the below guide, although it is not required. This wiki has been written using R software version 4.0.2.

R Environment

The first step in preparing to to run the NEEMA model is ensuring you have the correct R environment, which - for the purposes of this wiki - is the complete package framework underpinning this project.

Project Management

A project folder is recommended when running through the NEEMA model. This folder would contain the individual process scripts, as well as any utility files (such as those described next) for project management.

renv

renv is a project management package that simplifies the sharing of R environments attached to local projects. It allows users to create a bespoke R environment specific to the current project being worked on. The first step in this process is of course installing the latest version of the renv package:

install.packages("renv")

Once installed, restart R in a new session. From the Github repository, download the renv lockfile, renv.lock into your project folder. This file contains the complete R environment associated with this project. Once downloaded, you can take a look at the contents of the lock file to see that it contains information on the exact R software and package versions we are using, as well as where we are obtaining them from. For example:

    "EpiModel": {
      "Package": "EpiModel",
      "Version": "2.0.3",
      "Source": "GitHub"
    }

this code snippet shows that we are using EpiModel version 2.0.3, and that the package is being sourced from GitHub. Once you have familiarized yourself with the lockfile, return to R so that we can initialize our R environment.

In R, in the console, initialize your R environment as such:

renv::init( )

This will initialize a local library (separate, but perhaps identical) to the default main R library of packages. If you have created an R project for this, this library should be empty. If however you are initializing renv from an existing R project, it will copy over all currently install packages to this private library It is recommended that this is done on an empty project folder (save for the renv.lock file).

Once this library folder has been created, it is time to populate the library with the package versions contained in the renv.lock file. To do this simply type:

renv::restore ( )

in your R console. renv will then read the lock file and begin to copy to the private library the correct package versions (if these versions exist in your local library, they will be copied from there, otherwise they will be sourced from the location indicated within the lockfile). This process may take awhile, however at the end you should - assuming this has been done from an empty project workspace - have an exact copy of the R environment used to run the complete NEEMA model.

We are now ready to run the individual process scripts.

Process Scripts

Each of the steps in the NEEMA workflow have an individual process script, as well an accompanying wiki page detailing the steps involved in each process as well as internal validation and consistency checks. For example, the first process, identification of partners of incident HIV+ MSM, has a wiki page titled Process 1: Identification and associated R script. All process scripts follow the same general format:

• Load R (which automatically loads the bespoke R library associated with this project)
• Load EpiModelHIV

library(EpiModelHIV)

• Load network files into the environment. The creation of these files is done in a separate script found at the supplied link.
• Network initialization and estimation and setting of epidemic parameters and initial conditions.
• Control settings for the "burnin" model are specified. The burnin model is the base model that all validation scripts are based on in order to get comparable results for comparison.

control1 <- control_msm(simno = 1001,
                        nsteps = 100,
                        ncores = 1,
                        nsims = 1,
                        save.nwstats = FALSE,
                        save.clin.hist = FALSE,
                        tergmLite = TRUE)

A second set of control settings is set that handles the individual models used to validate the process in question. Note the change in initialize.FUN.:

control2 <- control_msm(simno = 1001,
                        start = 101,
                        nsteps = 200,
                        ncores = 1,
                        nsims = 5,
                        save.nwstats = FALSE,
                        save.clin.hist = FALSE,
                        tergmLite = TRUE, 
                        initialize.FUN = reinit_msm)

With the initial setup complete, the environment is now setup to run the different validation models. For example:

# Realistic breakdown of partnership types
param$part.lookback.main <- 52
param$part.lookback.casl <- 26
param$part.lookback.ooff <- 4

sim[[2]] <- netsim(burnin, param, init, control2)

is one of the models run, that looks at the effect of reduced lookback periods (versus 52 week lookback periods for all partnership types in the burnin model).

Full Modeling Script

The full modeling script may be found here(to be updated) and largely follows the initial setup for the process scripts. This script is focused entirely on generating a burnin model that meets certain epidemic and demographic conditions (total diagnosed/HIV prevalence and linkage to care for example). Like the burnin model used in the validation process, this model will be used to test different intervention methods (variable partner lookback periods, identified partner screening rates, etc).

Parting Comments