interventions.base_interventions

interventions.base_interventions

Define interventions for STIsim

Classes

Name Description
ANCTest Multi-disease ANC visit testing, scheduled once per pregnancy.
PartnerNotification Notify and follow up sexual partners of index cases.
ProductMix Generic class for algorithms that determine which product a person will receive
STIDx Generic class for diagnostics with a positive/negative outcome
STITest Base class for STI testing.
STITreatment Base class for treatment of STI infection.
SymptomaticTesting Base class for symptomatic testing with multiple possible etiologies
SyndromicManagement Syndromic management of vaginal/urethral discharge syndromes.

ANCTest

interventions.base_interventions.ANCTest(
    visit_prob=0.85,
    disease_names=None,
    test_sensitivity=None,
    disease_treatment_map=None,
    newborn_tests=None,
    start=None,
    stop=None,
    name=None,
    label=None,
    **kwargs,
)

Multi-disease ANC visit testing, scheduled once per pregnancy.

When a woman becomes pregnant, schedules one ANC visit at a random gestational timepoint (months 1–7). At that visit she is tested for HIV and syphilis (auto-detected if present in the sim) plus any extra diseases listed in disease_names. visit_prob reflects ANC attendance: once she attends, all active disease tests are applied.

HIV positives have diagnosed / ti_diagnosed set, so ART links up automatically. Other diseases route positives to disease_treatment_map. Newborn/infant tests, if provided in newborn_tests, are scheduled on the unborn via the maternal network (sim must include ss.MaternalNet and ss.Pregnancy).

Parameters

Name Type Description Default
visit_prob float probability of attending ANC (default 0.85) 0.85
disease_names list extra diseases to test for; HIV and syphilis are auto-detected if present in the sim None
test_sensitivity dict per-disease sensitivity, e.g. {'hiv': 0.99}; default 1.0 for all None
disease_treatment_map dict maps disease name → treatment intervention; required for syphilis and any non-HIV disease None
newborn_tests dict maps disease name → newborn/infant test intervention (also added to sim.interventions), e.g. {'hiv': infant_hiv, 'syphilis': newborn_syph} None
start, stop, name, label standard required

Examples::

# Minimal: HIV + syphilis auto-detected, no newborn tests
anc = sti.ANCTest(
    visit_prob=0.85,
    disease_treatment_map={'syphilis': syph_tx},
)

# With newborn/infant tests
infant_hiv  = sti.InfantHIVTest(name='infant_hiv')
newborn_syph = sti.NewbornSyphTest(name='newborn_syph', ...)
anc = sti.ANCTest(
    visit_prob=0.85,
    disease_treatment_map={'syphilis': syph_tx},
    newborn_tests={'hiv': infant_hiv, 'syphilis': newborn_syph},
)
sim = ss.Sim(..., interventions=[anc, art, syph_tx, infant_hiv, newborn_syph])

PartnerNotification

interventions.base_interventions.PartnerNotification(
    eligibility,
    test=None,
    pars=None,
    **kwargs,
)

Notify and follow up sexual partners of index cases.

Each timestep, eligible index cases (e.g. newly diagnosed agents) have their partners identified across two channels:

  • Current partners: edges in the active sexual network.
  • Previous partners: edges in a :class:stisim.PriorPartners recall network — dissolved partnerships within the recall window.

Each contact is offered notification with probability p_notify_<scope>; notified contacts attend follow-up with probability p_attends_<scope>. Attendees are scheduled for the supplied test intervention on the next timestep. Index cases are not notified about themselves; partners reachable via both channels are not double-notified.

Parameters

Name Type Description Default
eligibility Callable f(sim) -> uids returning index cases (e.g. agents who just tested positive). required
test Test intervention to schedule for attending partners. Optional — subclasses overriding :meth:notify_attendees may set this to None. None
pars Optional dict of parameter overrides. None
**kwargs Forwarded to ss.Intervention. {}

Parameters (override via pars=... or kwargs): p_notify_current: ss.bernoulli for notifying current partners (default p=0.5). p_attends_current: ss.bernoulli for attendance given notification, current partners (default p=0.5). p_notify_previous: ss.bernoulli for notifying prior partners (default p=0.05). Set p=0 to disable the prior-partner channel. p_attends_previous: ss.bernoulli for attendance given notification, prior partners (default p=0.01). current_network: Name of the active sexual network (default 'structuredsexual'). previous_network: Name of the prior-partner network (default 'priorpartners'). Required if the prior channel is enabled.

