interventions.treatments
interventions.treatments
Treatment products and delivery for TB.
Classes
| Name | Description |
|---|---|
| DOTS | Standard DOTS (85% cure). |
| DOTSImproved | Enhanced DOTS (90% cure). |
| FirstLine | First-line combination therapy (95% cure). |
| SecondLine | Second-line therapy for MDR-TB (75% cure). |
| Tx | TB treatment product that encapsulates drug efficacy, duration, adherence, and relapse. |
| TxDelivery | Delivers a treatment product to eligible (diagnosed, active-TB) agents. |
| TxMulti | TB treatment product that supports more than one outcome (e.g. success, failure, partial). |
DOTS
interventions.treatments.DOTS(**kwargs)Standard DOTS (85% cure).
DOTSImproved
interventions.treatments.DOTSImproved(**kwargs)Enhanced DOTS (90% cure).
FirstLine
interventions.treatments.FirstLine(**kwargs)First-line combination therapy (95% cure).
SecondLine
interventions.treatments.SecondLine(**kwargs)Second-line therapy for MDR-TB (75% cure).
Tx
interventions.treatments.Tx(
efficacy=0.85,
dur_treatment=None,
adherence=0.85,
p_relapse=0.05,
dur_relapse=None,
drug_type=None,
**kwargs,
)TB treatment product that encapsulates drug efficacy, duration, adherence, and relapse.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| efficacy | Probability of cure given adherence (0-1). Default 0.85. | 0.85 |
|
| dur_treatment | Treatment duration distribution. Default 180 days. | None |
|
| adherence | Probability of completing the full course (0-1). Default 0.85. | 0.85 |
|
| p_relapse | Probability that a successfully cured agent relapses to active TB. Default 0.05 (matches drug_params['dots']['relapse_rate']). |
0.05 |
|
| dur_relapse | Distribution for time-to-relapse (days), measured from the end of successful treatment. Default constant 1.5 years. | None |
|
| drug_type | If provided (e.g. ‘dots’, ‘first_line_combo’), overrides efficacy, dur_treatment, adherence, and p_relapse with drug-specific values. | None |
Methods
| Name | Description |
|---|---|
| administer | Roll treatment outcomes for agents starting treatment. |
administer
interventions.treatments.Tx.administer(sim, uids)Roll treatment outcomes for agents starting treatment.
First rolls adherence (will they complete the course?), then rolls cure probability for adherent agents. Non-adherent agents are failures. Among successful agents, a subset is pre-rolled for future relapse.
Returns
| Name | Type | Description |
|---|---|---|
| dict with ‘success’, ‘failure’, and ‘relapse’ UIDs. | ||
| ‘relapse’ is a subset of ‘success’. |
TxDelivery
interventions.treatments.TxDelivery(
product,
eligibility=None,
reseek_multiplier=2.0,
reset_flags=True,
**kwargs,
)Delivers a treatment product to eligible (diagnosed, active-TB) agents.
Handles eligibility, treatment initiation via the TB module, success/failure outcomes from the product, and failure retry logic.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| product | A Tx product instance. | required | |
| eligibility | Callable (sim) -> uids. Default: diagnosed & active TB & alive. | None |
|
| reseek_multiplier | Care-seeking multiplier applied after treatment failure. Default 2.0. | 2.0 |
|
| reset_flags | Whether to reset diagnosed/tested flags after failure. Default True. | True |
Methods
| Name | Description |
|---|---|
| shrink | Remove temporary results |
| step | Coordinate everything that happens on the step; details are in methods below |
| step_check_completion | Find agents whose treatment course has completed this step |
| step_eligibility | Check agents for eligibility, and start treatment for those eligible |
| step_failures | Handle failures: return to prior TB state and trigger re-care-seeking |
| step_relapses | Trigger relapses for agents whose scheduled relapse time has arrived. |
| step_start_treatment | Start treatment for eligible agents. |
| step_success | Successful treatment clears infection and sets reinfection protection |
shrink
interventions.treatments.TxDelivery.shrink()Remove temporary results
step
interventions.treatments.TxDelivery.step()Coordinate everything that happens on the step; details are in methods below
step_check_completion
interventions.treatments.TxDelivery.step_check_completion()Find agents whose treatment course has completed this step
step_eligibility
interventions.treatments.TxDelivery.step_eligibility()Check agents for eligibility, and start treatment for those eligible
step_failures
interventions.treatments.TxDelivery.step_failures()Handle failures: return to prior TB state and trigger re-care-seeking
step_relapses
interventions.treatments.TxDelivery.step_relapses()Trigger relapses for agents whose scheduled relapse time has arrived.
Eligible pre-states: CLEARED (no active disease), INFECTION (latently reinfected, no active disease yet), NON_INFECTIOUS (early active TB). Agents in ASYMPTOMATIC, SYMPTOMATIC, or TREATMENT are silently dropped - they’re already on an active disease trajectory (or being treated), and forcing a state change would corrupt counters or pull them out of an active treatment course.
Relapsing agents return to SYMPTOMATIC active TB and have their diagnosed flag reset so they can be re-detected and re-treated.
step_start_treatment
interventions.treatments.TxDelivery.step_start_treatment()Start treatment for eligible agents.
Latent agents are cleared immediately. Active TB agents are put into TREATMENT state and their outcome (success/failure) is pre-rolled via the product, but not resolved until dur_treatment has elapsed.
step_success
interventions.treatments.TxDelivery.step_success()Successful treatment clears infection and sets reinfection protection
TxMulti
interventions.treatments.TxMulti(df, hierarchy=None, **kwargs)TB treatment product that supports more than one outcome (e.g. success, failure, partial).
Uses a DataFrame of state-to-outcome probabilities, just like Dx. See ProductMulti for full details on the df format.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| df | DataFrame with required columns (state, result, probability) and optional filter columns (age_min, age_max, hiv). | required | |
| hierarchy | List of result strings in priority order, e.g. [‘success’, ‘failure’]. | None |