BCG Vaccination Interventions

This module provides BCG (Bacillus Calmette-Guérin) vaccination interventions for TBsim simulations.

Main BCG Module

class tbsim.interventions.bcg.BCGProtection(pars={}, **kwargs)[source]

Bases: Intervention

Simulates BCG-like vaccination for tuberculosis prevention in individuals within a specified age range.

This intervention identifies individuals within a configurable age range who have not yet been vaccinated. At each timestep, a proportion of these eligible individuals is selected based on the coverage parameter to receive simulated BCG protection. Once vaccinated, individuals are considered protected for a fixed number of years (immunity_period). While protected, their TB-related risk modifiers — activation, clearance, and death — are adjusted using scaled and sampled values from BCG-specific probability distributions.

Use Cases

  1. Pediatric BCG Vaccination Programs

    • Newborn vaccination: Target infants 0-1 years with high coverage (80-95%)

    • Childhood vaccination: Target children 1-5 years with moderate coverage (60-80%)

    • School-age vaccination: Target children 5-15 years with lower coverage (40-60%)

  2. Adult BCG Vaccination Strategies

    • Healthcare worker vaccination: Target adults 18-65 years with moderate coverage (40-70%)

    • High-risk population vaccination: Target specific age groups with elevated TB risk

    • Mass vaccination campaigns: Target broad age ranges during outbreak responses

  3. Research and Policy Analysis

    • Vaccine effectiveness studies: Compare different efficacy levels and protection durations

    • Coverage optimization: Evaluate optimal vaccination coverage for population-level impact

    • Age-stratified analysis: Assess vaccination strategies across different age groups

    • Economic evaluation: Model cost-effectiveness of different vaccination scenarios

  4. Scenario Modeling

    • Baseline vs intervention: Compare TB outcomes with and without BCG vaccination

    • Combined interventions: Model BCG alongside other TB interventions (TPT, treatment, diagnostics)

    • Sensitivity analysis: Test robustness across different parameter ranges

    • Policy planning: Evaluate vaccination strategies for different populations and settings

Inputs and Requirements

Required Dependencies

  • TB Disease Model: The simulation must include a TB disease model with the following attributes: - rr_activation: Risk ratio for TB activation (modified by BCG) - rr_clearance: Risk ratio for bacterial clearance (modified by BCG) - rr_death: Risk ratio for TB mortality (modified by BCG) - state: TB disease states (set to TBS.PROTECTED for vaccinated individuals)

  • Population: Must have age information accessible via sim.people.age

  • Starsim Framework: Requires starsim probability distributions and date handling

Required TB States (TBS enum)

  • TBS.PROTECTED (100): Special state for BCG-protected individuals

  • TBS.NONE (-1): Default state for unprotected individuals

  • Standard TB states: LATENT_SLOW, LATENT_FAST, ACTIVE_PRESYMP, ACTIVE_SMPOS, ACTIVE_SMNEG, ACTIVE_EXPTB, DEAD

Simulation Requirements

  • Timestep compatibility: Works with any timestep duration (automatically converts immunity_period from years to timesteps)

  • Date handling: Requires proper date objects for start/stop parameters

  • Population size: Compatible with any population size (tested with 500+ individuals)

Outputs and Reports

Real-time Metrics (Updated Each Timestep)
Vaccination Metrics:

  • n_vaccinated: Total number of vaccinated individuals

  • n_eligible: Number of eligible individuals in current timestep

  • n_newly_vaccinated: Number of newly vaccinated individuals

  • n_vaccine_responders: Number of individuals who responded to vaccine

Protection Status:

  • n_protected: Currently protected individuals

  • n_protection_expired: Individuals whose protection has expired

Coverage and Effectiveness:

  • vaccination_coverage: Coverage rate (vaccinated/eligible)

  • protection_coverage: Protection rate (protected/total_population)

  • vaccine_effectiveness: Response rate (responders/vaccinated)

