Burn-in Scripts

Scripts for running burn-in simulations to establish equilibrium states before main analysis.

Archive Scripts

Historical burn-in scripts maintained for reference.

Refined TB Prevalence Sweep for Manual Calibration (South Africa) with Health-Seeking, Diagnostic, and Treatment

This script performs a manual calibration sweep of TB transmission dynamics in Starsim/TBsim to explore plausible endemic equilibrium behavior for South Africa, incorporating key epidemiological features specific to the South African context, including health-seeking behavior, diagnostic testing, and treatment outcomes.

🎯 Objective:

• Calibrate burn-in dynamics (i.e., rise and settle to endemic steady state)

• Target approximately:

  • >50% latent TB prevalence

  • ~1% active TB prevalence

• Qualitative fit to empirical data point: 0.852% active TB prevalence (South Africa, 2018)

• Model realistic health-seeking behavior, diagnostic testing, and treatment outcomes

🔧 Current Assumptions:

• Includes HIV coinfection (critical for South Africa TB dynamics)

• Models TB-HIV interaction effects on progression rates

• Uses South Africa-specific demographics and population structure

• Simulation starts in 1850 and runs 200 years to allow for equilibrium

• Incorporates historical HIV epidemic emergence (1980s onwards)

• Health-seeking behavior with 90-day average delay (slower for better burn-in)

• Diagnostic testing with 60% sensitivity, 70% coverage, and 95% specificity

• Treatment with 70% success rate and retry mechanism for failures

📊 What It Does:

• Sweeps across a grid of:

  • TB infectiousness (β)

  • Reinfection susceptibility (rel_sus_latentslow)

  • TB mortality rates

• For each parameter combo, it:

  • Runs a simulation with TB-HIV coinfection + health-seeking + diagnostic

  • Plots active and latent prevalence over time

  • Plots health-seeking behavior metrics

  • Plots diagnostic testing outcomes

  • Plots treatment outcomes (incident and cumulative)

  • Overlays the 2018 SA data point on each plot

  • Adds an inset focused on the post-1980 period (zoomed to 0–1% active prevalence)

• Outputs multiple PDF figures with all subplots, timestamped with run time

• Prints runtime diagnostics including total sweep duration

📥 Inputs:

• Hardcoded ranges for β, rel_sus_latentslow, and TB mortality

• South Africa-specific demographic parameters

• HIV epidemic parameters (prevalence targets, timing)

• Health-seeking parameters (90-day average delay)

• Diagnostic parameters (60% sensitivity, 70% coverage, 95% specificity)

📤 Outputs:

• PDF files showing:

  • TB prevalence trajectories across parameter grid

  • Health-seeking behavior metrics

  • Diagnostic testing outcomes (incident and cumulative)

  • Treatment outcomes (incident and cumulative)

  • Population demographics

  • HIV metrics

• Console logging of sweep progress and timing

⚠️ Notes:

• Active prevalence <1% is sensitive to population size; low agent counts may cause extinction

• HIV coinfection significantly impacts TB dynamics in South Africa

• Health-seeking behavior affects TB transmission and case detection

• Diagnostic testing influences treatment initiation and outcomes

• Treatment success/failure affects TB transmission and care-seeking behavior

• This model now better reflects the South African epidemiological context with realistic care-seeking and treatment

scripts.burn_in.archive.run_tb_burn_in_South_Africa.get_output_path(filename)

class scripts.burn_in.archive.run_tb_burn_in_South_Africa.GradualHIVIntervention(pars, **kwargs)

Bases: Intervention

Custom HIV intervention that implements gradual ramp-up based on van Schalkwyk et al. 2021 data for eThekwini, South Africa. Handles both age groups: 15-24 and 25+.

__init__(pars, **kwargs)

step()

Define how the module updates over time – the key part of Starsim!!

class scripts.burn_in.archive.run_tb_burn_in_South_Africa.AgeDependentTBProgression(pars, **kwargs)

Bases: Intervention

Intervention to modify TB progression rates and fast progressor fractions based on age groups.

This intervention adjusts: 1. The relative risk (rr_activation) multiplier for TB progression from latent to active disease 2. The probability of becoming a fast progressor (p_latent_fast) after TB infection

Age-specific multipliers: - 0-4 years: 2.0x the base rate (higher progression and fast progressor fraction) - 5-14 years: 0.5x the base rate (lower progression and fast progressor fraction) - 15+ years: 1.0x the base rate (base progression and fast progressor fraction)

__init__(pars, **kwargs)

step()

Apply age-dependent TB progression multipliers and fast progressor fractions

scripts.burn_in.archive.run_tb_burn_in_South_Africa.make_people(n_agents, age_data=None)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_latent_prevalence(sim)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.debug_hiv_results(sim)

Debug function to print available HIV result keys and values

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_hiv_prevalence(sim)

Compute HIV prevalence over time

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_hiv_prevalence_adults_25plus(sim, target_year=None)

Compute HIV prevalence for adults 25+ at a specific year or over time

Parameters:

• sim – Simulation object

• target_year – If specified, compute for this year only. If None, compute over time.

Returns:

float (prevalence for that year) If target_year is None: array (prevalence over time)

Return type:

If target_year specified

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_hiv_prevalence_adults_15to24(sim, target_year=None)

Compute HIV prevalence for adults 15-24 at a specific year or over time

Parameters:

• sim – Simulation object

• target_year – If specified, compute for this year only. If None, compute over time.

Returns:

float (prevalence for that year) If target_year is None: array (prevalence over time)

Return type:

If target_year specified

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_hiv_positive_tb_prevalence(sim)

Compute HIV-positive TB prevalence as proportion of total population

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_age_stratified_prevalence(sim, target_year=2018)

Compute age-stratified TB prevalence from simulation results

