TB Diagnostic Interventions

This module provides TB diagnostic testing capabilities for TBsim simulations.

Main TB Diagnostic Module

class tbsim.interventions.tb_diagnostic.TBDiagnostic(pars=None, **kwargs)[source]

Bases: Intervention

TB diagnostic intervention that performs testing on individuals who seek care.

This intervention simulates TB diagnostic testing with configurable sensitivity and specificity. It is triggered when individuals seek care and can handle false negatives by allowing retesting with increased care-seeking probability.

The intervention models the diagnostic cascade in TB care, where individuals who seek healthcare are tested for TB using diagnostic tests with known sensitivity and specificity. The intervention handles both true positive/negative results and false positive/negative results, with special logic for false negatives to allow retesting.

Use Cases:

  • Simulating TB diagnostic programs in healthcare settings

  • Evaluating the impact of diagnostic test performance on TB case detection

  • Modeling diagnostic coverage and its effect on TB transmission

  • Assessing the role of false negatives in TB care-seeking behavior

  • Studying the effectiveness of different diagnostic strategies

Inputs/Requirements:

The intervention requires the following to be present in the simulation: - TB disease module (sim.diseases.tb) with active TB states - Health seeking behavior intervention that sets the ‘sought_care’ flag - Person states: ‘sought_care’, ‘tested’, ‘diagnosed’, ‘n_times_tested’,

‘test_result’, ‘care_seeking_multiplier’, ‘multiplier_applied’

  • TB states: ACTIVE_SMPOS, ACTIVE_SMNEG, ACTIVE_EXPTB for active TB cases

Parameters:

coverage (float or Dist): Fraction of those who sought care who get tested.

Can be a fixed probability or a distribution. Range: 0.0 to 1.0. Default: 1.0 (all eligible get tested).

sensitivity (float): Probability that a test is positive given the person has TB.

Range: 0.0 to 1.0. Higher values mean fewer false negatives. Default: 0.9 (90% sensitivity).

specificity (float): Probability that a test is negative given the person does not have TB.

Range: 0.0 to 1.0. Higher values mean fewer false positives. Default: 0.95 (95% specificity).

reset_flag (bool): Whether to reset the sought_care flag after testing.

Default: False (allows for retesting).

care_seeking_multiplier (float): Multiplier applied to care-seeking probability

for individuals with false negative results. Default: 1.0 (no change).

Outputs/Reports:

The intervention generates the following results that can be accessed via sim.results: - n_tested (int): Number of people tested at each timestep - n_test_positive (int): Number of positive test results at each timestep - n_test_negative (int): Number of negative test results at each timestep - cum_test_positive (int): Cumulative number of positive test results - cum_test_negative (int): Cumulative number of negative test results

Person States Modified:

The intervention modifies the following person states: - tested (bool): Set to True for all tested individuals - n_times_tested (int): Incremented for each test performed - test_result (bool): True for positive results, False for negative results - diagnosed (bool): Set to True for positive test results - care_seeking_multiplier (float): Multiplied by care_seeking_multiplier parameter

for false negative cases to increase future care-seeking

  • multiplier_applied (bool): Tracks whether multiplier has been applied to prevent

    multiple applications

  • sought_care (bool): Reset to False for false negative cases to allow retesting

Algorithm:

  1. Identify eligible individuals (sought care, not diagnosed, alive)

  2. Apply coverage filter to select who gets tested

  3. Determine TB status for selected individuals

  4. Apply test sensitivity and specificity logic: - True TB cases: test positive with probability = sensitivity - Non-TB cases: test positive with probability = (1 - specificity)

  5. Update person states based on test results

  6. Handle false negatives by: - Increasing care-seeking probability for future attempts - Resetting care-seeking and testing flags to allow retesting

Example:

>>> sim = ss.Sim(
...     interventions=[
...         mtb.HealthSeekingBehavior(pars={'initial_care_seeking_rate': ss.perday(0.1)}),
...         mtb.TBDiagnostic(pars={
...             'coverage': 0.8,
...             'sensitivity': 0.85,
...             'specificity': 0.95,
...             'care_seeking_multiplier': 2.0
...         })
...     ]
... )
__init__(pars=None, **kwargs)[source]

Initialize the TB diagnostic intervention.

This method sets up the diagnostic intervention with default parameters and initializes temporary storage for result tracking. The intervention is ready to be added to a simulation after initialization.

Parameters:

  • pars (dict, optional) – Dictionary of parameters to override defaults. Valid keys: ‘coverage’, ‘sensitivity’, ‘specificity’, ‘reset_flag’, ‘care_seeking_multiplier’.

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

  • Parameters (Default)

  • -------------------

  • coverage (-)

  • sensitivity (-)

  • specificity (-)

  • reset_flag (-)

  • care_seeking_multiplier (-)

  • Raises

  • -------

  • ValueError (If parameter values are outside valid ranges (0.0-1.0 for probabilities).)

  • Note

  • -----

  • simulation. (The intervention requires specific person states to be present in the)

  • seeking (These are typically initialized by the TB disease module and health)

  • intervention. (behavior)

step()[source]

Execute one timestep of TB diagnostic testing.

This method performs the core diagnostic testing logic for each simulation timestep. It identifies eligible individuals, applies diagnostic tests with specified sensitivity and specificity, and handles the consequences of test results including false negatives.

Process Flow:

  1. Identify eligible individuals (sought care, not diagnosed, alive)

  2. Apply coverage filter to select who gets tested

  3. Determine TB status and apply test sensitivity/specificity

  4. Update person states based on test results

  5. Handle false negatives by allowing retesting with increased care-seeking probability

Eligibility Criteria:

  • Individual must have sought care (sought_care = True)

  • Individual must not be already diagnosed (diagnosed = False)

  • Individual must be alive (alive = True)

