products

products

Products: vaccines, treatments, and diagnostics, and the protection people hold from them

A product says what something does (e.g. its efficacy), and a delivery (ss.vaccinate(), ss.treat(), ss.screen()) says who gets it and when. They are kept apart so that one product can be delivered in several ways. A product written as code (administer()) runs as agents.

Used with: agents and compartments; declared and coded modules

Classes

Name	Description
Diagnostic	A diagnostic test: what ss.screen() delivers
Effect	The effect of a product on one quantity, for the people who hold it: a multiplier of 1 - efficacy
EventSource	What a delivery and a product share as events: the people it reached on the step (screening), its outcomes (screening.positive), and their memory
Held	Base class for products that change rates for the people who hold them
Product	Generic product base class: see ss.Vaccine, ss.Diagnostic, and ss.Treatment
StrainEffect	The effect of a product against acquiring each strain of a disease with shared states, for the people who hold it: on each strain’s force of infection (see ss.solvers.Engine.strain_effect())
Treatment	A treatment: what ss.treat() delivers
Vaccine	A vaccine: what ss.vaccinate() delivers
boxcar	Protection that is full for a time (a plateau), then lost at once, or (with decay=) fading exponentially: the waning= of a product
held_cond	The condition vx.held (whether each person holds this product), which on a class is whether they hold any product of that kind (who=ss.Vaccine.held), for a model built before its products

Diagnostic

products.Diagnostic(
    sensitivity=1.0,
    specificity=1.0,
    outcomes=None,
    result_delay=None,
    detects=None,
    cost=None,
    name=None,
    label=None,
    **kwargs,
)

A diagnostic test: what ss.screen() delivers

A test gives each person one of its results: by default positive or negative, from sensitivity and specificity; or one of outcomes=, each with its probability given the state a person is in. Each outcome is a result of each delivery of it, and an event (screening.positive for one delivery, hiv_rdt.positive for any delivery of the product), which triggers the steps that follow.

Note: CRN safe as agents.

Parameters

Name	Type	Description	Default
sensitivity	float / dict	the probability that someone with the condition tests positive; a dict gives one for each state (each a number or an ss.by), and the test then detects being in those states. The states can be of several diseases ({hpv16.I: 0.9, 'hpv18.CIN': 0.95}), and the boolean states of a disease written as code ('hpv16.cin'); delivered with disease=[...], a state with no disease ('cin') is that state of each	1.0
specificity	float	the probability that someone without it tests negative	1.0
outcomes	dict	instead of sensitivity and specificity, the outcomes in order of severity, most severe first, each with its probability for people in each state (a dict by state, of any disease, as for sensitivity; a number is for those with what detects= says); the last is None, everyone the others do not take. A key None in a result’s dict is for people in none of the states keyed in any result (of any disease the test is keyed by), e.g. a false positive: it is counted once, whereas a result for a state (susceptible=0.1) is one for each disease. For someone in states of several diseases, there is a result for each disease, and the most severe of them is theirs (for a positive and a negative result, each disease is detected independently)	None
result_delay	dur / dict	the time from the test to its result (agents only); a dict gives one for each outcome. (The delay of a delivery’s when=ss.on(event, delay=...) is the time from its trigger to the test.)	None
detects	Cond / func	the condition the test detects (default: being in an infected state of the disease)	None
cost	float	the cost of each delivery	None
name	str	the name; if not given, taken from the variable the test is assigned to	None
label	str	the label, for plots and printing	None
kwargs	dict	passed to ss.Product

Examples

pcr = ss.Diagnostic(sensitivity=0.9, specificity=0.98, cost=4.00, result_delay=ss.days(2))
xpert = ss.Diagnostic(sensitivity=dict(symptomatic=0.91, asymptomatic=ss.by(age=[0.73, 0.78]))) # By state, and by age group within a state
hpv_dna = ss.Diagnostic(sensitivity={hpv16.I: 0.9, hpv16.CIN: 0.95, hpv18.I: 0.9}, specificity=0.97) # Across diseases
cytology = ss.Diagnostic(outcomes=dict(high_grade=dict(cin=0.9, cancer=1.0), ascus={'cin': 0.1, None: 0.1}, normal=None)) # ASCUS for 10% of people with neither CIN nor cancer

