An interactive version of this notebook is available on Google Colab or Binder.

Adding a new method

At this point, you should be able to ru FPsim, create interventions, and set eligilble subpopulations for that inervention. Now, let’s see how to create a different type of intervention: introducing a new contraceptive method. First, import the model.

import fpsim as fp
import sciris as sc
import starsim as ss

/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-fpsim/envs/latest/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

We will start by making a copy of the default list of contraceptive methods used by FPsim. We need this so that we can add our new metod to the list.

my_methods = fp.make_methods()

Define a new method

To define and parameterize your new method, you need to enter attributes:

1. A simple name, which needs to be concise because it will be used inside the code.

2. Efficacy, defined as a percent.

3. Whether it is a modern method or not, defined as true or false.

4. Duration of use, or time on that method, which can me defined as a number of months, or a distribution. If you choose a distribution, you need to define the type of distribution (e.g. lognormal, loglogistic, …) as well as the parameters for that distribution. See tutorial three for more information on time on method.

5. A label, which can be more descriptive as it is used in plots

You create the new method using code like this:

new_method = fp.Method(name='new', efficacy=0.96,  modern=True,  dur_use=15, label='New method')

Add your method to the list of methods in the model.

my_methods += new_method

The final thing we need to define for our new method is the method mix. This tell the model which method a woman will choose when she slects a method. We need an array of percentages for each method, incuding the new method.

# Note: if we do not define this method mix, the contraception module will use 1/(number of methods) for every method.
method_choice = fp.RandomChoice(methods=my_methods, pars={'method_mix': [0.25, 0.25, 0, 0, 0, 0, 0, 0, 0, 0.5]})

Run your simulations

Define the baseline settings for your analysis.

pars = dict(
    n_agents   = 10_000,
    start_year = 2000,
    end_year   = 2012,
    exposure_factor = 1.0  # Overall scale factor on probability of becoming pregnant
)

Define two simulaitons: s1, the baseline with no interventions, and s2, adding the new method we defined above as the contraception module. Then run both of these together.

s1 = fp.Sim(pars=pars, label='Baseline')
s2 = fp.Sim(pars=pars, contraception_module=method_choice, label='New Method')
simlist = sc.autolist([s1, s2])
msim = ss.MultiSim(sims=simlist)
msim.run(parallel=False)

Location not supplied: using parameters from Senegal
Location not supplied: using parameters from Senegal
Initializing sim "Baseline" with 10000 agents
  Running "Baseline": 2000.01.01 ( 0/145) (0.00 s)  ———————————————————— 1%
  Running "Baseline": 2001.01.01 (12/145) (0.26 s)  •——————————————————— 9%
  Running "Baseline": 2002.01.01 (24/145) (0.58 s)  •••————————————————— 17%
  Running "Baseline": 2003.01.01 (36/145) (0.92 s)  •••••——————————————— 26%
  Running "Baseline": 2004.01.01 (48/145) (1.27 s)  ••••••—————————————— 34%
  Running "Baseline": 2005.01.01 (60/145) (1.62 s)  ••••••••———————————— 42%
  Running "Baseline": 2006.01.01 (72/145) (1.99 s)  ••••••••••—————————— 50%
  Running "Baseline": 2007.01.01 (84/145) (2.36 s)  •••••••••••————————— 59%
  Running "Baseline": 2008.01.01 (96/145) (2.74 s)  •••••••••••••——————— 67%
  Running "Baseline": 2009.01.01 (108/145) (3.14 s)  •••••••••••••••————— 75%
  Running "Baseline": 2010.01.01 (120/145) (3.53 s)  ••••••••••••••••———— 83%
  Running "Baseline": 2011.01.01 (132/145) (3.92 s)  ••••••••••••••••••—— 92%
  Running "Baseline": 2012.01.01 (144/145) (4.31 s)  •••••••••••••••••••• 100%

Initializing sim "New Method" with 10000 agents
  Running "New Method": 2000.01.01 ( 0/145) (0.00 s)  ———————————————————— 1%
  Running "New Method": 2001.01.01 (12/145) (0.16 s)  •——————————————————— 9%
  Running "New Method": 2002.01.01 (24/145) (0.36 s)  •••————————————————— 17%
  Running "New Method": 2003.01.01 (36/145) (0.57 s)  •••••——————————————— 26%
  Running "New Method": 2004.01.01 (48/145) (0.77 s)  ••••••—————————————— 34%
  Running "New Method": 2005.01.01 (60/145) (0.98 s)  ••••••••———————————— 42%
  Running "New Method": 2006.01.01 (72/145) (1.19 s)  ••••••••••—————————— 50%
  Running "New Method": 2007.01.01 (84/145) (1.40 s)  •••••••••••————————— 59%
  Running "New Method": 2008.01.01 (96/145) (1.62 s)  •••••••••••••——————— 67%
  Running "New Method": 2009.01.01 (108/145) (1.83 s)  •••••••••••••••————— 75%
  Running "New Method": 2010.01.01 (120/145) (2.06 s)  ••••••••••••••••———— 83%
  Running "New Method": 2011.01.01 (132/145) (2.28 s)  ••••••••••••••••••—— 92%
  Running "New Method": 2012.01.01 (144/145) (2.51 s)  •••••••••••••••••••• 100%

MultiSim("Baseline"; n_sims: 2; base: Sim(Baseline; n=10000; 2000—2012; connectors=contraception, edu, fp))

Take a look at the contraceptive use from your simulations.

msim.plot(key='cpr');

Figure(1600x1000)