resistance.strains
resistance.strains
Strain registry for multi-strain (drug-resistance) TB.
A strain is an n-bit resistance profile over a fixed, ordered set of drugs (bit i = resistant to drug i). For n drugs there are m = 2**n possible strains, enumerated as integer ids 0..m-1 (id 0 = pan-susceptible).
An agent carries a subset of the m strains, stored elsewhere as a single integer strain_mask (bit j set = carries strain j); see tbsim.resistance.TBResistant. This registry holds the strain-level lookups (fitness, resistance profiles, labels) and the bit helpers used to reason about masks.
The two-strain reference ODE (tbsim.compartmental.TwoStrainODE) is the n=1 special case: drugs=['TX'] gives strain 0 = A (susceptible) and strain 1 = B (resistant).
Classes
| Name | Description |
|---|---|
| Strains | Registry of the possible strains for a given drug set. |
Strains
resistance.strains.Strains(drugs, rel_fitness=None)Registry of the possible strains for a given drug set.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| drugs | list | ordered drug/class names; index = resistance bit position, e.g. ['RIF', 'BDQ'] (or ['TX'] for the two-strain reference). |
required |
| rel_fitness | dict | per-drug multiplicative transmission fitness cost r_i in [0, 1], e.g. {'RIF': 0.5}. Drugs absent from the dict have no cost (r_i = 1). A strain’s fitness is the product of the costs of the drugs it is resistant to (pan-susceptible = 1.0). |
None |
Attributes
| Name | Type | Description |
|---|---|---|
| n | int | number of drugs. |
| m | int | number of possible strains (2**n). |
| profile | np.ndarray | (m, n) bool; profile[j, i] = strain j resistant to drug i. |
| fitness | np.ndarray | length-m float; per-strain transmission fitness. |
| labels | list | length-m human-readable strain labels (e.g. 'pan', 'RIF+FQ'). |
Methods
| Name | Description |
|---|---|
| add_resistance | Return the strain id(s) obtained by adding resistance to drug. |
| carried | Decode agent strain masks into a boolean membership matrix. |
| covered | (m,) bool: strain j is covered by regimen_drugs iff it is susceptible to every |
| covered_mask | Bitmask over strain ids of the strains covered by regimen_drugs (see :meth:covered). |
| drug_bit | Resistance-profile bit (within a strain id) for a drug name. |
| max_fitness | Per-agent maximum strain fitness over carried strains (0 if none carried). |
| phenotype_any | Aggregate observed resistance phenotype per agent: OR of the resistance |
| resistant_frac | Fraction of the given (infected) agents whose aggregate phenotype is resistant to drug. |
| transmit_probs | Per-agent probability of transmitting each strain, \propto count × fitness over |
| validate_drugs | Raise ValueError if any name in names (iterable of drug names, e.g. a list or the keys |
add_resistance
resistance.strains.Strains.add_resistance(strain_ids, drug)Return the strain id(s) obtained by adding resistance to drug.
carried
resistance.strains.Strains.carried(mask)Decode agent strain masks into a boolean membership matrix.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mask | array | per-agent strain_mask integers. |
required |
Returns
| Name | Type | Description |
|---|---|---|
(len(mask), m) bool; [k, j] = agent k carries strain j. |
covered
resistance.strains.Strains.covered(regimen_drugs)(m,) bool: strain j is covered by regimen_drugs iff it is susceptible to every drug in the regimen (so a regimen with no drugs covers nothing to be resistant to = all strains). Used by TPT / latent-treatment sterilization.
covered_mask
resistance.strains.Strains.covered_mask(regimen_drugs)Bitmask over strain ids of the strains covered by regimen_drugs (see :meth:covered).
drug_bit
resistance.strains.Strains.drug_bit(drug)Resistance-profile bit (within a strain id) for a drug name.
max_fitness
resistance.strains.Strains.max_fitness(mask)Per-agent maximum strain fitness over carried strains (0 if none carried).
phenotype_any
resistance.strains.Strains.phenotype_any(mask)Aggregate observed resistance phenotype per agent: OR of the resistance profiles over all carried strains.
Returns
| Name | Type | Description |
|---|---|---|
(len(mask), n) bool; [k, i] = agent k carries some strain resistant to drug i. |
resistant_frac
resistance.strains.Strains.resistant_frac(mask, drug)Fraction of the given (infected) agents whose aggregate phenotype is resistant to drug.
transmit_probs
resistance.strains.Strains.transmit_probs(mask, counts=None)Per-agent probability of transmitting each strain, \propto count × fitness over carried strains (the spec’s r_j / \sum r, generalized so an agent carrying multiple copies of a strain is proportionally more likely to pass it). Rows for uninfected agents (mask 0) are left all-zero. The overall per-contact transmission probability (rel_trans = max fitness) does not depend on counts — only the which-strain split does.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mask | array | per-agent strain_mask integers. |
required |
| counts | array | optional (len(mask), m) per-strain multiplicity. If None, every carried strain is weighted as a single copy (fitness-only, the pre-counter behavior). |
None |
Returns
| Name | Type | Description |
|---|---|---|
(len(mask), m) float, each infected row summing to 1. |
validate_drugs
resistance.strains.Strains.validate_drugs(names, where='')Raise ValueError if any name in names (iterable of drug names, e.g. a list or the keys of a per-drug dict) is not a known drug — fail-fast on typos that otherwise resolve silently via .get() (L8). where labels the call site in the message.
Example::
strains.validate_drugs(['RIF', 'BDQ'], where='TxR.regimen_drugs')