fpsim.interventions module

Specify the core interventions available in FPsim. Other interventions can be defined by the user by inheriting from these classes.

class fpsim.interventions.Intervention(label=None, show_label=False, do_plot=None, line_args=None)

Bases: object

Base class for interventions. By default, interventions are printed using a dict format, which they can be recreated from. To display all the attributes of the intervention, use disp() instead.

To retrieve a particular intervention from a sim, use sim.get_intervention().

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

disp()

Print a detailed representation of the 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.

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)

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

sim – the Sim instance

Returns

None

plot_intervention(sim, ax=None, **kwargs)

Plot the intervention

This can be used to do things like add vertical lines on days 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 days stored in self.days. However, if there is a self.plot_days attribute, this will be used instead.

Parameters
  • sim – the Sim instance

  • ax – the axis instance

  • kwargs – passed to ax.axvline()

Returns

None

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

JSON-serializable representation (typically a dict, but could be anything else)

class fpsim.interventions.change_par(par, years=None, vals=None, verbose=False)

Bases: fpsim.interventions.Intervention

Change a parameter at a specified point in time.

Parameters
  • par (str) – the parameter to change

  • years (float/arr) – the year(s) at which to apply the change

  • vals (any) – a value or list of values to change to (if a list, must have the same length as years); or a dict of year:value entries

If any value is 'reset', reset to the original value.

Example:

ec0 = fp.change_par(par='exposure_factor', years=[2000, 2010], vals=[0.0, 2.0]) # Reduce exposure factor
ec0 = fp.change_par(par='exposure_factor', vals={2000:0.0, 2010:2.0}) # Equivalent way of writing
sim = fp.Sim(interventions=ec0).run()
initialize(sim)

Initialize intervention – this is used to make modifications to the intervention that can’t be done until after the sim is created.

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

sim – the Sim instance

Returns

None

finalize()

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)

class fpsim.interventions.update_methods(year, eff=None, probs=None, matrix=None, verbose=False)

Bases: fpsim.interventions.Intervention

Intervention to modify method efficacy and/or switching matrix.

Parameters
  • year (float) – The year we want to change the method.

  • eff (dict) –

    An optional key for changing efficacy; its value is a dictionary with the following schema:

    {method: efficacy}

    Where method is the method to be changed, and efficacy is the new efficacy (can include multiple keys).

  • probs (list) –

    A list of dictionaries where each dictionary has the following keys:

    source (str): The source method to be changed. dest (str) The destination method to be changed. factor (float): The factor by which to multiply existing probability; OR value (float): The value to replace the switching probability value. keys (list): A list of strings representing age groups to affect. matrix (str): One of [‘probs’, ‘probs1’, ‘probs1to6’] where:

    probs: Changes the specified uptake at the corresponding year regardless of state. probs1: Changes the specified uptake for all individuals in their first month postpartum. probs1to6: Changes the specified uptake for all individuals that are in the first 6 months postpartum.

apply(sim)

Applies the efficacy or contraceptive uptake changes if it is the specified year based on scenario specifications.