IMPACTNCD_Engl is an implementation of the IMPACTNCD framework, developed by Chris Kypridemos with contributions from Max Birkett, Karl Emmert-Fees, Anna Head, Brendan Collins, Martin O'Flaherty, Peter Crowther (Melandra Ltd), Maria Guzman-Castillo, Amandine Robert, Piotr Bandosz, and Adithi R. Upadhya.
Several research grants have supported its development including grants from the Health Foundation, NIHR, EU Horizon2020, Liverpool City Council, MRC, NIH, and the National Cerebral and Cardiovascular Center in Japan.
Copyright (C) 2018-2026 University of Liverpool, Chris Kypridemos.
IMPACTNCD_Engl is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
This microsimulation translates changes in the trends of established chronic disease risk factors to changes in the incidence and prevalence of common chronic diseases, and changes in all-cause mortality, in England. A typical simulation consists of a baseline and one or more what-if policy scenarios. Policy scenarios usually comprise of changes in the exposure of a population segment to a risk factor, e.g. after some future health policy, 10% of the population show
- improved body mass index (BMI), blood pressure, or cholesterol level (each by 5%).
- increased fruit and vegetable intake (by 5%).
- reduced alcohol intake (by 5%).
- reduced smoking prevalence or passive smoking (each by 5%).
- increased physical activity (by having an additional active day).
The microsimulation can then estimate the effectiveness and equity of the modelled health policy.
The model has two parts that are obtained separately:
- The code — cloned (or downloaded) from the public GitHub repository. No GitHub account or access token is required.
- The data — the large input data and pre-computed PARFs/RR tables are not in git. They are published on Zenodo (concept DOI
10.5281/zenodo.20812409, CC-BY-SA-4.0) and downloaded with one command. The data is public, so no Zenodo account or token is required.
There are two ways to install and run the model: a Docker image (recommended — everything is bundled and reproducible) or a native R installation.
Pre-built Docker images bundle the full R environment, all model data (from Zenodo), and the model code, so there is nothing to compile or download by hand. After installing Docker:
cd docker_setup
./setup_user_docker_env.sh # Linux/macOS (Windows PowerShell: setup_user_docker_env.ps1)📖 New to this, or not a developer? Follow the step-by-step Installation & Getting-Started Guide — it walks you from installing Docker on Windows, macOS, or Linux all the way to running your own scenarios.
See docker_setup/README.md for the full Docker reference: the setup_user_docker_env/setup_dev_docker_env helpers, the three-layer image architecture (prerequisite → data → model), and how to build the images locally.
Run the model directly in R on your machine.
Prerequisites — install:
- R (≥ 4.1.0; the model is developed and tested against R 4.6.0) — guides for Windows and Linux.
- Rtools — Windows only, required to compile the C++ simulation engine.
- Git — recommended (eases future updates), and optionally RStudio.
Additional R packages (listed in docker_setup/r-packages.txt, e.g. data.table, foreach) are installed automatically the first time you source("global.R").
1. Get the code. Clone the public repository:
git clone https://github.com/ChristK/IMPACTncd_Engl.gitOr download a ZIP: on the repository page, click Code ▸ Download ZIP, then unzip it to your chosen location.
Network blocks HTTPS to GitHub but allows SSH? Clone with
git clone git@github.com:ChristK/IMPACTncd_Engl.gitinstead.global.Rinstalls the CKutils helper package from GitHub over HTTPS and, if that fails, falls back automatically to cloning it over SSH. This needs Git on yourPATHand an SSH key registered with your GitHub account (check withssh -T git@github.com). To skip the HTTPS attempt altogether, addIMPACTNCD_CKUTILS_INSTALL=sshto your~/.Renvironand restart R. If port 22 is blocked too, GitHub also accepts SSH over the HTTPS port. The other downloads (CRAN packages, the Zenodo data) come from other hosts and are not affected.
2. Download the model data from Zenodo (required on a fresh clone — a freshly cloned repository has no data). The data is public, so no account or token is needed:
source("global.R")
IMPACTncd <- Simulation$new("./inputs/sim_design.yaml")
IMPACTncd$zenodo_connect() # defaults to the published record, anonymous
IMPACTncd$zenodo_download_all() # inputs + pre-computed PARFs/RR tables (~13 GB)See the zenodo_data_management vignette for selective downloads, updating to a new data version, and (for data managers) publishing new data.
Tip: It is highly recommended to create your own copies of
inputs/sim_design.yamlandsimulation.R, edit those, and leave the originals untouched. This minimises merge conflicts when pulling updates from GitHub.
The package ships tutorial vignettes. List them all with:
vignette(package = "IMPACTncdEngland")and open one with vignette("<name>", package = "IMPACTncdEngland"). The source .Rmd files live in Rpackage/IMPACTncd_England_model_pkg/vignettes/.
| Vignette | Topic |
|---|---|
how_to_test_run |
Start here — run a test simulation (also covers how to uninstall the package). |
how_to_run_scenarios |
Define and run a baseline plus what-if policy scenarios. |
understanding_model_outputs |
Interpret the model's output files. |
custom-scenario-columns |
Export custom columns created within scenarios. |
inputs_manifest_system |
The inputs manifest / data-asset tracking system. |
zenodo_data_management |
Download, manage, and publish the model's input data on Zenodo. |
Other help files:
- docker_setup/README.md — Docker images, the three-layer build, and user/developer environment setup.
- installation_docs/ — step-by-step guides for installing R, Rtools, Git, and RStudio.
- CLAUDE.md — architecture notes and common commands for the repository.
You can find a detailed technical description and validation of the model here.
This version of the model has been used to produce two REAL Centre reports, named Health in 2040: projected patterns of illness in England and Health inequalities in 2040: current and projected patterns of illness by level of deprivation in England.
Previous versions of the IMPACTNCD microsimulation are available in Chris Kypridemos Github repository and have been published in various academic journals, such us BMJ, PLOS Med, and Circulation.