interventions

interventions

HPV-specific Starsim interventions.

Contains the prophylactic vaccination intervention API: hpv.BaseVaccination (a subclass of ss.BaseVaccination that accepts age_range / sex / eligibility constructor args and composes them into a single Starsim eligibility callable) and the hpv.routine_vx / hpv.campaign_vx leaf classes that combine it with Starsim’s RoutineDelivery / CampaignDelivery.

Also provides screening (routine_screening / campaign_screening), triage (routine_triage / campaign_triage), treatment, dynamic_pars, and the txvx family (BaseTxVx / routine_txvx / campaign_txvx / linked_txvx).

Classes

Name	Description
BaseScreening	HPV-specific BaseScreening.
BaseTest	HPV-specific test/screening base.
BaseTreatment	HPV-specific treatment base.
BaseTriage	HPV-specific BaseTriage.
BaseTxVx	HPV therapeutic vaccination base.
BaseVaccination	HPV-specific prophylactic vaccination base.
campaign_screening	Campaign HPV screening.
campaign_triage	Campaign HPV triage.
campaign_txvx	Campaign therapeutic vaccination.
campaign_vx	Campaign-style prophylactic HPV vaccination.
dynamic_pars	Time-varying parameter editor.
linked_txvx	Therapeutic vaccination linked to another intervention’s outcomes.
routine_screening	Routine HPV screening.
routine_triage	Routine HPV triage.
routine_txvx	Routine therapeutic vaccination.
routine_vx	Routine prophylactic HPV vaccination.
treat_delay	Treat HPV+CIN+ agents after a fixed delay.
treat_num	Treat a fixed number of HPV+CIN+ agents each step (or all eligible if max_capacity=None).

BaseScreening

