resistance.dst
resistance.dst
Drug-susceptibility testing (DST) for multi-strain TB.
DST (product) produces an observed n-bit resistance profile from an agent’s carried strains, applying per-drug sensitivity/specificity at the strain level and an optional per-strain observation probability p_strain_obs (a within-host/culture bottleneck; default = strain fitness). DSTDelivery (intervention) administers it to eligible agents and stores the observed profile, which downstream treatment eligibility can read — either a single-drug callable (observed_resistant) or a composable multi-drug router (matches) for DST-dependent regimen selection.
Classes
| Name | Description |
|---|---|
| DST | Drug-susceptibility test. |
| DSTDelivery | Administers a DST to eligible agents and stores the observed resistance profile. |
DST
resistance.dst.DST(strains, sens=1.0, spec=1.0, p_strain_obs=None, **kwargs)Drug-susceptibility test.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| strains | Strains | the strain registry (e.g. tb.strains). |
required |
| sens | float / dict | per-drug sensitivity (P(observe resistant | strain is resistant)). Default 1. | 1.0 |
| spec | float / dict | per-drug specificity (P(observe susceptible | strain is susceptible)). Default 1. | 1.0 |
| p_strain_obs | None / float / dict | probability each carried strain is observed at all (culture bottleneck). None (default) uses the strain’s transmission fitness as a bacillary-load proxy. |
None |
Methods
| Name | Description |
|---|---|
| administer | Return the observed n-bit resistance profile (as an integer per agent) for uids. |
administer
resistance.dst.DST.administer(tb, uids)Return the observed n-bit resistance profile (as an integer per agent) for uids.
DST is applied at the strain level then aggregated to the agent phenotype: each carried strain is independently observed (culture bottleneck p_strain_obs), and each observed strain independently passes sensitivity (if truly resistant) or fails specificity (if susceptible). A drug is called resistant for an agent if any of its observed strains reads resistant — so a phenotype carried by several strains is more likely detected (spec §DST). The per-drug calls within one strain use independent CRN streams, so within a strain resistant to some modeled drugs and susceptible to others the test’s errors are independent across drugs (a multi-drug DST behaves like independent per-drug tests).
DSTDelivery
resistance.dst.DSTDelivery(
product,
eligibility=None,
result_validity=None,
**kwargs,
)Administers a DST to eligible agents and stores the observed resistance profile.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| product | DST | the DST product. | required |
| eligibility | callable | sim -> uids (default: active TB, alive, not yet tested). |
None |
| result_validity | ss.dur |
if set, a stored DST result older than this window is wiped each step (dst_tested reverts to False) so the agent must be re-tested before it is eligible again — the fix for perpetual re-treatment off a single stale test (L1). Default None = results never expire (previous behavior). |
None |
Methods
| Name | Description |
|---|---|
| matches | Return an eligibility callable selecting agents whose observed DST profile matches per_drug. |
| observed_resistant | Return a callable sim -> uids selecting agents observed resistant to drug (for treatment eligibility). |
matches
resistance.dst.DSTDelivery.matches(
require_tested=True,
exclude_on_treatment=True,
max_age=None,
require_active_tb=True,
**per_drug,
)Return an eligibility callable selecting agents whose observed DST profile matches per_drug.
E.g. matches(RIF=True, BDQ=False) selects observed-RIF-resistant, observed-BDQ-susceptible agents. The returned sim -> uids callable restricts to DST-tested (unless require_tested=False) and, unless exclude_on_treatment=False, not-currently-on-treatment agents. If require_active_tb is True (default), only agents who currently have active TB match — agents on treatment count as active here (they are being treated for active TB), so exclude_on_treatment alone governs whether they are kept (letting the treatment-monitoring pattern matches(..., exclude_on_treatment=False) select on-treatment agents). If max_age (ss.dur) is given, only agents whose result is within that window of the current step match (freshness gating; L1). Compose with TxDeliveryR(eligibility=..., supersedes=[...]) to route or switch regimens.
observed_resistant
resistance.dst.DSTDelivery.observed_resistant(
drug,
max_age=None,
require_active_tb=True,
)Return a callable sim -> uids selecting agents observed resistant to drug (for treatment eligibility).
If max_age (ss.dur) is given, only agents whose result is within that window of the current step are selected (freshness gating; L1). If require_active_tb is True (default), only currently active-TB agents are selected.