hpvsim.interventions module¶
Specify the core interventions. Other interventions can be defined by the user by inheriting from these classes.
- class Intervention(label=None, show_label=False, do_plot=None, line_args=None, **kwargs)[source]¶
Bases:
object
Base class for interventions.
- Parameters:
label (str) – a label for the intervention (used for plotting, and for ease of identification)
show_label (bool) – whether or not to include the label in the legend
do_plot (bool) – whether or not to plot the intervention
line_args (dict) – arguments passed to pl.axvline() when plotting
- initialize(sim=None)[source]¶
Initialize intervention – this is used to make modifications to the intervention that can’t be done until after the sim is created.
- finalize(sim=None)[source]¶
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)
- apply(sim)[source]¶
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:
sim – the Sim instance
- Returns:
None
- shrink(in_place=False)[source]¶
Remove any excess stored data from the intervention; for use with sim.shrink().
- Parameters:
in_place (bool) – whether to shrink the intervention (else shrink a copy)
- plot_intervention(sim, ax=None, **kwargs)[source]¶
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:
sim – the Sim instance
ax – the axis instance
kwargs – passed to ax.axvline()
- Returns:
None
- to_json()[source]¶
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:
JSON-serializable representation (typically a dict, but could be anything else)
- class RoutineDelivery(years=None, start_year=None, end_year=None, prob=None, annual_prob=True)[source]¶
Bases:
Intervention
Base class for any intervention that uses routine delivery; handles interpolation of input years.
- class CampaignDelivery(years, interpolate=None, prob=None, annual_prob=True)[source]¶
Bases:
Intervention
Base class for any intervention that uses campaign delivery; handles interpolation of input years.
- class dynamic_pars(pars=None, **kwargs)[source]¶
Bases:
Intervention
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:
pars (dict) – described above
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 debut
- class EventSchedule[source]¶
Bases:
Intervention
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')
- class BaseVaccination(product=None, prob=None, age_range=None, sex=None, eligibility=None, label=None, **kwargs)[source]¶
Bases:
Intervention
Base vaccination class for determining who will receive a vaccine.
- Parameters:
product (str/Product) – the vaccine to use
prob (float/arr) – annual probability of eligible population getting vaccinated
age_range (list/tuple) – age range to vaccinate
sex (int/str/list) – sex to vaccinate - accepts 0/1 or ‘f’/’m’ or a list of both
eligibility (inds/callable) – indices OR callable that returns inds
label (str) – the name of vaccination strategy
kwargs (dict) – passed to Intervention()
- class routine_vx(product=None, prob=None, age_range=None, sex=0, eligibility=None, start_year=None, end_year=None, years=None, **kwargs)[source]¶
Bases:
BaseVaccination
,RoutineDelivery
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 2020
- class campaign_vx(product=None, prob=None, age_range=None, sex=0, eligibility=None, years=None, interpolate=True, **kwargs)[source]¶
Bases:
BaseVaccination
,CampaignDelivery
Campaign vaccination - an instance of base vaccination combined with campaign delivery. See base classes for a description of input arguments.
- class BaseTest(product=None, prob=None, eligibility=None, **kwargs)[source]¶
Bases:
Intervention
Base class for screening and triage.
- Parameters:
product (str/Product) – the diagnostic to use
prob (float/arr) – annual probability of eligible women receiving the diagnostic
eligibility (inds/callable) – indices OR callable that returns inds
label (str) – the name of screening strategy
kwargs (dict) – passed to Intervention()
- class BaseScreening(age_range=None, **kwargs)[source]¶
Bases:
BaseTest
Base class for screening.
- Parameters:
age_range (list/tuple/arr) – age range for screening, e.g. [30,50]
kwargs (dict) – passed to BaseTest
- class routine_screening(product=None, prob=None, eligibility=None, age_range=None, years=None, start_year=None, end_year=None, **kwargs)[source]¶
Bases:
BaseScreening
,RoutineDelivery
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 2020
- class campaign_screening(product=None, age_range=None, sex=None, eligibility=None, prob=None, years=None, interpolate=None, **kwargs)[source]¶
Bases:
BaseScreening
,CampaignDelivery
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 2030
- class BaseTriage(**kwargs)[source]¶
Bases:
BaseTest
Base class for triage.
- Parameters:
kwargs (dict) – passed to BaseTest
- class routine_triage(product=None, prob=None, eligibility=None, age_range=None, years=None, start_year=None, end_year=None, annual_prob=None, **kwargs)[source]¶
Bases:
BaseTriage
,RoutineDelivery
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)
- class campaign_triage(product=None, age_range=None, sex=None, eligibility=None, prob=None, years=None, interpolate=None, annual_prob=None, **kwargs)[source]¶
Bases:
BaseTriage
,CampaignDelivery
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)
- class BaseTreatment(product=None, prob=None, eligibility=None, age_range=None, **kwargs)[source]¶
Bases:
Intervention
Base treatment class.
- Parameters:
product (str/Product) – the treatment product to use
accept_prob (float/arr) – acceptance rate of treatment - interpreted as the % of women eligble for treatment who accept
eligibility (inds/callable) – indices OR callable that returns inds
label (str) – the name of treatment strategy
kwargs (dict) – passed to Intervention()
- get_accept_inds(sim)[source]¶
Get indices of people who will acccept treatment; these people are then added to a queue or scheduled for receiving treatment
- class treat_num(max_capacity=None, **kwargs)[source]¶
Bases:
BaseTreatment
Treat a fixed number of people each timestep.
- Parameters:
max_capacity (int) – maximum number who can be treated each timestep
- class treat_delay(delay=None, **kwargs)[source]¶
Bases:
BaseTreatment
Treat people after a fixed delay
- Parameters:
delay (int) – years of delay between becoming eligible for treatment and receiving treatment.
- class BaseTxVx(**kwargs)[source]¶
Bases:
BaseTreatment
Base class for therapeutic vaccination
- class routine_txvx(product=None, prob=None, age_range=None, eligibility=None, start_year=None, end_year=None, years=None, annual_prob=None, **kwargs)[source]¶
Bases:
BaseTxVx
,RoutineDelivery
- 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 2020
- class campaign_txvx(product=None, prob=None, age_range=None, eligibility=None, years=None, interpolate=True, annual_prob=None, **kwargs)[source]¶
Bases:
BaseTxVx
,CampaignDelivery
Campaign delivery of therapeutic vaccine - an instance of treat_num combined with campaign delivery. See base classes for a description of input arguments.
- class linked_txvx(**kwargs)[source]¶
Bases:
BaseTxVx
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.
- class dx(df, hierarchy=None)[source]¶
Bases:
Product
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.
- property default_value¶
- administer(sim, inds, return_format='dict')[source]¶
Administer a testing product.
- Returns:
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
- Return type:
if return_format==’array’
- class tx(df, clearance=0.8, genotype_pars=None, imm_init=None, imm_boost=None)[source]¶
Bases:
Product
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.