Test Logic:

  • True TB cases: test positive with probability = sensitivity

  • Non-TB cases: test positive with probability = (1 - specificity)

False Negative Handling:

  • Individuals with TB who test negative are identified as false negatives

  • Their care-seeking probability is increased by the care_seeking_multiplier

  • Their care-seeking and testing flags are reset to allow retesting

  • The multiplier is only applied once per individual to prevent infinite boosting

Side Effects:

  • Updates person states: tested, n_times_tested, test_result, diagnosed

  • Modifies care_seeking_multiplier and multiplier_applied for false negatives

  • Resets sought_care and tested flags for false negatives

  • Stores results for update_results method

Returns:

None

Note:

This method is called automatically by the simulation framework at each timestep. The intervention must be added to the simulation’s interventions list to be executed.

init_results()[source]

Initialize result tracking for the diagnostic intervention.

This method sets up the result tracking system for the diagnostic intervention. It defines the metrics that will be recorded at each timestep and makes them available for analysis and reporting.

Result Metrics:

  • n_tested (int): Number of people tested at each timestep

  • n_test_positive (int): Number of positive test results at each timestep

  • n_test_negative (int): Number of negative test results at each timestep

  • cum_test_positive (int): Cumulative number of positive test results

  • cum_test_negative (int): Cumulative number of negative test results

Usage:

Results can be accessed after simulation completion via: - sim.results[‘TBDiagnostic’][‘n_tested’] - sim.results[‘TBDiagnostic’][‘n_test_positive’] - etc.

Note:

This method is called automatically by the simulation framework during initialization. The results are updated each timestep by update_results().

update_results()[source]

Update result tracking for the current timestep.

This method records the diagnostic testing results for the current timestep and updates cumulative totals. It processes the temporary storage from the step() method and stores the results in the intervention’s result arrays.

Process:

  1. Calculate per-step counts from temporary storage

  2. Record current timestep results

  3. Update cumulative totals (add to previous step’s cumulative)

  4. Reset temporary storage for next timestep

Calculations:

  • n_tested: Total number of people tested this timestep

  • n_test_positive: Number of positive test results this timestep

  • n_test_negative: Number of negative test results this timestep

  • cum_test_positive: Cumulative positive results (previous + current)

  • cum_test_negative: Cumulative negative results (previous + current)

Data Sources:

  • self.tested_this_step: Array of UIDs tested this timestep

  • self.test_result_this_step: Array of test results (True/False)

Note:

This method is called automatically by the simulation framework after each timestep. The temporary storage is reset after processing to prepare for the next timestep.

class tbsim.interventions.tb_diagnostic.EnhancedTBDiagnostic(pars=None, **kwargs)[source]

Bases: Intervention

Enhanced TB diagnostic intervention that combines detailed parameter stratification from interventions_updated.py with health-seeking integration from tb_diagnostic.py.

This intervention provides: 1. Age and TB state-specific sensitivity/specificity parameters 2. HIV-stratified parameters for LAM testing 3. Integration with health-seeking behavior 4. False negative handling with care-seeking multipliers 5. Comprehensive result tracking

__init__(pars=None, **kwargs)[source]
step()[source]

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

init_results()[source]

Initialize results output; called during init_pre()

By default, modules all report on counts for any explicitly defined “States”, e.g. if a disease contains an ss.BoolState called ‘susceptible’ it will automatically contain a Result for ‘n_susceptible’. For identical behavior that does not automatically generate results, use ss.BoolArr instead of ss.BoolState.

update_results()[source]

Update results; by default, compute counts of each state at each point in time

This function is executed after transmission in all modules has been resolved. This allows result updates at this point to capture outcomes dependent on multiple modules, where relevant.

Available Classes

TBDiagnostic

TB diagnostic testing intervention with configurable sensitivity and specificity

Key Features

  • Diagnostic Testing: Simulate TB testing with realistic parameters

  • Test Accuracy: Configurable sensitivity and specificity

  • False Negative Handling: Allow retesting with increased care-seeking

  • Coverage Control: Manage testing coverage rates

  • Result Tracking: Comprehensive diagnostic outcome monitoring

Usage Examples

Basic TB diagnostic:

from tbsim.interventions.tb_diagnostic import TBDiagnostic
from tbsim import TB

# Note: TBDiagnostic requires 'sought_care' and 'diagnosed' attributes
# These are typically added by health-seeking interventions
sim = ss.Sim(
    diseases=TB(),
    interventions=TBDiagnostic()
)
sim.run()

Custom diagnostic parameters:

diagnostic = TBDiagnostic(
    coverage=0.8,                    # 80% testing coverage
    sensitivity=0.85,                # 85% test sensitivity
    specificity=0.95,                # 95% test specificity
    care_seeking_multiplier=2.0      # 2x care-seeking after false negative
)

Key Methods

Diagnostic Management

  • step(): Execute diagnostic testing each time step

  • init_results(): Initialize diagnostic result tracking

  • update_results(): Update results during simulation

Testing Logic

  • Identifies eligible individuals (sought care, not diagnosed)

  • Applies coverage filters for testing selection

  • Determines TB status and applies test accuracy

  • Updates person states based on test results

  • Handles false negatives with retesting support

Test Parameters

Coverage: Fraction of care-seeking individuals who get tested Sensitivity: Probability of positive test given TB infection Specificity: Probability of negative test given no TB infection Care-seeking Multiplier: Increased health-seeking after false negatives

Diagnostic Outcomes

The module tracks: - Testing Volume: Number of tests performed - Test Results: Positive and negative outcomes - False Results: Inaccurate test results - Retesting: False negative handling and retesting - Diagnosis: Confirmed TB cases

For enhanced diagnostic capabilities, see the Enhanced TB Diagnostic Interventions module.