CBO's Hepatitis C Individual-Level State Transition Model (iSTM)

Important

Results from this repository are not a cost estimate and should not be interpreted as CBO’s expectation of future outcomes.

The outputs reflect illustrative policy scenarios run through the model. They depend on the model structure, input data, and user-specified assumptions, and should not be viewed as an official estimate, forecast, or prediction of real-world effects.

This repository contains an individual-level state transition model (iSTM) implemented in R to estimate the budgetary and health effects of policies aimed at increasing treatment of hepatitis C in the U.S. over a (configurable) period (commonly 10 and 30 years). The model simulates individuals as they transition across disease states, different insurers, and ages, allowing for detailed policy impact analysis. CBO can use the model to inform cost estimates. Cost estimates would depend on policies that might differ from ones modeled here and would include parameters or data that are restricted and cannot be posted publicly. For further information on the parameters used in CBO's Hepatitis C Model, please refer to Parameter Sources for CBO's Hepatitis C Model.

Key Features

• Individual-level microsimulation
  Tracks each person through disease states, insurance coverage, and aging over time.
• Comprehensive insurance modeling
  Simulates transitions across Medicaid, Medicare, commercial, marketplace, incarcerated, IHS, and uninsured status with age-specific transition probabilities.
• Age-specific all-cause mortality
  Uses mortality rates by age.
• Detailed cost tracking
  Separates costs into management, treatment, testing, and comorbidity categories across insurance types.
• Policy scenario analysis
  Compares current law vs. policy scenarios with different treatment rates depending on an individual's insurer.
• Comprehensive reporting
  Generates detailed outputs including cost breakdowns, population flows, and intermediate results for validation.

Model Components

Input Data Processing

The model uses multiple prepared data files to initialize populations and drive transitions:

• Insurance Transitions (insurer_transitions_*.csv) - Age-specific probabilities for insurance coverage changes
• Mortality Data (mortality.csv) - All-cause mortality rates by age
• Economic Parameters (economic_parameters.csv) - Discount rates and inflation factors used for projecting costs over the timeframe of the model

Core Simulation Modules

• Parameter Assignment (assign_parameters.R) - Initializes all model parameters from scenarios and config files
• Cost Construction (construct_costs.R) - Builds cost lookup tables with inflation and discount factors
• Markov Transitions (markov_transitions.R) - Handles HCV disease state progression (e.g., F0→F1→F2→F3→F4, treatment, cure, etc.)
• Microsimulation Core (microsim_core.R) - Main simulation engine processing individuals through time
• Simulation Orchestrator (simulation_orchestrator.R) - Coordinates full model runs and output generation

Output Generation

• Report Generation (report_generation.R) - Creates summary statistics and simulation results
• Visualization (visuals/create_visuals.R) - Generates plots and charts from simulation results. Runs automatically after simulation when run_visuals: true in config.yml, or can be called standalone.

Installation & Setup

CBO's Hepatitis C Model was developed in R version 4.1.3 using RStudio on a Windows 11 operating system and relies on multiple packages that are managed with the renv package. Here are instructions for installing the model from GitHub and setting up your computing environment to match the one that the CBO used.

1. Clone the Repository

1. In RStudio, select File > New Project... in the menu ribbon to open the "New Project Wizard."
2. Within the "New Project Wizard," select Version Control and then select Git.
3. Then copy and paste this GitHub repository URL into the Repository URL field:

https://github.com/US-CBO/hepatitis-c-model

(The project directory name will auto-populate based on the repo name.)

4. Enter where on your computer you'd like to download the repository to by entering the parent directory in your file system in the Create project as subdirectory field (or browsing to the location you want through the Browse... interface).

5. Then click Create Project, which will clone the repository as a subdirectory in the location you selected and then switch to the project workspace within RStudio.

6. To re-open this project after the initial download from GitHub, open the project using the hepatitis-c-model.Rproj file in the root directory.

2. Install Packages

If you do not have renv installed, you will need to install it by running the command

install.packages("renv")

in the R Console within RStudio.

Then install all of the necessary packages associated with this project by running the command:

renv::restore()

Review the list of packages necessary to run the model that will be installed and enter y to proceed with the installations.

Running The Model

Quick Start

source("main_run.R")

This runs all scenarios defined in config.yml and scenarios.yml, generates all outputs, and — if run_visuals: true in config.yml — automatically creates and saves all plots when the simulation completes.

1. Configuring Output Directory

base_dir is optional. If it is omitted or left blank, the model automatically creates an outputs/ folder inside the repository root and writes all results there.

To write outputs to a specific network path or directory, set base_dir in config.yml:

outputs:
  base_dir: "\\PATH\\TO_FOLDER\\HERE"   # optional — omit or leave blank to use repo-local outputs/
  run_folder_name: "Username_model_run_description"
  timestamp_prefix: false  # set to true to prepend YYYYMMDD-HHMMSS_ to the run folder name

Note: Double backslashes (\\\\) are required to escape backslash characters on Windows network paths.

Each run writes outputs to a subdirectory under base_dir (or the local outputs/ fallback):

