products

products

HPV-specific Starsim products.

Contains

• hpv.vx: prophylactic vaccine product
• hpv.dx: per-genotype multinomial diagnostic classifier
• hpv.tx: per-genotype state-flip treatment product
• hpv.txvx: therapeutic vaccine product
• hpv.radiation: cancer treatment product

Classes

Name	Description
dx	HPV diagnostic product with per-genotype state classification.
radiation	HPV cancer-treatment product — extends ti_dead_cancer per cancerous module.
tx	HPV treatment product — per-genotype state-flip with efficacy draw.
txvx	HPV therapeutic vaccine — clears infection/lesions, then confers immunity.
vx	HPV multi-genotype prophylactic vaccine.

dx

products.dx(name=None, df=None, hierarchy=None, module_name=None, **kwargs)

HPV diagnostic product with per-genotype state classification.

Per-genotype rows in products_dx.csv are classified one genotype at a time; rows with genotype=‘all’ are collapsed across all HPV modules (susceptible iff susceptible-to-all; positive iff infected-with-any). Hierarchy-min semantics: when an agent is positive across multiple genotypes, the lowest-index (most severe) result wins.

radiation

products.radiation(dur=None, **kwargs)

HPV cancer-treatment product — extends ti_dead_cancer per cancerous module.

Default duration: normal(mean=18 months, sd=2 months), converted to years at construction.

tx

products.tx(name=None, df=None, module_name=None, **kwargs)

HPV treatment product — per-genotype state-flip with efficacy draw.

On successful treatment of state in {precin, cin, cancerous} on genotype g: module.[uids] = False module.cin[uids] = False module.precin[uids] = False module.cancerous[uids] = False module.ti_cin[uids] = NaN module.ti_cancerous[uids] = NaN module.ti_clearance[uids] = module.ti + 1 # cleared next module step module.to_latent[uids] = False # clears to susceptible

txvx

products.txvx(
    name=None,
    df=None,
    rel_imm=None,
    imm_init=None,
    imm_boost=None,
    module_name=None,
    **kwargs,
)

HPV therapeutic vaccine — clears infection/lesions, then confers immunity.

A treatment product, not a prophylactic. It flips per-genotype disease state through the same state x genotype efficacy table as hpv.tx (the txvx1/txvx2 rows of products_tx.csv), and additionally confers severity immunity via imm_init/imm_boost, scaled per target genotype by rel_imm (products_txvx.csv).

Named products reproduce the v2 defaults: txvx1 is a first dose conferring beta_mean(0.35, 0.025) immunity, txvx2 a booster multiplying existing immunity by 1.5.

Methods

Name	Description
administer	Clear disease state as hpv.tx does, then confer immunity.

administer

products.txvx.administer(uids, return_format='dict')

Clear disease state as hpv.tx does, then confer immunity.

vx

products.vx(
    name=None,
    rel_imm=None,
    sterilizing_p=0.95,
    module_name=None,
    **kwargs,
)

HPV multi-genotype prophylactic vaccine.

Constructed with EITHER name (looks up the per-genotype rel_imm from hpvsim/data/products_vx.csv) OR rel_imm (explicit per-genotype dict). Default product names: 'bivalent', 'quadrivalent', 'nonavalent'.

In practice almost all callers use name — the named products in the CSV cover the real-world vaccines. The explicit rel_imm dict is an escape hatch for ad-hoc / experimental products (e.g. a hypothetical vaccine, or sensitivity sweeps over cross-protection coefficients) and is rarely needed.

The vaccine model has two parameters:

• sterilizing_p (default 0.95): per-agent Bernoulli probability of sterilizing immunity, drawn ONCE per agent (not per genotype).
• rel_imm[g] from the CSV: per-genotype cross-protection coefficient. Sterilizing agents receive vax_imm[g] = rel_imm[g]; leaky agents receive vax_imm[g] = rel_imm[g] * sterilizing_p.

The effective per-genotype protection is approximately 0.9975 * rel_imm[g]. Existing vax_imm is never downgraded (max-of-existing semantics).

Vaccine immunity is written to vax_imm (NOT nab_imm). The CrossImmunity connector applies vax_imm directly per-genotype without flowing it through the cross-immunity matrix, so the CSV’s per-genotype rel_imm values are the complete vaccine cross-protection profile: vaccine immunity does not amplify into cross-protection against non-target genotypes.

Methods

Name	Description
administer	Apply the vaccine: per-agent all-or-nothing sterilizing draw,

administer

products.vx.administer(people, uids)

Apply the vaccine: per-agent all-or-nothing sterilizing draw, scaled per genotype by the CSV’s rel_imm cross-protection coefficient.

A single per-agent sterilizing Bernoulli at sterilizing_p (default 0.95), then per-genotype scaling by rel_imm[g] from products_vx.csv. rel_imm[g] is applied directly to vax_imm[g] as a multiplicative scalar on the per-agent peak.

For each vaccinated agent

• Sterilizing fate is drawn once at p=sterilizing_p (NOT per-genotype).
• For each genotype g:
  • Sterilizing agents: vax_imm[g] = rel_imm[g]
  • Non-sterilizing (leaky): vax_imm[g] = rel_imm[g] * sterilizing_p

Max-of-existing prevents vaccine from downgrading prior immunity.