Attributes

Name	Description
diseases	The names of the diseases whose states it is keyed by
result_names	The names of its results from the least severe to the most (the order of tails()): for a positive and a negative result, negative first
tabulated	A test has no step of its own (its deliveries give it), so it does not stop a whole run in the kernels

Methods

Name	Description
delays	The delay of each result, from the least severe to the most (None for none)
key_by	Each disease’s states: a value for its infected (or for detects=) becomes one for the infected of each, and one by state, for that state of each that has it; a person’s result is the worst over the diseases
key_ref	A key of a dict by state, as (disease name, or None for the delivery’s; state name): a declared state, a state of a disease written as code (hpv16.cin, an ss.BoolState), or text ('hpv16.cin')
layout	The probability of each result but the least severe, as rows that each hold for some people: grouped by disease, whose
refs	The states of named diseases it is keyed by, as (disease, state), for tracking diseases jointly (see ss.solvers.JointStates)
severity	How severe the results of a row are, for ordering: the probability of each result or a more severe one, summed
state_keys	The states it is keyed by, as given
tables	The probability of each result but the least severe, from the next to the most severe, as {key: value}: a key is a state, None (people in none of the states), or ‘detects’ (people with what detects= says)
tails	The probability that each person’s result is each one or a more severe one, for each but the least severe (so for a
test_together	Diseases written as code that one delivery gives the test for (together, e.g. HPVsim’s genotypes), given the same values by

delays

products.Diagnostic.delays()

The delay of each result, from the least severe to the most (None for none)

key_by

products.Diagnostic.key_by(mods)

Each disease’s states: a value for its infected (or for detects=) becomes one for the infected of each, and one by state, for that state of each that has it; a person’s result is the worst over the diseases

key_ref

products.Diagnostic.key_ref(key)

A key of a dict by state, as (disease name, or None for the delivery’s; state name): a declared state, a state of a disease written as code (hpv16.cin, an ss.BoolState), or text ('hpv16.cin')

layout

products.Diagnostic.layout(sim, home)

The probability of each result but the least severe, as rows that each hold for some people: grouped by disease, whose states are exclusive, as {disease: [(state, [values])]} (and ‘detects’: [(None, [values])]); and the values for people in none of them. A state with no disease is one of home

refs

products.Diagnostic.refs()

The states of named diseases it is keyed by, as (disease, state), for tracking diseases jointly (see ss.solvers.JointStates)

severity

products.Diagnostic.severity(vals)

How severe the results of a row are, for ordering: the probability of each result or a more severe one, summed

state_keys

products.Diagnostic.state_keys()

The states it is keyed by, as given

tables

products.Diagnostic.tables()

The probability of each result but the least severe, from the next to the most severe, as {key: value}: a key is a state, None (people in none of the states), or ‘detects’ (people with what detects= says)

tails

products.Diagnostic.tails(selector, home, infected, together=None)

The probability that each person’s result is each one or a more severe one, for each but the least severe (so for a positive and a negative result, the probability of a positive one). For each disease, from the state they are in; combined over diseases as the worst result (P(worst ≥ k) = 1 − ∏(1 − P_d(≥ k)))

Parameters

Name	Type	Description	Default
selector	ss.conditions.Selector	the selector of the delivery’s disease	required
home	str	the delivery’s disease, for states given without one	required
infected	func	returns the infected states of home, which a test with no detects= detects	required
together	list	the names of diseases written as code that a delivery gives it for (disease=[...]), which are tested together (see test_together())	None

test_together

products.Diagnostic.test_together(groups, together=None)

Diseases written as code that one delivery gives the test for (together, e.g. HPVsim’s genotypes), given the same values by state (a test keyed by a state’s name, e.g. {'CIN': 0.9}), are one group, keyed by their names: a person is tested once, in the state that gives the most severe results (a woman with CIN of one genotype and susceptible to the others is tested as with CIN), rather than once for each disease

Effect

products.Effect(product, key, efficacy)

The effect of a product on one quantity, for the people who hold it: a multiplier of 1 - efficacy

Parameters

Name	Type	Description	Default
product	Product	the product	required
key	str	what it acts on, e.g. 'acquisition'	required
efficacy	float	the fraction of the quantity it removes	required

Attributes

Name	Description
constant	Whether the effect is the same at every step (so the tables need not be worked out step by step): a number for each group
tabulated	Whether the engines can work out the effect for every step before a run (see ss.solvers.Compartmental.tables()): unless the efficacy is a function of the sim

Methods

Name	Description
apply	The quantity (e.g. rel_sus, per agent or per state and group) scaled by 1 - efficacy for those who hold the product

apply

products.Effect.apply(value, engine)

The quantity (e.g. rel_sus, per agent or per state and group) scaled by 1 - efficacy for those who hold the product

EventSource

products.EventSource()

What a delivery and a product share as events: the people it reached on the step (screening), its outcomes (screening.positive), and their memory

Each is a condition that triggers a delivery (ss.treat(when=screening.positive)), and remembers per person whether (.ever), how often (.n_times), and how long ago (.since) it happened, including on the current step once the delivery that fired it has run. As agents, the memory of every event of a delivery is kept (two numbers per agent each), so it can be read after a run too, e.g. sim.interventions.screening.ever.uids; a product’s, and in a compartmental run (only .ever) any event’s, only if something in the sim reads it.

Attributes

Name	Description
event	The event itself (the people it reached on the step), as a condition
ever	Whether it has happened to each person, as a condition
n_times	How many times it has happened to each person
since	The time since it last happened to each person (infinite if never)

Methods

Name	Description
current	The people an event happened to on this step, as a selection for a module’s selector
fire	Record that an event happened to some people now: a boolean per agent, or the fraction of each state and group (as they were in before, if given)
flush	Put the people events happened to, up to and including time index ti, into the memory
init_events	Before a run: the people of each event on the current step, and the memory the sim needs (as agents, arrays of each person’s last time and count)
no_outcome	The error for a misspelled outcome
outcome_attr	An outcome as an event, e.g. screening.positive; called for an attribute that is not otherwise found
outcome_names	The names of its outcomes, e.g. [‘positive’, ‘negative’] for a test
reached	The UIDs of the people it reached on its last step (agents only), or of those with one of its outcomes (e.g. screening.reached('positive'))

current

products.EventSource.current(outcome, selector)

The people an event happened to on this step, as a selection for a module’s selector

While a delayed delivery reads its trigger (see ss.Event.delayed_arrivals()), selector.reading is (step, marks, new): the people of that step (this one or the one before) that it has not read yet, as marks says, with what it has now read put in new.

fire

products.EventSource.fire(outcome, sel, eng=None, before=None)

Record that an event happened to some people now: a boolean per agent, or the fraction of each state and group (as they were in before, if given)

flush

products.EventSource.flush(ti)

Put the people events happened to, up to and including time index ti, into the memory

init_events

products.EventSource.init_events(sim)

Before a run: the people of each event on the current step, and the memory the sim needs (as agents, arrays of each person’s last time and count)

no_outcome

products.EventSource.no_outcome(attr)

The error for a misspelled outcome

outcome_attr

products.EventSource.outcome_attr(attr)

An outcome as an event, e.g. screening.positive; called for an attribute that is not otherwise found

outcome_names

products.EventSource.outcome_names()

The names of its outcomes, e.g. [‘positive’, ‘negative’] for a test

reached

products.EventSource.reached(outcome=None)

The UIDs of the people it reached on its last step (agents only), or of those with one of its outcomes (e.g. screening.reached('positive'))

Its last step is the current one once it has run in it, and otherwise the one before: so code that runs after the interventions (a disease or an analyzer) reads the people of the step just taken, as for an event.

Parameters

Name	Type	Description	Default
outcome	str	the outcome (default: everyone reached)	None

Held

products.Held(
    efficacy=None,
    waning=None,
    doses=None,
    during=None,
    cost=None,
    name=None,
    label=None,
    **kwargs,
)

Base class for products that change rates for the people who hold them

Holding the product is a property of people, named after the product (e.g. has_bcg): a boolean per agent in an agent-based run, and a stratification in a compartmental one.

Parameters

Name	Type	Description	Default
efficacy	float / dict	protection; see ss.Vaccine	None
waning	dur / boxcar / func / dict	how protection is lost; see ss.Vaccine	None
doses	list	the relative efficacy after each dose; see ss.Vaccine	None
during	Cond	if given, it is held only while people are in these states	None
cost	float	the cost of each delivery	None
name	str	the name; if not given, taken from the variable it is assigned to	None
label	str	the label, for plots and printing	None
kwargs	dict	passed to ss.Product

Attributes

Name	Description
boxcar_form	The ss.boxcar that holding the product follows in a compartmental run (its waning, or the one waning of every effect that fades), or None
dim	The name of the property of people that says whether they hold the product
diseases	The names of the diseases the efficacy is keyed by, where they are given as modules (by name, they are known only in a sim: see disease_effects())
effects	The efficacy against each thing, as a dict
fades	Whether protection fades by a function of the time since delivery (or one for each effect)
held_frac	The fraction of the people in the same place who hold it, as a quantity in a rate, each counted by the protection they have left, e.g. itn.held_frac, or itn.held_frac(fn) by a function of the time since delivery (see ss.expressions.HeldFrac)
holds	Whether people hold this product, as opposed to it acting once when delivered
loses	Whether protection is lost at a random time (exponential waning, given as a duration), as opposed to fading by a function of time
tabulated	In a compartmental run, a product has no step of its own (its deliveries move people between levels of holding it), so it does not stop a whole run in the kernels

Methods

Name	Description
by_strain	An efficacy against acquisition by the strains of a disease with shared states (ss.by(strain=[...]), one per strain, or a dict by name): one for each strain, or None (for anything else)
check_dims	An efficacy by a dimension (ss.by(genotype=...)) that the people it acts on have no level of, such as a strain, which susceptibles do not carry, is an error
disease_effects	The efficacy against each thing, for each disease it acts on, as {disease name: {key: efficacy}}
init_pre	Work out what the product acts on, once: both the sim and its deliveries initialize it
key_by	The same efficacy against each disease, e.g. a bivalent vaccine delivered with disease=[hpv16, hpv18]
remaining	As agents: the fraction of protection left for each agent (by UID) who holds the product, by a function of the time since
step_waning	Called by its deliveries at the start of each step (it acts once per step): holders stop holding it once they leave the
waning_for	The function of the time since delivery by which the protection of one effect fades, or None

by_strain

products.Held.by_strain(eff, key, dis)

An efficacy against acquisition by the strains of a disease with shared states (ss.by(strain=[...]), one per strain, or a dict by name): one for each strain, or None (for anything else)

check_dims

products.Held.check_dims(eff, key, dis, states)

An efficacy by a dimension (ss.by(genotype=...)) that the people it acts on have no level of, such as a strain, which susceptibles do not carry, is an error

disease_effects

products.Held.disease_effects(sim)

The efficacy against each thing, for each disease it acts on, as {disease name: {key: efficacy}}

The efficacy is keyed by disease (dict(hpv16=0.95, hpv18=dict(cin=0.5)), each a number or a dict as for one disease), or is for the delivery’s disease.

init_pre

products.Held.init_pre(sim)

Work out what the product acts on, once: both the sim and its deliveries initialize it

Parameters

Name	Type	Description	Default
sim	Sim	the sim being initialized	required

key_by

products.Held.key_by(mods)

The same efficacy against each disease, e.g. a bivalent vaccine delivered with disease=[hpv16, hpv18]

remaining

products.Held.remaining(fn, holds, engine)

As agents: the fraction of protection left for each agent (by UID) who holds the product, by a function of the time since delivery: fn(t) or fn(t, sim, uids), with t a duration in the sim’s unit (e.g. ss.days, so t < ss.days(180) and t.years read the same in any sim), for the agents uids who hold it (so sim.people.age[uids] - t.years is their age when it was given)

Parameters

Name	Type	Description	Default
fn	func	the function of the time since delivery	required
holds	array	whether each agent holds the product	required
engine	Engine	the engine running the disease	required

step_waning

products.Held.step_waning()

Called by its deliveries at the start of each step (it acts once per step): holders stop holding it once they leave the states of during= (under every solver); and as agents, they lose protection at a constant rate (waning= a duration), or stop holding it once none is left (waning= a shape or function of time)

waning_for

products.Held.waning_for(key)

The function of the time since delivery by which the protection of one effect fades, or None

Product

products.Product(name=None, label=None, **kwargs)

Generic product base class: see ss.Vaccine, ss.Diagnostic, and ss.Treatment

Products represent diagnostic tests, treatments, or vaccines, delivered by ss.vaccinate(), ss.screen(), and ss.treat(). A product is an event too: the people any delivery of it reached on the step (cytology), with its outcomes (cytology.positive), and their memory (cytology.since): see ss.products.EventSource. A product whose effect is code of your own defines administer().

Methods

Name	Description
administer	The effect of a product written as code: called with the UIDs of the people a delivery gave it to on the step, after
agent_reasons	The reasons, if any, that this product needs agents
init_pre	Initialize the product, and its events, once: both the sim and its deliveries initialize it
key_by	For a delivery with disease= several diseases (a list or an ss.Strains): the product’s values as keyed by each, if they are not already (see the subclasses)
keyed_by	Whether a dict of values is keyed by diseases
step_waning	Called by its deliveries at the start of each step, before anyone is offered it: see ss.products.Held

administer

products.Product.administer(uids)

The effect of a product written as code: called with the UIDs of the people a delivery gave it to on the step, after what a product of its kind does (agents only). Override it in a subclass of ss.Product (or of ss.Vaccine etc.).

It may return the UIDs with each of its outcomes, as a dict (e.g. dict(positive=uids)): they are then results and events of the delivery, as a test’s are, which can trigger the steps that follow. The outcomes are those that outcome_names() lists.

Parameters

Name	Type	Description	Default
uids	array	the people who were given the product	required

Examples

class Bednet(ss.Product):
    def administer(self, uids):
        self.sim.diseases.malaria.rel_sus[uids] *= 0.5

agent_reasons

products.Product.agent_reasons(sim)

The reasons, if any, that this product needs agents

init_pre

products.Product.init_pre(sim)

Initialize the product, and its events, once: both the sim and its deliveries initialize it

Parameters

Name	Type	Description	Default
sim	Sim	the sim being initialized	required

key_by

products.Product.key_by(mods)

For a delivery with disease= several diseases (a list or an ss.Strains): the product’s values as keyed by each, if they are not already (see the subclasses)

keyed_by

products.Product.keyed_by(vals, mods)

Whether a dict of values is keyed by diseases

step_waning

products.Product.step_waning()

Called by its deliveries at the start of each step, before anyone is offered it: see ss.products.Held

StrainEffect

products.StrainEffect(product, key, efficacy)

The effect of a product against acquiring each strain of a disease with shared states, for the people who hold it: on each strain’s force of infection (see ss.solvers.Engine.strain_effect())

Methods

Name	Description
for_strain	The effect against one strain, as for any product

for_strain

products.StrainEffect.for_strain(strain)

The effect against one strain, as for any product

Treatment

products.Treatment(cure=None, efficacy=None, moves=None, **kwargs)

A treatment: what ss.treat() delivers

A treatment can cure (cure=, once, when it is given), change rates for as long as it is held (efficacy=), or both. By default it is given to the people who are infected. A treatment that cures has the outcomes cured, failed (infected, and not cured), and unneeded (not in a state it cures: not infected, or in no source of the transitions it cures along), which are results and events of its deliveries.

A cure is a probability (cure=0.9): the person leaves whichever infected state they are in for the state the disease’s recovery leads to. It can instead be a dict of probabilities, keyed in one of two ways:

• By state (cure=dict(I=0.9), or cure={hpv.CIN: 0.9}): the people in those states are cured, to the state the recovery leads to, and people in other states are not.
• By what cured people move along: transitions of the disease, usually ones with a rate of 0 (cure = A + C >> S @ 0), whose flows count the people moved (cure={syph.cure_early: 0.98, syph.cure_late: 0.95}); or a move written with the states (cure={I + CIN >> S: 0.9}), which no flow counts, e.g. for a cure to one of several states that recoveries lead to. Each person treated who is in a source of one of them moves along it with its probability (cured), or does not (failed); one in no source is unneeded. The transitions can be of several diseases (cure={ng.cure: 0.95, ct.cure: 0.95}); a modifier of such a transition (ss.modify(ng.cure, multiply=0.5, who=...)) multiplies the probability for the people it applies to. It is then given to the people in their sources.

A name as a key (cure=dict(cure=0.9)) is a state of the disease, or else one of its transitions (it is an error if it is both); 'ng.cure' is the transition cure of ng. What happens at failure (resistance) is a transition of the disease triggered by the outcome: ss.Transition(I, R_res, when=drug.failed, p=0.05).

Not every move a treatment makes is a cure: moves= names what it moves people along, for a treatment that, say, starts care or protects (moves=hiv.start_art, moves={sir.protect: 0.5}), with the probability cure= (1 by default) or one for each in a dict. It works as a cure by transition does, with the same outcomes.

Note: CRN safe as agents.

Parameters

Name	Type	Description	Default
cure	float / dict	the probability that treatment cures (1 if neither cure nor efficacy is given); or a dict of probabilities (each a number, an ss.by, a time series, or a function of the sim), by state or by transition, as above. For a disease written as code, the keys are its boolean states (e.g. dict(precin=0.9, cin=0.9)), each cured by its clear_infection()	None
efficacy	dict	the effects while it is held, as for ss.Vaccine (e.g. dict(transmission=0.96, mortality=0.9))	None
moves	Transition / str / list / dict	what it moves people along, instead of a cure by the disease’s recovery: transitions of the disease (by name too), or a move written with the states (e.g. I + CIN >> S); or a dict of the probability for each (otherwise cure, a number); a person must not be in the sources of two of one disease’s	None
waning	dur / boxcar / func / dict	as for ss.Vaccine, for the effects while held
during	Cond	as for ss.Vaccine: held (and its effects acting) only while people are in these states, e.g. during=typhoid.acute
cost	float	the cost of each delivery
name	str	the name; if not given, taken from the variable the treatment is assigned to

Examples

drug = ss.Treatment(cure=0.95, cost=120.0)
ablation = ss.Treatment(cure=dict(infected=0.936, cin=0.936)) # By state
drug = ss.Treatment(efficacy=dict(transmission=0.5), during=typhoid.acute) # Half as infectious while acute
art = ss.Treatment(efficacy=dict(transmission=0.96, mortality=0.9))
both = ss.Treatment(cure=0.3, efficacy=dict(transmission=0.9))
bpg = ss.Treatment(cure={syph.cure_early: 0.98, syph.cure_late: 0.95}) # A destination for each stage
ablation = ss.Treatment(cure={hpv.I + hpv.CIN >> hpv.S: 0.9}) # Cured to S, though its recoveries lead to S and R
kit = ss.Treatment(cure={ng.cure: 0.95, ct.cure: 0.95}) # Two diseases, one product
art = ss.Treatment(moves=hiv.start_art) # A move that is not a cure

Attributes

Name	Description
curing	Whether it moves people out of a state when given (a cure, or moves=), and so has the outcomes cured, failed, and unneeded
diseases	The names of the diseases whose transitions the treatment names (or, for one that changes rates, that its efficacy is keyed by)

Methods

Name	Description
along	With a cure by name only, those that are transitions of the disease rather than states: then what it moves people along
edge_disease	The name of the disease a transition (as given) belongs to, if it says: for a move written with the states, the disease of its destination
edge_specs	What it cures along, as given, each with its probability: (transition, move, or name, probability)
is_arrow	Whether a key of cure= is a move written with the states (e.g. I + CIN >> S), rather than a transition of the disease
key_by	A cure of each disease’s infected (and an efficacy against each, if it is held)
recovery	How a cured person leaves: the transition whose flow counts them (or None), the state they go to, and the states they leave
refs	The source states of the transitions it moves people along, as (disease, state), for tracking diseases jointly (see ss.solvers.JointStates)
resolve	What a treatment that cures moves people along in a sim: for each move, its disease, transition (or None, if no flow
resolve_each	The cure of each of the diseases a delivery gives (disease=[…])
split	A cure as (by state, by transition): a number or a dict by state name, or None; and a dict by transition (or move

along

products.Treatment.along(graph)

With a cure by name only, those that are transitions of the disease rather than states: then what it moves people along

edge_disease

products.Treatment.edge_disease(tr)

The name of the disease a transition (as given) belongs to, if it says: for a move written with the states, the disease of its destination

edge_specs

products.Treatment.edge_specs()

What it cures along, as given, each with its probability: (transition, move, or name, probability)

is_arrow

products.Treatment.is_arrow(tr)

Whether a key of cure= is a move written with the states (e.g. I + CIN >> S), rather than a transition of the disease

key_by

products.Treatment.key_by(mods)

A cure of each disease’s infected (and an efficacy against each, if it is held)

recovery

products.Treatment.recovery(dis)

How a cured person leaves: the transition whose flow counts them (or None), the state they go to, and the states they leave

A cure takes people out of whichever infected state they are in (the states counted in prevalence, and those that people infected reach on the way to the state cured people go to), never only the sources of one transition (a cure by transition moves people along transitions, from their own sources).

refs

products.Treatment.refs()

The source states of the transitions it moves people along, as (disease, state), for tracking diseases jointly (see ss.solvers.JointStates)

resolve

products.Treatment.resolve(sim, disease)

What a treatment that cures moves people along in a sim: for each move, its disease, transition (or None, if no flow counts it), destination, source states, and probability (a number, or a dict by state). Empty for one that does not cure.

Parameters

Name	Type	Description	Default
sim	ss.Sim	the sim	required
disease	str	the disease of a transition given by name alone, and of a cure by state	required

resolve_each

products.Treatment.resolve_each(sim)

The cure of each of the diseases a delivery gives (disease=[…])

split

products.Treatment.split(cure)

A cure as (by state, by transition): a number or a dict by state name, or None; and a dict by transition (or move written with the states, or a name with its disease), or None. A name alone is a state until the disease is known (see along())

Vaccine

products.Vaccine(efficacy=None, leaky=True, **kwargs)

A vaccine: what ss.vaccinate() delivers

How protection is lost, waning= (by default, never):

• A duration (e.g. ss.years(5)): lost all at once, after a time drawn from an exponential distribution with that mean.
• ss.boxcar(plateau=..., decay=...): full protection for a time, then (optionally) an exponential decline; under every solver.
• A function of the time since delivery, returning the fraction of protection that remains: fn(t) or fn(t, sim, uids), with t a duration (e.g. t < ss.days(180), t.years) and uids the agents who hold it (e.g. sim.people.age[uids] - t.years is their age when it was given); agents only.
• A dict, giving each effect its own of these (e.g. dict(acquisition=ss.boxcar(plateau=ss.years(1)), transmission=None)).

A vaccine that fades by a shape or function is held (vx.held) until no protection is left (as agents, e.g. at the end of a boxcar), and a delivery gives it again to those who hold it, restarting it. For other shapes under every solver (two rates in turn), write the protection as states and move people into them: see ss.Event.

Note: CRN safe as agents.

Parameters

Name	Type	Description	Default
efficacy	float / dict	protection against acquisition (required); or a dict of efficacy against each of ‘acquisition’ (scales rel_sus), ‘transmission’ (scales rel_trans), ‘mortality’ (scales the death transitions), or any named transition	None
waning	dur / boxcar / func / dict	how protection is lost, as above
doses	list	for a vaccine given in doses, the relative efficacy after each (e.g. [0.85, 1.0]); holding it then has a level per dose, and each delivery to someone who holds it gives them the next dose
leaky	bool	if True (the default), everyone who receives it is partly protected (by efficacy); if False, a fraction efficacy of them are fully protected and the rest not at all (“all or nothing”). The two give the same protection on average, but differ once people are exposed again and again: all or nothing leaves some never infected	True
during	Cond	if given, it is held only while people are in these states (e.g. during=sir.I): they stop holding it when they leave them
cost	float	the cost of each delivery
name	str	the name; if not given, taken from the variable the vaccine is assigned to

Examples

bcg = ss.Vaccine(efficacy=0.85, waning=ss.years(5), cost=12.50)
ss.Vaccine(efficacy=dict(acquisition=0.85, transmission=0.3))
mcv = ss.Vaccine(efficacy=0.85, leaky=False) # 85% fully protected
hpv = ss.Vaccine(efficacy=0.95, doses=[0.85, 1.0]) # The first dose gives 85% of the protection of two
bivalent = ss.Vaccine(efficacy=dict(hpv16=0.9975, hpv18=0.9975)) # Against two diseases
rtss = ss.Vaccine(efficacy=0.8, waning=ss.boxcar(plateau=ss.days(180), decay=ss.days(730))) # Full for 180 days, then declining
linear = ss.Vaccine(efficacy=0.9, waning=lambda t: np.clip(1 - t.years/5, 0, 1)) # Fading to nothing over 5 years

boxcar

products.boxcar(plateau, decay=None, stages=10)

Protection that is full for a time (a plateau), then lost at once, or (with decay=) fading exponentially: the waning= of a product

As agents, it is the fraction of protection left, t after delivery (1 for t < plateau, then exp(-(t - plateau)/decay), or 0). In a compartmental run, holding the product has levels: the plateau, as stages levels each left at stages/plateau (Erlang stages, so the end of the plateau is spread over about plateau/sqrt(stages)), then a level left at the rate 1/decay, so the fraction holding it falls as the protection of agents does.

Parameters

Name	Type	Description	Default
plateau	dur	how long protection is full	required
decay	dur	then, the e-folding time of its exponential decline (the mean time it lasts after the plateau); None (the default) for none: it ends with the plateau	None
stages	int	the number of levels of the plateau in a compartmental run	10

Examples

rtss = ss.Vaccine(efficacy=0.8, waning=ss.boxcar(plateau=ss.days(180), decay=ss.days(730)))
net = ss.Vaccine(efficacy=0.9, waning=ss.boxcar(plateau=ss.years(3))) # Full for three years, then none

Methods

Name	Description
levels	The levels of holding the product in a compartmental run, after “False”: the stages of the plateau, then decaying (if it does)
moves	The moves between those levels, each at a rate (as dur=, the mean time at a level)

levels

products.boxcar.levels()

The levels of holding the product in a compartmental run, after “False”: the stages of the plateau, then decaying (if it does)

moves

products.boxcar.moves(dim)

The moves between those levels, each at a rate (as dur=, the mean time at a level)

held_cond

products.held_cond()

The condition vx.held (whether each person holds this product), which on a class is whether they hold any product of that kind (who=ss.Vaccine.held), for a model built before its products

Functions

Name	Description
coded_states	The states of a disease written as code, by name: its boolean states (ss.BoolState), e.g. cin

coded_states

products.coded_states(dis)

The states of a disease written as code, by name: its boolean states (ss.BoolState), e.g. cin