outputs/
└── [run_folder_name]/              # timestamp_prefix: false (default)
└── YYYYMMDD-HHMMSS_[run_folder_name]/   # timestamp_prefix: true

2. Selecting Scenarios

Control which scenarios run via config.yml:

scenarios:
  run_scenarios: "all"         # run every scenario defined in scenarios.yml
  run_scenarios: "base_case"   # run only the base case
  run_scenarios: ["base_case", "higher_treatment_scenario"]  # run a specific subset

3. Controlling Visualization

Plots are generated automatically at the end of main_run.R when the toggle is enabled:

outputs:
  run_visuals: true   # generate and save plots after simulation (default: true)
  run_visuals: false  # skip visualization; run manually later if needed

To generate plots from an existing run folder without re-running the simulation:

source("visuals/create_visuals.R")
create_visuals()                                         # interactive folder selection
create_visuals("outputs/illustrative_policies")  # supply path directly

create_visuals() auto-detects all scenario IDs from output filenames, creates a plots/<scenario_id>/ subdirectory for each scenario, and saves all plots there.

Model Execution Process

When you run main_run.R, the model:

1. Loads Configuration - Reads config.yml and scenarios.yml
2. Initializes Parameters - Sets up all model parameters for each scenario
3. Generates Population - Creates the initial HCV population with appropriate demographics
4. Runs Microsimulation - Executes the core simulation for each scenario (Current Law and Policy)
5. Generates Outputs - Creates comprehensive results
6. Creates Visualizations - Saves plots to plots/ (if run_visuals: true)

Output Structure

Results are written to the run folder configured in config.yml. Each scenario's files are organized in a per-scenario subdirectory:

outputs/
└── [run_folder_name]/
    ├── <scenario_id>/
    │   ├── total_spending_by_year_<scenario_id>.csv
    │   ├── total_spending_by_insurer_<scenario_id>.csv
    │   ├── treatment_rates_by_insurer_<scenario_id>.csv
    │   ├── population_by_disease_stage_<scenario_id>.csv
    │   ├── age_insurer_by_cycle_current_law_<scenario_id>.csv
    │   ├── age_insurer_by_cycle_policy_<scenario_id>.csv
    │   └── spending_data.csv                    # derived by create_visuals
    ├── spending_data_all_scenarios.csv          # cross-scenario summary (billions, discounted)
    └── plots/
        └── <scenario_id>/
            ├── incremental_federal_spending.png
            ├── cumulative_federal_spending.png
            ├── treatment_rates_by_insurer.png
            ├── treatment_rate_delta_by_insurer.png
            ├── disease_stages_grouped.png
            ├── fibrosis_progression.png
            ├── cured_vs_uncured.png
            └── population_by_age_group.png

Key output files (per scenario):

File	Contents
total_spending_by_year_<id>.csv	Spending breakdown by year, policy type, and cost category
total_spending_by_insurer_<id>.csv	Spending breakdown by year, insurer, and policy type
treatment_rates_by_insurer_<id>.csv	Insurer-specific treatment rates for Current Law and Policy
population_by_disease_stage_<id>.csv	Count of individuals in each disease stage by year
age_insurer_by_cycle_current_law_<id>.csv	Enrolled population by age group and insurer, Current Law
age_insurer_by_cycle_policy_<id>.csv	Enrolled population by age group and insurer, Policy

Scenario Configuration

The model uses YAML-based scenario configuration with inheritance:

Basic Structure:

base_case:
  name: "Base Case"
  ...
  # Treatment parameters
  treatment:
    # Current law treatment rates by insurer
    current_law_rates:
      esi: 0.031
      marketplace: 0.031
      medicare: 0.035
      medicaid: 0.029
      ihs: 0.029
      incarcerated: 0.028
      uninsured: 0.023
    
    # Policy multipliers applied to current law rates
    policy_multipliers:
      esi: 1.0
      marketplace: 1.0 
      medicare: 1.0 
      medicaid: 3.0 
      ihs: 3.0 
      incarcerated: 4.0
      uninsured: 3.0
  ...

scenarios:
  - id: "high_treatment_rate_medicaid_policy"
    name: "Higher Policy Treatment Rate For Medicaid"
    inherit: "base_case"  
    treatment:
      policy_multipliers:
        medicaid: 4.0

The “base case” scenario estimates outcomes under current law and under a policy scenario with treatment rates higher than under current law. Additional scenarios in this code base include one where treatment rates under the policy would increase more than in the base case and another where treatment rates under the policy would increase less than in the base case.

Key Features:

• Parameter Inheritance: Scenarios automatically inherit all base_case parameters
• Selective Override: Only specify parameters that differ from base case
• Nested Structure: Support complex parameter hierarchies
• Validation: Automatic parameter validation and error checking

Acknowledgements

The Hepatitis C model was developed and maintained by CBO analysts Anthony Montano, Lesley Baseman, Noelia Duchovny, Nianyi Hong, and Aditi Sen. Ru Ding, Kevin Perese, and Chapin White provided useful comments after reviewing the code for this project.

Contact

For questions regarding the data, model, or documentation, contact CBO's Office of Communications at:

communications@cbo.gov

CBO will respond to inquiries as its workload permits.