Notes

  • To use the prior-partner channel, the active sexual network must have recall_prior=True so dissolved partnerships are pushed to PriorPartners.
  • For more elaborate downstream actions (e.g. setting treatment eligibility per partnership), subclass and override :meth:step.

Methods

Name Description
find_partners UIDs of partners of index_uids on network nw, deduplicated and
notify_attendees Hook called for partners attending follow-up. Default implementation
find_partners
interventions.base_interventions.PartnerNotification.find_partners(
    nw,
    index_uids,
)

UIDs of partners of index_uids on network nw, deduplicated and excluding any index case from being notified about themselves.

notify_attendees
interventions.base_interventions.PartnerNotification.notify_attendees(uids)

Hook called for partners attending follow-up. Default implementation schedules self.test for the attendees on the next timestep.

Override in subclasses to customise downstream actions — for instance, to apply syndromic treatment by partner sex, set treatment eligibility on a specific intervention, or send notifications to a registry.

ProductMix

interventions.base_interventions.ProductMix(df, excl_cols=None, *args, **kwargs)

Generic class for algorithms that determine which product a person will receive Uses ss.choice() sampling, which is slower than bernoulli, when there are more than two options The test that agents are given does NOT depend on their underlying health state.

Methods

Name Description
administer Apply a testing algorithm
administer
interventions.base_interventions.ProductMix.administer(sim, uids)

Apply a testing algorithm

STIDx

interventions.base_interventions.STIDx(df, disease, *args, **kwargs)

Generic class for diagnostics with a positive/negative outcome Uses bernoulli sampling, so can only be used for tests with binary outcomes Results vary depending on agents’ true underlying health state

Methods

Name Description
administer Administer a testing product.
administer
interventions.base_interventions.STIDx.administer(sim, uids)

Administer a testing product.

STITest

interventions.base_interventions.STITest(
    pars=None,
    test_prob_data=None,
    years=None,
    start=None,
    stop=None,
    eligibility=None,
    product=None,
    name=None,
    label=None,
    **kwargs,
)

Base class for STI testing.

Controls who gets tested, how often, and with what diagnostic product. Each timestep, eligible agents are tested with a probability derived from test_prob_data. By default (dt_scale=True), test_prob_data is interpreted as an annual testing probability and converted to a per-timestep probability via ss.probperyear. This correctly recovers the annual probability over a full year of timesteps (e.g. test_prob_data=0.24 with monthly dt gives ~2.26% per month, recovering exactly 24% per year).

If you need to specify a per-timestep probability directly (not an annual probability), set dt_scale=False: - test_prob_data=0.5, dt_scale=False → 50% chance per timestep

Parameters

Name Type Description Default
product diagnostic product (e.g. STIDx, HIVDx) that determines test outcomes (sensitivity, specificity). If None, subclasses supply a default (e.g. HIVTest uses a perfect HIVDx). For STITest, a product is required. None
test_prob_data annual testing probability (if dt_scale=True, the default) or per-timestep probability (if dt_scale=False). Accepts a scalar (constant probability), an array (one value per entry in years), or a DataFrame (subclass-specific, e.g. SymptomaticTesting accepts risk-group-stratified DataFrames). Default: 1.0 (test all eligible agents per year). None
years array calendar years corresponding to entries in test_prob_data when test_prob_data is an array. Mutually exclusive with start. None
start float calendar year when the intervention activates (inclusive). Defaults to the first simulation year. None
stop float calendar year when the intervention deactivates (inclusive). Defaults to the last simulation year. None
eligibility function f(sim) -> BoolArr or f(sim) -> UIDs defining who can be tested. Can filter on any agent property, e.g. lambda sim: sim.people.female & (sim.people.age > 15). Default: all agents (subclasses may override, e.g. HIVTest defaults to undiagnosed agents only). None
rel_test relative testing probability multiplier (default 1.0) required
dt_scale if True (default), interpret test_prob_data as an annual probability. Set to False to interpret test_prob_data as a per-timestep probability. required

States set on agents

tested (bool): ever tested diagnosed (bool): ever diagnosed positive ti_tested (float): timestep of last test ti_scheduled (float): timestep of next scheduled test ti_positive (float): timestep of last positive result ti_negative (float): timestep of last negative result tests (float): cumulative number of tests received

Attributes

Name Description
state_list Include products in the state list

Methods