interventions.BaseScreening(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

HPV-specific BaseScreening.

Two differences from ss.BaseScreening:

• Records new_dx through :meth:_count_diagnosed instead of the upstream hardcoded self.outcomes['positive'], which KeyErrors for products whose result hierarchy uses other labels (cytology’s ascus/abnormal, or hpv_type’s positive_1618 / positive_ohr) when they are used as a primary screen. Behaviour for via/hpv (which do define 'positive') is unchanged.
• Renames the shipped n_screened / n_dx results to new_screens / new_dx. Both are per-step flows, and the n_-prefixed names collide with the ss.Result.annualize heuristic which reads n_* as a stock (averaged over sub-steps) rather than a flow (summed). The new_* names sum correctly.

BaseTest

interventions.BaseTest(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

HPV-specific test/screening base.

Adds age_range / sex / eligibility / debut_age kwargs, composed into a single Starsim eligibility callable via _compose_screening_eligibility. Overrides _parse_product_str so routine_screening(product=‘via’, …) resolves through hpv.dx(name=‘via’).

BaseTreatment

interventions.BaseTreatment(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    **kwargs,
)

HPV-specific treatment base.

Adds: - age_range / sex / eligibility kwargs - HPV-specific eligibility: female + alive + cancer-status-matched (cancer treatments require any-genotype cancerous; non-cancer treatments require no cancerous on any genotype) - Per-intervention state: cin_treated / cin_treatments / ti_cin_treated for CIN treatments, cancer_treated / etc. for cancer treatments

The treat_cancer flag is derived at init time from whether the product is an hpv.radiation instance.

Methods

Name	Description
check_eligibility	Alive + sex + age_range [lo, hi) + cancer-status match.
step	Reset per-step outcomes before delegating to the treatment step.

check_eligibility

interventions.BaseTreatment.check_eligibility()

Alive + sex + age_range [lo, hi) + cancer-status match.

step

interventions.BaseTreatment.step()

Reset per-step outcomes before delegating to the treatment step.

BaseTriage

interventions.BaseTriage(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

HPV-specific BaseTriage.

Overrides ss.BaseTriage.step to use integer-ti membership (the same pattern ss.BaseScreening uses correctly). Upstream Starsim 3.3.4 has a TODO on its triage step using sim.t in timepoints which silently fails under quarterly dt because sim.t is a freq object, not an int.

Also mirrors ss.BaseScreening’s per-step bookkeeping: records screened, screens, and ti_screened so that downstream eligibility callbacks (and test assertions) can inspect who was triaged.

BaseTxVx

interventions.BaseTxVx(*args, **kwargs)

HPV therapeutic vaccination base.

Extends BaseTreatment with txvx-specific per-intervention state: tx_vaccinated / txvx_doses / ti_tx_vaccinated.

Note: BaseTxVx inherits the cin_treated / cancer_treated / etc. states from BaseTreatment. These remain all-zero on txvx interventions (radiation never matches, no CIN treatment happens here). They’re a small memory + introspection cost in exchange for keeping the BaseTreatment state-definition path single-sourced.

Delivery clears infection/lesions and confers severity immunity via hpv.txvx.administer (a treatment product). The intervention’s own dose counters track program-level uptake.

Methods

Name	Description
check_eligibility	TxVx eligibility — alive + sex + age range [lo, hi) + cancer-free.
deliver	One-step delivery — finds accepters, administers, bumps counters.

check_eligibility

interventions.BaseTxVx.check_eligibility()

TxVx eligibility — alive + sex + age range [lo, hi) + cancer-free.

Overrides BaseTreatment.check_eligibility to hard-gate on the cancer-free arm regardless of the inherited treat_cancer flag. Therapeutic vaccines are never given to cancer patients (radiation is for that path); a non-radiation txvx product on a routine_txvx would still set treat_cancer=False through the BaseTreatment init, but pinning the cancer-free condition here makes the semantics explicit and resilient to product-type confusion.

Sex follows sex= (default 'f') rather than being hardcoded to female, so sex=['f','m'] really does include men.

deliver

interventions.BaseTxVx.deliver()

One-step delivery — finds accepters, administers, bumps counters.

BaseVaccination

interventions.BaseVaccination(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    **kwargs,
)

HPV-specific prophylactic vaccination base.

Wraps Starsim’s ss.BaseVaccination to add age_range / sex / eligibility constructor args. These compose into a single Starsim eligibility callable. The originals are stored on the instance for introspection (e.g. by_age consumption).

Also overrides _parse_product_str so that routine_vx(product='bivalent', ...) resolves through hpv.vx(name='bivalent').

Methods

Name	Description
init_results	Dose time series, mirroring the screening/treatment results.

init_results

interventions.BaseVaccination.init_results()

Dose time series, mirroring the screening/treatment results.

new_vaccinated counts first doses only; new_doses counts every dose. Both are scale=True, so they come out in real-population units. The cum_* pair is filled in :meth:finalize_results.

campaign_screening

interventions.campaign_screening(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

Campaign HPV screening.

campaign_triage

interventions.campaign_triage(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

Campaign HPV triage.

campaign_txvx

interventions.campaign_txvx(*args, **kwargs)

Campaign therapeutic vaccination.

campaign_vx

interventions.campaign_vx(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    **kwargs,
)

Campaign-style prophylactic HPV vaccination.

dynamic_pars

interventions.dynamic_pars(pars=None, interpolate=True, **kwargs)

Time-varying parameter editor.

pars: dict mapping dotted-path strings to {‘years’: […], ‘vals’: […]} schedules. Each step, the resolved parameter is set to the interpolated (default) or stepwise (interpolate=False) value for the current year.

Dotted-path resolution order: sim.diseases > sim.interventions > sim.pars. Schedule keys are epoch years (e.g. 2020, 2030) — np.interp clamps to the first / last value outside the schedule.

linked_txvx

interventions.linked_txvx(*args, eligibility=None, **kwargs)

Therapeutic vaccination linked to another intervention’s outcomes.

Has no own timeline. Fires every step; eligibility= callback (required) determines who actually receives the dose. Typical usage:

linked = hpv.linked_txvx(
    product='txvx1', prob=0.6,
    eligibility=lambda s: s.interventions['colpo'].outcomes['lsil'],
)

routine_screening

interventions.routine_screening(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

Routine HPV screening.

routine_triage

interventions.routine_triage(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    debut_age=None,
    **kwargs,
)

Routine HPV triage.

routine_txvx

interventions.routine_txvx(*args, **kwargs)

Routine therapeutic vaccination.

routine_vx

interventions.routine_vx(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    **kwargs,
)

Routine prophylactic HPV vaccination.

treat_delay

interventions.treat_delay(delay=None, **kwargs)

Treat HPV+CIN+ agents after a fixed delay.

On each step

1. Newly-eligible accepters are enqueued at due_ti = self.ti + round(delay / dt).
2. Agents whose due_ti is the current ti are treated.

delay is in years. Scheduler keys are integer ti so timing is exact under any dt; the round() picks the nearest integer step for non-integer (delay / dt) ratios.

treat_num

interventions.treat_num(
    *args,
    age_range=None,
    sex='f',
    eligibility=None,
    **kwargs,
)

Treat a fixed number of HPV+CIN+ agents each step (or all eligible if max_capacity=None).