EpiModelHIV-Template

This template is a scaffold for an EpiModelHIV applied project. It walks you through every step from cloning the repo to publication-ready tables and plots.

This project relies on several tools:

• EpiModel — network-based epidemic simulation framework
• EpiModelHIV — HIV/STI modules built on EpiModel
• ARTnet — sexual partnership survey data used for network estimation
• slurmworkflow — HPC job pipeline generation
• renv — R package version management

See the EpiModeling wiki for how we use these tools in practice.

Setup

Before running any scripts, complete these steps in order.

1. Prerequisites

This project has two components that work together:

• Your applied project (this repo) — scripts, parameters, and analysis for your research question.
• EpiModelHIV-p@<your_branch> — your custom branch of the EpiModelHIV-p package containing the simulation modules.

From now on, we refer to your applied project as <applied_project> and to your package branch as EpiModelHIV-p@<applied_project>.

• Create a new repository <applied_project> from the EpiModelHIV-Template ("Use this template" green button above) and clone it to your local machine
• Create a new branch on EpiModelHIV-p for your project and clone it to your local machine
• Have access to ARTnetData
• Have an RSPH HPC account (instructions) for the HPC parts

2. Set project environment variables

Three variables must be defined in the project-level .Renviron file:

• EPIMODELHIV_DIR: the path to your local clone of EpiModelHIV-p@<applied_project>. Used by .Rprofile to locate the sibling package.
• HPC_MAIL_USER: the email address SLURM should notify for HPC job status. Used by R/hpc_configs.R.
• GITHUB_PAT: your GitHub personal access token, needed to install the private packages (EpiModelHIV-p, ARTnetData). R reads only one .Renviron, so once the project has its own, the token in your user-wide ~/.Renviron is ignored and private installs fail with "error code 56".

Open the project .Renviron with:

usethis::edit_r_environ("project")

(This opens the .Renviron scoped to this project, not your user-wide one.) Add these three lines, adjust them to your setup, save, then restart R:

EPIMODELHIV_DIR="/path/to/EpiModelHIV-p"
HPC_MAIL_USER="you@emory.edu"
GITHUB_PAT="<your GitHub token>"

The project .Renviron is git-ignored, so the token stays out of git.

3. Personalize

Open R/shared_variables.R and edit every variable marked with # <- USER (your EpiModelHIV-p branch name). The project will not work until this is done.

R/hpc_configs.R needs no edits. When you create an HPC workflow, it reads the current git branch of this project, and the HPC clone of the project must be on that same branch.

4. Initialize the R environment

Open R/00-setup.R and run it step by step (read the comments — there is a required R restart in the middle).

This installs all R packages.

5. Start Chapter A

You are now ready to begin. Head to R/A-networks/README.md.

---

Project overview

The project is organized into four sequential chapters under R/:

Chapter	What it does	Output
A — Networks	Estimate partnership network models from ARTnet data	data/run/estimates/
B — Model Dev	Run simulations, develop and debug custom modules	—
C — Calibration	Fit parameters to epidemiological targets	data/run/calibration/
D — Interventions	Run intervention scenarios, produce tables and plots	data/run/scenarios/ & data/output/

In practice the workflow is iterative — you will cycle between B, C, and D as the project evolves.

Conventions

Script types — Each chapter contains:

• Numbered scripts (1-*.R, 2-*.R): top-level scripts, run in a fresh R session (Ctrl+Shift+F10), in order.
• workflow-*.R: generate HPC job files via slurmworkflow. Run locally.
• z-context.R: switches between local (small, fast) and HPC (full-scale) settings. Sourced, never run directly.
• Other scripts: utilities sourced by numbered scripts. Never run directly.

Shared variables — R/shared_variables.R is sourced by every top-level script and is the single source of truth for paths, time steps, and milestones. Never redefine its variables in other scripts.

Model parameters: the default values come from model_parameters.csv in the EpiModelHIV package (inst/model_parameters.csv in EpiModelHIV-p). data/input/model_parameters.csv holds only this project's overrides and starts with just its header. To change a value, copy the parameter's row from the package file into the project file and edit value. Empty cells keep the package value, so a row with only param and value filled in also works. read_model_params() in R/netsim_settings.R combines the two files. It stops with an error if the project file names a parameter the package does not have, so an override left behind after a parameter is renamed or removed fails loudly. New parameters go in the package file on your EpiModelHIV-p branch. Scripts that call library(EpiModelHIV) read the installed package's file; load_local_EpiModelHIV() reads the one in your local clone.

Data directories:

• data/input/ — parameters, scenario definitions (git-tracked)
• data/run/ — estimates, calibration, raw simulations (not tracked)
• data/output/ — publication tables and plots (not tracked)