Cumulative Metrics
Cumulative Totals:

  • cumulative_vaccinated: Total ever vaccinated

  • cumulative_responders: Total ever responded to vaccine

  • cumulative_expired: Total ever expired protection

Intervention Timing:

  • avg_age_at_vaccination: Average age when vaccinated

  • avg_protection_duration: Average protection period

TB Impact Assessment
Disease Outcomes (via calculate_tb_impact()):

  • vaccinated_tb_deaths: TB deaths among vaccinated individuals

  • unvaccinated_tb_deaths: TB deaths among unvaccinated individuals

  • vaccinated_tb_cases: TB cases among vaccinated individuals

  • unvaccinated_tb_cases: TB cases among unvaccinated individuals

  • deaths_averted: Estimated deaths prevented by vaccination

  • cases_averted: Estimated cases prevented by vaccination

Risk Modifiers:

  • vaccinated_death_modifier: Average death risk modifier for vaccinated

  • unvaccinated_death_modifier: Average death risk modifier for unvaccinated

Summary Statistics (via get_summary_stats())

  • total_vaccinated: Final count of vaccinated individuals

  • total_responders: Final count of vaccine responders

  • final_coverage: Final population coverage

  • vaccine_effectiveness: Overall vaccine effectiveness

  • total_population: Total population size

Debug Information (via debug_population())

  • Population demographics by age group

  • Vaccination status by age range

  • Eligibility counts for targeted age groups

param Core Parameters:

  • coverage (float): Fraction of eligible individuals vaccinated per timestep (default: 0.5)

  • start (str/datetime.date): Start date for the intervention (default: ‘1900-01-01’)

  • stop (str/datetime.date): Stop date for the intervention (default: ‘2100-12-31’)

  • efficacy (float): Probability of effective vaccine response (default: 0.8)

  • immunity_period (int): Immunity period in years (default: 10)

  • age_range (tuple): Age range (min_age, max_age) for eligibility (default: (0, 5))

param Risk Modifier Distributions:

  • activation_modifier (ss.uniform): TB activation risk modifier (default: uniform(0.5, 0.65))

  • clearance_modifier (ss.uniform): Bacterial clearance modifier (default: uniform(1.3, 1.5))

  • death_modifier (ss.uniform): TB mortality modifier (default: uniform(0.05, 0.15))

param Usage Examples:

param ————–:

param Basic Pediatric Vaccination:::

# Standard newborn BCG vaccination bcg = BCGProtection(pars={

‘coverage’: 0.9, ‘age_range’: (0, 1), ‘efficacy’: 0.8, ‘immunity_period’: 10

})

param School-age Vaccination Campaign:::

# School-based vaccination program bcg = BCGProtection(pars={

‘coverage’: 0.7, ‘start’: ‘2020-01-01’, ‘stop’: ‘2025-12-31’, ‘age_range’: (5, 15), ‘efficacy’: 0.75, ‘immunity_period’: 8

})

param Adult Healthcare Worker Vaccination:::

# Healthcare worker vaccination bcg = BCGProtection(pars={

‘coverage’: 0.6, ‘age_range’: (18, 65), ‘efficacy’: 0.7, ‘immunity_period’: 5

})

param Research Scenario with Custom Distributions:::

# Research scenario with custom risk modifiers bcg = BCGProtection(pars={

‘activation_modifier’: ss.uniform(0.4, 0.6), ‘clearance_modifier’: ss.uniform(1.2, 1.6), ‘death_modifier’: ss.uniform(0.03, 0.12)

})

Core Attributes

  • coverage_dist (ss.bernoulli): Probability distribution for vaccination coverage

  • eligible (np.ndarray): Boolean mask of currently eligible individuals

  • n_eligible (int): Number of individuals eligible for vaccination in current step

  • p_vaccine_response (ss.bernoulli): Probability distribution for vaccine response

  • start (datetime.date): Start date for the intervention

  • stop (datetime.date): Stop date for the intervention

  • min_age (float): Minimum age for vaccination eligibility

  • max_age (float): Maximum age for vaccination eligibility

