Applied Modeling Project Structure

Who this is for: new lab members starting their first applied project. Read it before or alongside Getting Started with EpiModelHIV.

This page describes how an applied modeling project is organized: the two repositories it uses, where each kind of work happens, and what each folder of the project repo contains. The EpiModelHIV-Template README.md and the README.md in each chapter folder are the detailed reference; this page is the map.

Two repositories

• Project repo: the scripts, inputs, and results for one research question. Think of it as what another researcher would clone to reproduce your paper.
• Software repo: your branch of EpiModelHIV-p, written EpiModelHIV-p@<project>, created from the default branch (the current base model, v3.3.x as of October 2026). This is where you change or add model modules. Keeping the modules in a package branch, separate from the analysis scripts, lets you pull in improvements to the base model and keeps the project scripts short.

The project records which software branch it uses in two places: EMHIVp_branch in R/shared_variables.R, and the EpiModelHIV entry (branch and commit) in renv.lock.

EpiModelCOVID projects follow the same two-repository pattern with a branch of EpiModelCOVID. There is no COVID template or tutorial; ask Sam for a current example project to start from.

Three places

• Your computer: where you write and test all code, at small scale (10,000-node networks and a few replications). Both repos are cloned side by side and open in two RStudio windows.
• GitHub: where both repos live. You push from your computer, and the HPC pulls from GitHub.
• The HPC: where full-scale runs happen (100,000-node networks and many replications). Never edit code on the HPC: change it on your computer, push it to GitHub, and let the HPC workflow pull it. Each workflow-*.R script builds such a workflow with slurmworkflow; see Running Project Workflows on the HPC. Results that are not tracked by git (see data/run/ below) move between your computer and the HPC with scp or rsync (Working with Files on the HPC).

flowchart LR
  subgraph PC["Your computer"]
    P1["project repo<br/>(scripts, data/input)"]
    S1["EpiModelHIV-p clone<br/>(your branch)"]
  end
  subgraph GH["GitHub"]
    P2["project repo"]
    S2["EpiModelHIV-p<br/>project branch"]
  end
  subgraph HPC["RSPH HPC"]
    P3["project clone<br/>(data/run, workflows)"]
  end
  P1 -- "git push" --> P2
  S1 -- "git push" --> S2
  P2 -- "git pull (workflow step 1)" --> P3
  S2 -- "renv restore from renv.lock.hpc" --> P3
  P1 -- "scp: workflows/ and git-ignored inputs" --> P3
  P3 -- "scp or rsync: results" --> P1

Loading

Code only moves in one direction, from your computer through GitHub to the HPC. Files that git ignores (workflow folders, large inputs, results) move directly between your computer and the HPC.

Project repo layout

<project>/
├── R/
│   ├── 00-setup.R           one-time setup: renv restore and EpiModelHIV install
│   ├── shared_variables.R   paths, time steps, EpiModelHIV branch (sourced by every script)
│   ├── hpc_configs.R        HPC settings and make_em_workflow()
│   ├── netsim_settings.R    builds `param` and `init` for netsim (sourced)
│   ├── z-test.R             scratch file
│   ├── A-networks/          estimate and diagnose the network models
│   ├── B-model_dev/         develop and debug modules, try scenarios
│   ├── C-calibration/       calibrate to targets, create the restart point
│   └── D-interventions/     intervention scenarios, outcomes, tables, plots
├── data/
│   ├── input/               parameter overrides, scenarios.csv (tracked by git)
│   ├── run/                 estimates, diagnostics, calibration, scenario runs (not tracked)
│   └── output/              final tables and plots (not tracked)
├── workflows/               generated HPC workflows (not tracked)
├── Rmd/                     calibration report
├── renv.lock                package versions for your computer
├── renv.lock.hpc            smaller lockfile for the HPC (simulation packages only)
├── .Rprofile                activates renv, creates the data folders, defines load_local_EpiModelHIV()
├── .Renviron                your token and local paths (not tracked; you create it)
├── README.md                purpose of the project; later, the paper and software citation
└── <project>.Rproj

Chapters

Folder	What it does	Main outputs
R/A-networks/	Estimate the main, casual, and one-off partnership networks from ARTnet data and check them	data/run/estimates/, data/run/diagnostics/
R/B-model_dev/	Run netsim, develop and debug modules against your local EpiModelHIV clone, try the scenario API	none; this chapter is a sandbox
R/C-calibration/	Fit parameters to calibration targets (manually, then with swfcalib) and create the restart point	data/run/estimates/restart-<context>.rds, updated data/input/model_parameters.csv
R/D-interventions/	Define and run intervention scenarios from the restart point, compute outcomes, make tables and plots	data/run/scenarios/, data/output/

The chapters are run in order the first time, but the work is iterative: you will go back and forth between B, C, and D.

Script conventions

• Numbered scripts (1-estimation.R, 2-diagnostics.R, and so on) are the steps of a chapter. Run them in order, each in a fresh R session (Ctrl+Shift+F10, or Cmd+Shift+0 on macOS).
• workflow-*.R scripts run on your computer and write an HPC workflow into workflows/.
• z-context.R switches a chapter between local and HPC settings; setting hpc_context <- TRUE before sourcing it selects the HPC settings. It is sourced, never run directly.
• All other scripts (initialize.R, outcomes.R, labels.R, utils-*.R, and so on) define objects or functions for the numbered scripts. They are sourced, never run directly.
• R/shared_variables.R is the only place for paths, time steps, and milestones such as intervention_start. Do not redefine these variables in other scripts.

Data folders

• data/input/ holds everything the scripts need before any code runs: model_parameters.csv, which lists the project's overrides of the EpiModelHIV parameter defaults (see New Parameters and Attributes), and scenarios.csv. It is tracked by git, so it is on GitHub and reaches the HPC with the code.
• data/run/ holds everything the scripts create and reuse: network estimates, diagnostics, calibration runs, restart points, and raw and merged scenario runs. It is not tracked by git and fills up quickly. Copy files between your computer and the HPC as each chapter's README describes.
• data/output/ holds the final tables and figures. It is not tracked by git either; the scripts regenerate it.

.Rprofile creates these folders when you open the project.

Older layouts

Projects started before March 2026 use earlier versions of the template: chapters A-networks to F-intervention_scenarios plus Z-calibration (template branches v3.1.x and v3.2.x), or, before February 2024, numbered scripts directly in R/ (01-networks_estimation.R, utils-0_project_settings.R, workflow_01-*.R) with data/intermediate/ in place of data/run/. The ideas are the same; follow the README files in your own project.