9  Usage guide

This chapter provides operational instructions for analysts executing the Hospital-TTD-Mod pipeline. The codebase is designed to be highly modular and controlled via central configuration files, ensuring that analysts do not need to alter the core epidemiological or economic scripts to evaluate different service configurations.

9.1 Environment configuration and data security

Before executing the model, analysts must configure the master environment file (00_config.R). This file controls the geographic scope of the simulation and, critically, enforces data security protocols.

To prevent the accidental processing or compilation of restricted Hospital Episode Statistics (HES) data in unauthorised environments (e.g., local laptops or continuous integration servers), the model utilises a strict data routing toggle:

Code 
# Extract from 00_config.R

# SECURITY TOGGLE:

# Set to FALSE ONLY when executing on the secure heta_study VM
USE_DUMMY_DATA <- TRUE

# GEOGRAPHIC SCOPE:

# Define the target geography (e.g., "england" or "south_yorkshire")
TARGET_GEOGRAPHY <- "south_yorkshire"

When USE_DUMMY_DATA is set to TRUE, the pipeline routes all inputs through the synthetic data generation modules (scripts/02_data_prep_dummy/). Analysts must explicitly set this to FALSE when operating on the secure heta_study virtual machine to evaluate real patient data.

9.2 Scenario definition

The engine evaluates a basecase scenario against alternative service improvement configurations. Rather than hard-coding these parameters, analysts define scenarios using the external user_inputs/scenarios_control_panel.csv file.

This control panel allows analysts to adjust parameters such as:

  • Clinical pathways: Screening rates, specialist assessment capacities, and prescribing proportions.

  • Economic inputs: Unit costs for varying forms of nicotine replacement therapy (NRT), and the proportion of readmission savings deemed cashable.

The scripts/00_build_scenarios.R script ingests this CSV and translates it into a list of configuration objects, which are then passed sequentially through the simulation engine.

9.3 Executing the pipeline

The entire simulation is orchestrated by the central main.R script. Analysts should not execute the individual modular scripts in isolation.

Prior to execution, analysts must ensure the R environment matches the exact package versions used during development. This is handled via the renv package manager:

Code 
# Step 1: Restore the reproducible environment
renv::restore()

# Step 2: Execute the master pipeline
source("main.R")

The main.R script executes the following sequence:

  • Loads package dependencies and the 00_config.R file.
  • Sources the real or dummy data preparation pipeline based on the security toggle.
  • Ingests the scenario control panel.
  • Executes the 04_master_loop.R, passing each defined scenario through the clinical pathway, epidemiological, and economic engines.
  • Triggers the reporting modules.

9.4 Interpreting outputs

Upon successful execution, the pipeline automatically populates the output/reports/ directory.

9.4.1 Detailed tabular outputs

The pipeline generates a suite of granular CSV files, including:

  • master_clinical_long.csv: Patient flows and quitting trajectories.
  • admissions_stratified.csv: Long-term readmissions prevented, stratified by age, sex, and IMD.
  • stapleton_qalys_processed.csv: Lifetime health utility gains.

9.4.2 Executive slide deck

The primary mechanism for stakeholder dissemination is the automatically generated PowerPoint presentation (e.g., Hospital_TTD_south_yorkshire_Basecase_YYYYMMDD.pptx).

As detailed in Chapter 7, this document formally synthesises the pipeline outputs into an executive summary, providing the short-term Trust budget impact, the long-term societal cost-utility (ICER), and the methodological reconciliation against historical benchmarks.