Individual States

  • is_bcg_vaccinated (bool): Whether individual has received BCG vaccine

  • ti_bcg_vaccinated (float): Timestep when individual was vaccinated

  • ti_bcg_protection_expires (float): Timestep when protection expires

  • age_at_vaccination (float): Age when individual was vaccinated

  • bcg_activation_modifier_applied (float): Activation risk modifier applied

  • bcg_clearance_modifier_applied (float): Clearance modifier applied

  • bcg_death_modifier_applied (float): Death risk modifier applied

Core Methods

  • check_eligibility(): Identify and randomly select eligible individuals for vaccination

  • is_protected(uids, current_time): Return boolean mask indicating protected individuals

  • step(): Apply BCG protection and adjust TB risk modifiers accordingly

Protection Management

  • _apply_protection_effects(protected_uids): Apply BCG protection effects to TB risk modifiers

  • _remove_protection(expired_uids): Remove BCG protection effects when protection expires

  • _maintain_ongoing_protection(current_time): Maintain protection effects for all currently protected individuals

Results and Analysis

  • init_results(): Define simulation result metrics

  • update_results(): Record vaccination and eligibility metrics each timestep

  • get_summary_stats(): Get summary statistics for the intervention

  • debug_population(): Debug method to check population demographics and vaccination status

  • calculate_tb_impact(tb_model): Calculate the impact of BCG vaccination on TB outcomes

Notes

This intervention assumes the presence of a TB disease model attached to the simulation and modifies its rr_activation, rr_clearance, and rr_death arrays. The intervention uses starsim probability distributions for stochastic modeling and proper date handling for temporal eligibility checks. The age_range parameter allows targeting of any age group, making this intervention suitable for both pediatric and adult vaccination strategies.

The intervention automatically handles protection expiration and re-application of effects each timestep, ensuring that BCG protection persists throughout the immunity period. Risk modifiers are applied individually to each vaccinated person, allowing for heterogeneity in vaccine response.

__init__(pars={}, **kwargs)[source]

Initialize a BCGProtection intervention instance.

This constructor sets up the BCG vaccination intervention with user-specified or default parameters. It defines the probability distributions for coverage, efficacy, and risk modifiers, as well as the age range and timing for eligibility. It also initializes the state arrays that track vaccination and protection status for each individual in the simulation.

Parameters:

  • pars (dict, optional) – Dictionary of intervention parameters. See class docstring for details.

  • **kwargs – Additional keyword arguments passed to the parent Intervention class.

init_pre(sim)[source]

Initialize the intervention before the simulation starts.

init_post()[source]

Initialize the intervention after the simulation starts.

check_eligibility()[source]

Identify and randomly select eligible individuals for BCG vaccination in the current timestep.

This method uses starsim’s efficient indexing to find individuals who are within the configured age range and have not yet been vaccinated. It then applies the coverage probability to randomly select a subset of these eligible individuals for vaccination.

Returns:

Array of UIDs selected for vaccination in this timestep.

Return type:

ss.uids

is_protected(uids, current_time)[source]

Return boolean array indicating protection status.

Parameters:

  • uids (array-like) – Array of UIDs to check for protection status

  • current_time (float) – Current simulation timestep

Returns:

True if still protected (within immunity_period), else False

Return type:

bool array

step()[source]

Executes BCG vaccination during the current simulation timestep.

This method implements a targeted Bacille Calmette-Guérin (BCG) immunization strategy for individuals within a specified age range. It models age-filtered eligibility, stochastic coverage, and vaccine-induced protection with time-limited efficacy.

Notes