Parameters:

• sim – Simulation object

• target_year – Year to compute prevalence for

Returns:

Age-stratified prevalence data

Return type:

dict

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_age_stratified_prevalence_time_series(sim)

Compute age-stratified TB prevalence time series from simulation results

Parameters:

sim – Simulation object

Returns:

DataFrame with years as index and age groups as columns

Return type:

pd.DataFrame

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_total_population_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_hiv_metrics_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot HIV prevalence for both age groups (15-24 and 25+) with target data points

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_active_tb_sweep_with_data(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot active TB prevalence for all parameter combinations with separate focus on active TB

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_latent_tb_sweep_with_data(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot latent TB prevalence for all parameter combinations with separate focus on latent TB

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_tb_sweep_with_data(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Legacy function - now calls both separate active and latent TB plots

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_annualized_infection_rate(sim)

Compute annualized TB infection rate (annual risk of infection) over time.

This function calculates the annualized infection rate using two methods: 1. Method 1: Sum new_infections over 365 days and divide by population 2. Method 2: Difference in n_infected between T and T-365 days, divided by population

Returns the annualized infection rate as a percentage of the population.

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_annualized_infection_rate_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot annualized TB infection rate for all parameter combinations

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_health_seeking_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot health-seeking behavior metrics for all parameter combinations

Metrics plotted: - new_sought_care: Number of people who sought care in this timestep (count) - n_sought_care: Cumulative number of people who have ever sought care (count) - n_eligible: Number of people with active TB eligible for care-seeking (count)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_diagnostic_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot diagnostic testing metrics for all parameter combinations

Metrics plotted: - n_tested: Number of people tested in this timestep (count) - n_test_positive: Number of positive test results in this timestep (count) - n_test_negative: Number of negative test results in this timestep (count)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_cumulative_diagnostic_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot cumulative diagnostic testing results for all parameter combinations

Metrics plotted: - cum_test_positive: Cumulative number of positive test results over time (count) - cum_test_negative: Cumulative number of negative test results over time (count)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_treatment_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot TB treatment outcomes for all parameter combinations

Metrics plotted: - n_treated: Number of people who started treatment in this timestep (count) - n_treatment_success: Number of successful treatment completions in this timestep (count) - n_treatment_failure: Number of failed treatment attempts in this timestep (count)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_cumulative_treatment_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot cumulative TB treatment outcomes for all parameter combinations

Metrics plotted: - cum_treatment_success: Cumulative number of successful treatments over time (count) - cum_treatment_failure: Cumulative number of failed treatments over time (count)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_age_prevalence_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot age-stratified TB prevalence for all parameter combinations

This function creates a grid of plots showing age-stratified TB prevalence rates by age groups including children (0-4, 5-14) and adults (15+), normalized per 100,000 population. The data is compared to the 2018 South Africa prevalence survey data where available.

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_hiv_tb_coinfection_rates(sim, target_year=2018)

Compute HIV coinfection rates among TB cases by symptom status

Parameters:

• sim – Simulation object

• target_year – Year to compute rates for

Returns:

HIV coinfection rates by TB symptom status

Return type:

dict

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_hiv_tb_coinfection_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot HIV coinfection rates among TB cases by symptom status for all parameter combinations

This function creates a grid of plots showing HIV coinfection rates among TB cases stratified by symptom status, comparing model results to 2018 South Africa survey data.

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_case_notification_rate_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot annualized TB case notification rate (per 100,000) for all parameter combinations in a grid. The notification rate at time t is the difference in cumulative positive diagnoses between t and t-365 days, divided by the population at t, times 100,000. Overlays real South Africa notification data from GTB report.

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_annualized_tb_mortality_rate(sim)

Compute annualized TB mortality rate (per 100,000 population) over time.

This function calculates the annualized TB mortality rate by: 1. Taking the difference in cumulative TB deaths between time T and T-365 days 2. Dividing by the population at time T 3. Multiplying by 100,000 to get rate per 100,000 population

Returns the annualized TB mortality rate per 100,000 population.

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_tb_mortality_rate_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp)

Plot annualized TB mortality rate (per 100,000) for all parameter combinations in a grid. The mortality rate at time t is the difference in cumulative TB deaths between t and t-365 days, divided by the population at t, times 100,000.

scripts.burn_in.archive.run_tb_burn_in_South_Africa.compute_age_distribution_at_year(sim, target_year=2022)

Compute age distribution at a specific year

Parameters:

• sim – Simulation object

• target_year – Year to compute age distribution for

Returns:

Age distribution data with 5-year bins

Return type:

dict

scripts.burn_in.archive.run_tb_burn_in_South_Africa.plot_population_pyramid_grid(sim_grid, beta_vals, rel_sus_vals, tb_mortality_vals, timestamp, target_year=2022)

Plot population pyramids for each parameter combination showing age distribution at target year

Parameters:

• sim_grid – 3D grid of simulation results

• beta_vals – Array of beta values

• rel_sus_vals – Array of relative susceptibility values

• tb_mortality_vals – Array of TB mortality values

• timestamp – Timestamp for filename

• target_year – Year to compute age distribution for (default: 2022)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.run_sim(beta, rel_sus_latentslow, tb_mortality, seed=0, years=200, n_agents=1000)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.refined_sweep(beta_vals, rel_sus_vals, tb_mortality_vals)

scripts.burn_in.archive.run_tb_burn_in_South_Africa.test_hiv_integration()

Simple test function to verify HIV integration works correctly

scripts.burn_in.archive.run_tb_burn_in_South_Africa.test_health_seeking_diagnostic_integration()

Test function to verify health-seeking and diagnostic integration works correctly

Data Processing Scripts

Scripts for extracting and processing data for burn-in simulations.