interventions.tpt

interventions.tpt

Tuberculosis Preventive Therapy (TPT): Product + Delivery.

TPTTx — treatment product (biological effect, per-agent state) TPTSimple — simple delivery (targets latently infected by default) TPTHousehold — household contact tracing delivery (legacy) HouseholdContactTracing — identifies household contacts of new treatment cases TPTDelivery — delivers TPT to screened contacts without active disease

Classes

Name	Description
HouseholdContactTracing	Identifies household contacts of agents who newly start TB treatment.
TPTDelivery	Delivers TPT to household contacts who were screened and found NOT to
TPTHousehold	Household contact tracing TPT delivery.
TPTSimple	Simple TPT delivery targeting latently infected agents.
TPTTx	TPT treatment product with sterilization and suppression mechanisms.

HouseholdContactTracing

interventions.tpt.HouseholdContactTracing(coverage=0.8, disease='tb', **kwargs)

Identifies household contacts of agents who newly start TB treatment.

Sets contact_identified=True on household members of followed-up index cases. Downstream interventions (e.g. DxDelivery for screening, TPTDelivery for preventive therapy) read this flag.

Requires a household network with household_ids (e.g. ss.HouseholdNet).

Parameters

Name	Type	Description	Default
coverage	float	Probability that a given index case’s household is followed up (per-index-case Bernoulli). Default 0.8.	`0.8`
disease	str	Key of the TB disease module. Default `'tb'`.	`'tb'`

Methods

Name	Description
find_household_net	Find the network that has `household_ids`.
step	Detect new treatment starts, trace household contacts, set flags.

find_household_net

interventions.tpt.HouseholdContactTracing.find_household_net()

Find the network that has household_ids.

step

interventions.tpt.HouseholdContactTracing.step()

Detect new treatment starts, trace household contacts, set flags.

TPTDelivery

interventions.tpt.TPTDelivery(
    product=None,
    contact_tracing='householdcontacttracing',
    contact_screen='contact_screen',
    result_state='diagnosed',
    **kwargs,
)

Delivers TPT to household contacts who were screened and found NOT to have active disease.

Reads flags from HouseholdContactTracing (contact_identified) and a screening DxDelivery (tested and result state) to determine eligibility: contacts who were identified, screened, and not diagnosed with active TB.

Parameters

Name	Type	Description	Default
product	TPTTx	The TPT treatment product. Created automatically if not provided.	`None`
contact_tracing	str	Name of the `HouseholdContactTracing` intervention. Default `'householdcontacttracing'`.	`'householdcontacttracing'`
contact_screen	str	Name of the screening `DxDelivery` intervention. Default `'contact_screen'`.	`'contact_screen'`
result_state	str	The result state name on the screening DxDelivery that indicates a positive (active TB) result. Default `'diagnosed'`.	`'diagnosed'`

Methods

Name	Description
step	Deliver TPT to eligible contacts; manage product lifecycle.

step

interventions.tpt.TPTDelivery.step()

Deliver TPT to eligible contacts; manage product lifecycle.

TPTHousehold

interventions.tpt.TPTHousehold(product=None, pars=None, **kwargs)

Household contact tracing TPT delivery.

Detects new TB treatment starts each step, traces household contacts of followed-up index cases, and offers TPT to all contacts (product handles eligibility filtering).

Requires a household network with household_ids (e.g. ss.HouseholdNet).

Parameters

Name	Type	Description	Default
product	TPTTx	The TPT treatment product (created automatically if not provided).	`None`
pars	dict	Overrides. `coverage` controls the probability that a given index case’s household is followed up (per-index-case Bernoulli).	`None`

Methods

Name	Description
check_eligibility	Detect new treatment starts → follow up index cases → trace
find_household_net	Find the network that has `household_ids`.
shrink	Delete link to household net
update_results	Record number of currently protected individuals.

check_eligibility

interventions.tpt.TPTHousehold.check_eligibility()

Detect new treatment starts → follow up index cases → trace household contacts.

find_household_net

interventions.tpt.TPTHousehold.find_household_net()

Find the network that has household_ids.

shrink

interventions.tpt.TPTHousehold.shrink()

Delete link to household net

update_results

interventions.tpt.TPTHousehold.update_results()

Record number of currently protected individuals.

TPTSimple

interventions.tpt.TPTSimple(product=None, pars=None, **kwargs)

Simple TPT delivery targeting latently infected agents.

Thin wrapper over :class:TBProductRoutine that defaults to targeting agents in TBS.INFECTION state (latent TB). Creates a :class:TPTTx product automatically if none is provided.

Parameters

Name	Type	Description	Default
product	TPTTx	The TPT treatment product (created automatically if not provided).	`None`
pars	dict	Overrides for delivery parameters (`coverage`, `age_range`, `eligible_states`, `start`, `stop`).	`None`

Example::

import starsim as ss
import tbsim
from tbsim.interventions.tpt import TPTSimple

tb  = tbsim.TB(name='tb')
tpt = TPTSimple()
sim = ss.Sim(diseases=tb, interventions=tpt, pars=dict(start='2000', stop='2020'))
sim.run()

Methods

Name	Description
update_results	Record number of currently protected individuals.

update_results

interventions.tpt.TPTSimple.update_results()

Record number of currently protected individuals.

TPTTx

interventions.tpt.TPTTx(pars=None, **kwargs)

TPT treatment product with sterilization and suppression mechanisms.

TPT efficacy is modeled in two stages:

efficacy determines whether TPT works at all for a given agent.
Among efficacious agents, p_sterilize determines who gets sterilization (infection cleared) vs suppression (risk reduction via rr_* modifiers). These are mutually exclusive.

Parameters

Name	Type	Description	Default
disease	str	Key of the disease module to target (default `'tb'`).	required
efficacy	`ss`.bernoulli	Probability that TPT works (default 0.6).	required
p_sterilize	`ss`.bernoulli	Among efficacious agents, probability of sterilization vs suppression (default 0.0 = all suppression).	required
dur_treatment	`ss`.Dist	Duration of the antibiotic course (default 3 months).	required
dur_protection	`ss`.Dist	Duration of post-treatment protection (default 2 years).	required
activation_modifier / clearance_modifier / death_modifier	`ss`.Dist	Per-individual risk-modifier distributions (suppression only).	required
exclude_on_treatment	bool	If True, skip agents currently on TB treatment (default True).	required

Methods

Name	Description
administer	Start TPT for uids.
apply_protection	Multiply `rr_*` arrays for all currently protected (suppression) agents.
update_roster	Handle treatment completion by mechanism:

administer

interventions.tpt.TPTTx.administer(people, uids)

Start TPT for uids.

Filters out ineligible agents, rolls mechanism assignment (sterilization / suppression / neither), schedules treatment duration, and samples rr_* modifiers for suppression agents.

Returns

Name	Type	Description
		ss.uids: UIDs of agents who actually started TPT.

apply_protection

interventions.tpt.TPTTx.apply_protection()

Multiply rr_* arrays for all currently protected (suppression) agents.

update_roster

interventions.tpt.TPTTx.update_roster()

Handle treatment completion by mechanism:

Sterilization: clear infection (INFECTION → CLEARED) if agent is still latently infected.
Suppression: start rr_* protection phase.
Neither: no action.

Also expires protection for suppression agents past their window.