This intervention performs the following operations:

  1. Temporal eligibility check: Verifies the current simulation time falls within the intervention window (start/stop dates).

  2. Protection expiration management: Checks for previously vaccinated individuals whose protection has expired and removes their protection effects from TB risk modifiers.

  3. Eligibility determination: Identifies individuals meeting age criteria (within age_range) who have not been vaccinated.

  4. Vaccination assignment: Randomly selects eligible individuals based on coverage probability and marks them as vaccinated, recording the vaccination timestep and age at vaccination.

  5. Vaccine response modeling: Simulates individual vaccine response using efficacy probability. Only responders receive protection benefits.

  6. Protection immunity_period assignment: Sets expiration timestep for vaccine responders based on protection immunity_period.

  7. TB risk modification: Applies BCG-specific modifiers to TB activation, clearance, and death rates using starsim probability distributions for individual heterogeneity.

  8. Ongoing protection maintenance: Ensures protection effects persist for all currently protected individuals.

The method uses starsim indexing and probability distributions for efficient population-level operations and stochastic modeling.

begin_step()[source]

Called at the very start of each simulation timestep, before any disease model steps.

Ensures that BCG protection effects are applied to all currently protected individuals before the TB model uses the risk modifiers.

init_results()[source]

Define simulation result metrics for the BCG intervention.

This method sets up all the result tracking arrays including:

  • Basic vaccination metrics (total, eligible, newly vaccinated, responders)

  • Protection status metrics (protected, expired)

  • Coverage and effectiveness metrics

  • Age-specific metrics for 1-5, 5-15, and 15+ years

  • Cumulative metrics

  • Intervention timing metrics (average age at vaccination, protection immunity_period)

  • TB impact metrics (cases and deaths averted)

update_results()[source]

Update all result metrics for the current timestep.

This method calculates and stores all the intervention metrics including:

  • Basic vaccination counts and rates

  • Protection status for vaccinated individuals

  • Age-specific coverage metrics for 1-5, 5-15, and 15+ years

  • Cumulative totals

  • Average age at vaccination and protection immunity_period

  • TB impact estimates (now calculated, not placeholder)

get_summary_stats()[source]

Get summary statistics for the intervention.

Returns:

Dictionary containing summary statistics

Return type:

dict

debug_population()[source]

Debug method to check population demographics and vaccination status.

This method provides detailed information about the population age distribution, vaccination status by age group, and eligibility counts for debugging purposes.

Returns:

Dictionary containing debug information about population demographics

Return type:

dict

calculate_tb_impact(tb_model)[source]

Calculate the impact of BCG vaccination on TB outcomes.

Parameters:

tb_model (object) – The TB disease model

Returns:

Dictionary containing TB impact metrics

Return type:

dict

Available Classes

BCGProtection

Main class for implementing BCG vaccination interventions

Key Features

  • Vaccination Modeling: Realistic BCG vaccination implementation

  • Protection Levels: Variable protection against TB infection

  • Age-based Targeting: Vaccination strategies by age group

  • Effectiveness Tracking: Monitor vaccination impact over time

  • Integration: Seamless integration with TB and comorbidity models

Usage Examples

Basic BCG intervention:

from tbsim.interventions.bcg import BCGProtection
from tbsim import TB

# Add TB module and BCG vaccination
tb = TB()
bcg = BCGProtection()

sim = ss.Sim(
    diseases=tb,
    interventions=bcg
)
sim.run()

BCG with custom parameters:

bcg = BCGProtection(
    protection_level=0.8,  # 80% protection
    target_age_groups=['infant', 'child'],
    vaccination_rate=0.9   # 90% coverage
)

Key Methods

Vaccination Management

  • check_eligibility(): Determine who can receive vaccination

  • is_protected(): Check if individual has BCG protection

  • step(): Execute vaccination logic each time step

Results Tracking

  • init_results(): Initialize vaccination result tracking

  • update_results(): Update results during simulation

  • get_summary_stats(): Get vaccination summary statistics

Analysis

  • calculate_tb_impact(): Assess vaccination impact on TB outcomes

  • debug_population(): Debug vaccination status

BCG Effectiveness

BCG vaccination provides: - Infection Protection: Reduced risk of TB infection - Disease Protection: Lower progression to active disease - Severity Reduction: Less severe disease if infection occurs - Childhood Protection: Particularly effective in children

For detailed analysis of BCG impact, use the TBsim Analyzers module.