Name Description
get_testers Find who tests by applying eligibility and coverage/uptake
make_test_prob_fn Testing probabilites over time
step Apply the testing intervention
get_testers
interventions.base_interventions.STITest.get_testers(sim)

Find who tests by applying eligibility and coverage/uptake

make_test_prob_fn
interventions.base_interventions.STITest.make_test_prob_fn(sim, uids)

Testing probabilites over time

step
interventions.base_interventions.STITest.step(uids=None)

Apply the testing intervention

STITreatment

interventions.base_interventions.STITreatment(
    name=None,
    pars=None,
    diseases=None,
    eligibility=None,
    max_capacity=None,
    years=None,
    *args,
    **kwargs,
)

Base class for treatment of STI infection. The majority of STI treatments will clear infection.

Parameters

Name Type Description Default
pars None
disease str should match the name of one of the diseases in the simulation required

Methods

Name Description
administer Administer treatment, keeping track of unnecessarily treated individuals
change_states Change the states of people who are treated
get_candidates Get people who are willing to accept treatment
set_treat_eff Can be changed by derived classes
step Apply treatment. On each timestep, this method will add eligible people who are willing to accept treatment to a
administer
interventions.base_interventions.STITreatment.administer(
    sim,
    uids,
    disease,
    return_format='dict',
)

Administer treatment, keeping track of unnecessarily treated individuals

change_states
interventions.base_interventions.STITreatment.change_states(disease, treat_succ)

Change the states of people who are treated

get_candidates
interventions.base_interventions.STITreatment.get_candidates(sim)

Get people who are willing to accept treatment

set_treat_eff
interventions.base_interventions.STITreatment.set_treat_eff(uids)

Can be changed by derived classes

step
interventions.base_interventions.STITreatment.step()

Apply treatment. On each timestep, this method will add eligible people who are willing to accept treatment to a queue, and then will treat as many people in the queue as there is capacity for.

SymptomaticTesting

interventions.base_interventions.SymptomaticTesting(
    pars=None,
    treatments=None,
    diseases=None,
    disease_treatment_map=None,
    negative_treatments=None,
    treat_prob_data=None,
    years=None,
    start=None,
    stop=None,
    eligibility=None,
    name=None,
    label=None,
    **kwargs,
)

Base class for symptomatic testing with multiple possible etiologies Unlike other test classes, this doesn’t return positive/negative outcomes, since syndromic management doesn’t involve reaching a diagnosis. Rather, the testing intervention itself contains a linked treatment intervention.

Methods

Name Description
step Apply syndromic management
step
interventions.base_interventions.SymptomaticTesting.step(uids=None)

Apply syndromic management

SyndromicManagement

interventions.base_interventions.SyndromicManagement(
    pars=None,
    treatments=None,
    diseases=None,
    cervical_diseases=None,
    outcome_tx_map=None,
    treat_prob_data=None,
    years=None,
    start=None,
    stop=None,
    eligibility=None,
    name=None,
    label=None,
    **kwargs,
)

Syndromic management of vaginal/urethral discharge syndromes.

When a symptomatic patient presents, they are probabilistically assigned one of four treatment outcomes based on whether they have a cervical infection (by default NG/CT) and their sex:

all3  — treated for cervical pathogens + TV/BV
ngct  — treated for cervical pathogens only
mtnz  — treated with metronidazole only (TV/BV)
none  — dismissed without treatment

Treatment probabilities for each outcome are given separately for females with cervical infection (tx_mix_cerv), females without (tx_mix_noncerv), and males (cervical column of tx_mix_cerv is reused for UDS). Each dict maps outcome name → [female_prob, male_prob].

The outcome_tx_map links each outcome to the treatment module(s) that should be triggered. Diagnostic accuracy (TP/FP/FN/TN) is recorded on any disease module that exposes those result keys.

Parameters

Name Type Description Default
treatments list treatment module instances None
diseases list disease modules to track accuracy for None
cervical_diseases list disease modules whose symptomatic flag indicates cervical infection; defaults to any disease named ‘ng’ or ‘ct’ in diseases None
outcome_tx_map dict maps outcome name → list of treatment modules; auto-constructed from treatments if omitted None
treat_prob_data unused; reserved for future time-varying tx prob None
years, start, stop, eligibility, name, label passed to STITest required

Examples::

syndromic = sti.SyndromicManagement(
    diseases=[ng, ct, tv, bv],
    treatments=[ng_tx, ct_tx, metronidazole],
    eligibility=seeking_care_vds,
)