interventions
Specify the core interventions. Other interventions can be defined by the user by inheriting from these classes.
Classes
| Name | Description |
|---|---|
| BaseScreening | Base class for screening. |
| BaseTest | Base class for screening and triage. |
| BaseTreatment | Base treatment class. |
| BaseTriage | Base class for triage. |
| BaseTxVx | Base class for therapeutic vaccination |
| BaseVaccination | Base vaccination class for determining who will receive a vaccine. |
| CampaignDelivery | Base class for any intervention that uses campaign delivery; handles interpolation of input years. |
| EventSchedule | Run functions on different days |
| Intervention | Base class for interventions. |
| RoutineDelivery | Base class for any intervention that uses routine delivery; handles interpolation of input years. |
| campaign_screening | Campaign screening - an instance of base screening combined with campaign delivery. |
| campaign_triage | Campaign triage - an instance of base triage combined with campaign delivery. |
| campaign_txvx | Campaign delivery of therapeutic vaccine - an instance of treat_num combined |
| campaign_vx | Campaign vaccination - an instance of base vaccination combined with campaign delivery. |
| dx | Testing products are used within screening and triage. Their fundamental property is that they classify people |
| dynamic_pars | A generic intervention that modifies a set of parameters at specified points |
| linked_txvx | Deliver therapeutic vaccine. This intervention should be used if TxVx delivery |
| routine_screening | Routine screening - an instance of base screening combined with routine delivery. |
| routine_triage | Routine triage - an instance of base triage combined with routine delivery. |
| routine_txvx | Routine delivery of therapeutic vaccine - an instance of treat_num combined |
| routine_vx | Routine vaccination - an instance of base vaccination combined with routine delivery. |
| treat_delay | Treat people after a fixed delay |
| treat_num | Treat a fixed number of people each timestep. |
| tx | Treatment products include anything used to treat cancer or precancer, as well as therapeutic vaccination. |
| vx | Vaccine product |
BaseScreening
interventions.BaseScreening(age_range=None, **kwargs)Base class for screening.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| age_range (list/tuple/arr) | age range for screening, e.g. [30,50] | required | |
| kwargs (dict) | passed to BaseTest | required |
Methods
| Name | Description |
|---|---|
| apply | Perform screening by finding who’s eligible, finding who accepts, and applying the product. |
| check_eligibility | Return an array of indices of agents eligible for screening at time t, i.e. sexually active |
apply
interventions.BaseScreening.apply(sim)Perform screening by finding who’s eligible, finding who accepts, and applying the product.
check_eligibility
interventions.BaseScreening.check_eligibility(sim)Return an array of indices of agents eligible for screening at time t, i.e. sexually active females in age range, plus any additional user-defined eligibility, which often includes the screening interval.
BaseTest
interventions.BaseTest(product=None, prob=None, eligibility=None, **kwargs)Base class for screening and triage.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| product (str/Product) | the diagnostic to use | required | |
| prob (float/arr) | annual probability of eligible women receiving the diagnostic | required | |
| eligibility (inds/callable) | indices OR callable that returns inds | required | |
| label (str) | the name of screening strategy | required | |
| kwargs (dict) | passed to Intervention() | required |
Methods
| Name | Description |
|---|---|
| deliver | Deliver the diagnostics by finding who’s eligible, finding who accepts, and applying the product. |
deliver
interventions.BaseTest.deliver(sim)Deliver the diagnostics by finding who’s eligible, finding who accepts, and applying the product.
BaseTreatment
interventions.BaseTreatment(
product=None,
prob=None,
eligibility=None,
age_range=None,
**kwargs,
)Base treatment class.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| product (str/Product) | the treatment product to use | required | |
| accept_prob (float/arr) | acceptance rate of treatment - interpreted as the % of women eligble for treatment who accept | required | |
| eligibility (inds/callable) | indices OR callable that returns inds | required | |
| label (str) | the name of treatment strategy | required | |
| kwargs (dict) | passed to Intervention() | required |
Methods
| Name | Description |
|---|---|
| apply | Perform treatment by getting candidates, checking their eligibility, and then treating them. |
| check_eligibility | Check people’s eligibility for treatment |
| get_accept_inds | Get indices of people who will acccept treatment; these people are then added to a queue or scheduled for receiving treatment |
| get_candidates | Get candidates for treatment on this timestep. Implemented by derived classes. |
apply
interventions.BaseTreatment.apply(sim)Perform treatment by getting candidates, checking their eligibility, and then treating them.
check_eligibility
interventions.BaseTreatment.check_eligibility(sim)Check people’s eligibility for treatment
get_accept_inds
interventions.BaseTreatment.get_accept_inds(sim)Get indices of people who will acccept treatment; these people are then added to a queue or scheduled for receiving treatment
get_candidates
interventions.BaseTreatment.get_candidates(sim)Get candidates for treatment on this timestep. Implemented by derived classes.
BaseTriage
interventions.BaseTriage(age_range=None, **kwargs)Base class for triage.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kwargs | dict | passed to BaseTest | {} |
BaseTxVx
interventions.BaseTxVx(**kwargs)Base class for therapeutic vaccination
Methods
| Name | Description |
|---|---|
| deliver | Deliver the intervention. This applies on a single timestep, whereas apply() methods |
deliver
interventions.BaseTxVx.deliver(sim)Deliver the intervention. This applies on a single timestep, whereas apply() methods apply on every timestep and can selectively call this method.
BaseVaccination
interventions.BaseVaccination(
product=None,
prob=None,
age_range=None,
sex=None,
eligibility=None,
label=None,
**kwargs,
)Base vaccination class for determining who will receive a vaccine.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| product (str/Product) | the vaccine to use | required | |
| prob (float/arr) | annual probability of eligible population getting vaccinated | required | |
| age_range (list/tuple) | age range to vaccinate | required | |
| sex (int/str/list) | sex to vaccinate - accepts 0/1 or ‘f’/‘m’ or a list of both | required | |
| eligibility (inds/callable) | indices OR callable that returns inds | required | |
| label (str) | the name of vaccination strategy | required | |
| kwargs (dict) | passed to Intervention() | required |
Methods
| Name | Description |
|---|---|
| apply | Perform vaccination by finding who’s eligible for vaccination, finding who accepts, and applying the vaccine product. |
| check_eligibility | Determine who is eligible for vaccination |
| shrink | Shrink vaccination intervention |
apply
interventions.BaseVaccination.apply(sim)Perform vaccination by finding who’s eligible for vaccination, finding who accepts, and applying the vaccine product.
check_eligibility
interventions.BaseVaccination.check_eligibility(sim)Determine who is eligible for vaccination
shrink
interventions.BaseVaccination.shrink(in_place=True)Shrink vaccination intervention
CampaignDelivery
interventions.CampaignDelivery(
years,
interpolate=None,
prob=None,
annual_prob=True,
)Base class for any intervention that uses campaign delivery; handles interpolation of input years.
EventSchedule
interventions.EventSchedule()Run functions on different days
This intervention is a a kind of generalization of dynamic_pars to allow more flexibility in triggering multiple, arbitrary operations and to more easily assemble multiple changes at different times. This intervention can be used to implement scale-up or other changes to interventions without needing to implement time-dependency in the intervention itself.
To use the intervention, simply index the intervention by t or by date.
Example:
iv = EventSchedule() iv[1] = lambda sim: print(sim.t) iv[‘2020-04-02’] = lambda sim: print(‘foo’)
Intervention
interventions.Intervention(
label=None,
show_label=False,
do_plot=None,
line_args=None,
)Base class for interventions.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| label | str | a label for the intervention (used for plotting, and for ease of identification) | None |
| show_label | bool | whether or not to include the label in the legend | False |
| do_plot | bool | whether or not to plot the intervention | None |
| line_args | dict | arguments passed to pl.axvline() when plotting | None |
Methods
| Name | Description |
|---|---|
| apply | Apply the intervention. This is the core method which each derived intervention |
| disp | Print a detailed representation of the intervention |
| finalize | Finalize intervention |
| initialize | Initialize intervention – this is used to make modifications to the intervention |
| plot_intervention | Plot the intervention |
| shrink | Remove any excess stored data from the intervention; for use with sim.shrink(). |
| to_json | Return JSON-compatible representation |
apply
interventions.Intervention.apply(sim)Apply the intervention. This is the core method which each derived intervention class must implement. This method gets called at each timestep and can make arbitrary changes to the Sim object, as well as storing or modifying the state of the intervention.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | the Sim instance | required |
Returns
| Name | Type | Description |
|---|---|---|
| None |
disp
interventions.Intervention.disp()Print a detailed representation of the intervention
finalize
interventions.Intervention.finalize(sim=None)Finalize intervention
This method is run once as part of sim.finalize() enabling the intervention to perform any final operations after the simulation is complete (e.g. rescaling)
initialize
interventions.Intervention.initialize(sim=None)Initialize intervention – this is used to make modifications to the intervention that can’t be done until after the sim is created.
plot_intervention
interventions.Intervention.plot_intervention(sim, ax=None, **kwargs)Plot the intervention
This can be used to do things like add vertical lines at timepoints when interventions take place. Can be disabled by setting self.do_plot=False.
Note 1: you can modify the plotting style via the line_args argument when creating the intervention.
Note 2: By default, the intervention is plotted at the timepoints stored in self.timepoints. However, if there is a self.plot_timepoints attribute, this will be used instead.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | the Sim instance | required | |
| ax | the axis instance | None |
|
| kwargs | passed to ax.axvline() | {} |
Returns
| Name | Type | Description |
|---|---|---|
| None |
shrink
interventions.Intervention.shrink(in_place=False)Remove any excess stored data from the intervention; for use with sim.shrink().
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| in_place | bool | whether to shrink the intervention (else shrink a copy) | False |
to_json
interventions.Intervention.to_json()Return JSON-compatible representation
Custom classes can’t be directly represented in JSON. This method is a one-way export to produce a JSON-compatible representation of the intervention. In the first instance, the object dict will be returned. However, if an intervention itself contains non-standard variables as attributes, then its to_json method will need to handle those.
Note that simply printing an intervention will usually return a representation that can be used to recreate it.
Returns
| Name | Type | Description |
|---|---|---|
| JSON-serializable representation (typically a dict, but could be anything else) |
RoutineDelivery
interventions.RoutineDelivery(
years=None,
start_year=None,
end_year=None,
prob=None,
annual_prob=True,
)Base class for any intervention that uses routine delivery; handles interpolation of input years.
campaign_screening
interventions.campaign_screening(
product=None,
age_range=None,
eligibility=None,
prob=None,
years=None,
interpolate=None,
annual_prob=None,
**kwargs,
)Campaign screening - an instance of base screening combined with campaign delivery. See base classes for a description of input arguments.
Examples::
screen1 = hpv.campaign_screening(product='hpv', prob=0.2, years=2030) # Screen 20% of the eligible population in 2020
screen2 = hpv.campaign_screening(product='hpv', prob=0.02, years=[2025,2030]) # Screen 20% of the eligible population in 2025 and again in 2030campaign_triage
interventions.campaign_triage(
product=None,
age_range=None,
eligibility=None,
prob=None,
years=None,
interpolate=None,
annual_prob=None,
**kwargs,
)Campaign triage - an instance of base triage combined with campaign delivery. See base classes for a description of input arguments.
Examples::
# Example 1: In 2030, triage all positive screens into confirmatory testing or therapeutic vaccintion
screened_pos = lambda sim: sim.get_intervention('screening').outcomes['positive']
triage1 = hpv.campaign_triage(product='pos_screen_assessment', eligibility=screen_pos, prob=0.9, years=2030)campaign_txvx
interventions.campaign_txvx(
product=None,
prob=None,
age_range=None,
eligibility=None,
years=None,
interpolate=True,
annual_prob=None,
**kwargs,
)Campaign delivery of therapeutic vaccine - an instance of treat_num combined with campaign delivery. See base classes for a description of input arguments.
campaign_vx
interventions.campaign_vx(
product=None,
prob=None,
age_range=None,
sex=0,
eligibility=None,
years=None,
interpolate=True,
annual_prob=None,
**kwargs,
)Campaign vaccination - an instance of base vaccination combined with campaign delivery. See base classes for a description of input arguments.
dx
interventions.dx(df, hierarchy=None)Testing products are used within screening and triage. Their fundamental property is that they classify people into exactly one result state. They do not change anything about the People.
Methods
| Name | Description |
|---|---|
| administer | Administer a testing product. |
administer
interventions.dx.administer(sim, inds, return_format='dict')Administer a testing product.
Returns
| Name | Type | Description |
|---|---|---|
| if return_format==‘array’: an array of length len(inds) with integer entries that map each person to one of the result_states | ||
| if return_format==‘dict’: a dictionary keyed by result_states with values containing the indices of people classified into this state |
dynamic_pars
interventions.dynamic_pars(pars=None, **kwargs)A generic intervention that modifies a set of parameters at specified points in time.
The intervention takes a single argument, pars, which is a dictionary of which parameters to change, with following structure: keys are the parameters to change, then subkeys ‘days’ and ‘vals’ are either a scalar or list of when the change(s) should take effect and what the new value should be, respectively.
You can also pass parameters to change directly as keyword arguments.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pars | dict | described above | None |
| kwargs | dict | passed to Intervention() | {} |
Examples::
interv = hpv.dynamic_pars(condoms=dict(timepoints=10, vals={'c':0.9})) # Increase condom use amount casual partners to 90%
interv = hpv.dynamic_pars({'beta':{'timepoints':[10, 15], 'vals':[0.005, 0.015]}, # At timepoint 10, reduce beta, then increase it again
'debut':{'timepoints':10, 'vals':dict(f=dict(dist='normal', par1=20, par2=2.1), m=dict(dist='normal', par1=19.6, par2=1.8))}}) # Increase mean age of sexual debutMethods
| Name | Description |
|---|---|
| apply | Loop over the parameters, and then loop over the timepoints, applying them if any are found |
| initialize | Initialize with a sim |
apply
interventions.dynamic_pars.apply(sim)Loop over the parameters, and then loop over the timepoints, applying them if any are found
initialize
interventions.dynamic_pars.initialize(sim)Initialize with a sim
linked_txvx
interventions.linked_txvx(**kwargs)Deliver therapeutic vaccine. This intervention should be used if TxVx delivery is linked to another program that determines eligibility, e.g. a screening program. Handling of dates is assumed to be handled by the linked intervention.
routine_screening
interventions.routine_screening(
product=None,
prob=None,
eligibility=None,
age_range=None,
years=None,
start_year=None,
end_year=None,
annual_prob=None,
**kwargs,
)Routine screening - an instance of base screening combined with routine delivery. See base classes for a description of input arguments.
Examples::
screen1 = hpv.routine_screening(product='hpv', prob=0.02) # Screen 2% of the eligible population every year
screen2 = hpv.routine_screening(product='hpv', prob=0.02, start_year=2020) # Screen 2% every year starting in 2020
screen3 = hpv.routine_screening(product='hpv', prob=np.linspace(0.005,0.025,5), years=np.arange(2020,2025)) # Scale up screening over 5 years starting in 2020routine_triage
interventions.routine_triage(
product=None,
prob=None,
eligibility=None,
age_range=None,
years=None,
start_year=None,
end_year=None,
annual_prob=None,
**kwargs,
)Routine triage - an instance of base triage combined with routine delivery. See base classes for a description of input arguments.
Examples::
# Example 1: Triage 40% of the eligible population in all years
triage1 = hpv.routine_triage(product='via_triage', prob=0.4)
# Example 2: Triage positive screens into confirmatory testing or theapeutic vaccintion
screened_pos = lambda sim: sim.get_intervention('screening').outcomes['positive']
triage2 = hpv.routine_triage(product='pos_screen_assessment', eligibility=screen_pos, prob=0.9, start_year=2030)routine_txvx
interventions.routine_txvx(
product=None,
prob=None,
age_range=None,
eligibility=None,
start_year=None,
end_year=None,
years=None,
annual_prob=None,
**kwargs,
)Routine delivery of therapeutic vaccine - an instance of treat_num combined with routine delivery. See base classes for a description of input arguments.
Examples::
txvx1 = hpv.routine_txvx(product='txvx1', prob=0.9, age_range=[25,26], start_year=2030) # Vaccinate 90% of 25yo women every year starting 2025
txvx2 = hpv.routine_txvx(product='txvx1', prob=np.linspace(0.2,0.8,5), age_range=[25,26], years=np.arange(2030,2035)) # Scale up vaccination over 5 years starting in 2020routine_vx
interventions.routine_vx(
product=None,
prob=None,
age_range=None,
sex=0,
eligibility=None,
start_year=None,
end_year=None,
years=None,
**kwargs,
)Routine vaccination - an instance of base vaccination combined with routine delivery. See base classes for a description of input arguments.
Examples::
vx1 = hpv.routine_vx(product='bivalent', age_range=[9,10], prob=0.9, start_year=2025) # Vaccinate 90% of girls aged 9-10 every year
vx2 = hpv.routine_vx(product='bivalent', age_range=[9,10], prob=0.9, sex=[0,1], years=np.arange(2020,2025)) # Screen 90% of girls and boys aged 9-10 every year from 2020-2025
vx3 = hpv.routine_vx(product='quadrivalent', prob=np.linspace(0.2,0.8,5), years=np.arange(2020,2025)) # Scale up vaccination over 5 years starting in 2020treat_delay
interventions.treat_delay(delay=None, **kwargs)Treat people after a fixed delay
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| delay | int | years of delay between becoming eligible for treatment and receiving treatment. | None |
Methods
| Name | Description |
|---|---|
| add_to_schedule | Add people who are willing to accept treatment to the treatment scehduler |
| apply | Apply treatment. On each timestep, this method will add eligible people who are willing to accept treatment to a |
| get_candidates | Get the indices of people who are candidates for treatment |
add_to_schedule
interventions.treat_delay.add_to_schedule(sim)Add people who are willing to accept treatment to the treatment scehduler
apply
interventions.treat_delay.apply(sim)Apply treatment. On each timestep, this method will add eligible people who are willing to accept treatment to a scheduler, and then will treat anyone scheduled for treatment on this timestep.
get_candidates
interventions.treat_delay.get_candidates(sim)Get the indices of people who are candidates for treatment
treat_num
interventions.treat_num(max_capacity=None, **kwargs)Treat a fixed number of people each timestep.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| max_capacity | int | maximum number who can be treated each timestep | None |
Methods
| Name | Description |
|---|---|
| add_to_queue | Add people who are willing to accept treatment to the queue |
| apply | Apply treatment. On each timestep, this method will add eligible people who are willing to accept treatment to a |
| get_candidates | Get the indices of people who are candidates for treatment |
add_to_queue
interventions.treat_num.add_to_queue(sim)Add people who are willing to accept treatment to the queue
apply
interventions.treat_num.apply(sim)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.
get_candidates
interventions.treat_num.get_candidates(sim)Get the indices of people who are candidates for treatment
tx
interventions.tx(
df,
clearance=0.8,
genotype_pars=None,
imm_init=None,
imm_boost=None,
)Treatment products include anything used to treat cancer or precancer, as well as therapeutic vaccination. They change fundamental properties about People, including their prognoses and infectiousness.
Methods
| Name | Description |
|---|---|
| administer | Loop over treatment states to determine those who are successfully treated and clear infection |
| get_people_in_state | Find people within a given state/genotype. Returns indices |
administer
interventions.tx.administer(sim, inds, return_format='dict')Loop over treatment states to determine those who are successfully treated and clear infection
get_people_in_state
interventions.tx.get_people_in_state(state, g, sim)Find people within a given state/genotype. Returns indices
vx
interventions.vx(genotype_pars=None, imm_init=None, imm_boost=None)Vaccine product
Methods
| Name | Description |
|---|---|
| administer | Apply the vaccine to the requested people indices. |
administer
interventions.vx.administer(people, inds)Apply the vaccine to the requested people indices.
Functions
| Name | Description |
|---|---|
| default_dx | Create default diagnostic products |
| default_tx | Create default treatment products |
| default_vx | Create default vaccine products |
default_dx
interventions.default_dx(prod_name=None)Create default diagnostic products
default_tx
interventions.default_tx(prod_name=None)Create default treatment products
default_vx
interventions.default_vx(prod_name=None)Create default vaccine products