Python (π): This assumes that you have a python environment installed.
To install FPsim, you first need to clone or download a copy of the source code from https://github.com/fpsim/fpsim
git clone -b <branch> --single-branch https://github.com/fpsim/fpsim.git
cd fpsim
pip install -e .If it worked, you should be able to import fpsim with import fpsim as fp.
Getting started with FPsim
The basic design philosophy of FPsim is: common modelling tasks should be simple . For example:
Defining parameters
Running a simulation
Plotting results
This tutorial walks you through how to define parameters and run the simulation. The next tutorial will show you how to plot the results of a simulation.
To create, run, and plot a sim with default options is just:
import fpsim as fp= fp.Sim(location= 'kenya' )= sim.plot()
Loading data from files in /home/runner/work/fpsim/fpsim/fpsim/locations/kenya/data...
Applying calibration parameters for kenya...
Initializing sim with 1000 agents
Running 2000.01.01 ( 0/241) (0.00 s) ββββββββββββββββββββ 0%
Running 2001.01.01 (12/241) (0.13 s) β’βββββββββββββββββββ 5%
Running 2002.01.01 (24/241) (0.31 s) β’β’ββββββββββββββββββ 10%
Running 2003.01.01 (36/241) (0.48 s) β’β’β’βββββββββββββββββ 15%
Running 2004.01.01 (48/241) (0.66 s) β’β’β’β’ββββββββββββββββ 20%
Running 2005.01.01 (60/241) (0.84 s) β’β’β’β’β’βββββββββββββββ 25%
Running 2006.01.01 (72/241) (1.02 s) β’β’β’β’β’β’ββββββββββββββ 30%
Running 2007.01.01 (84/241) (1.21 s) β’β’β’β’β’β’β’βββββββββββββ 35%
Running 2008.01.01 (96/241) (1.41 s) β’β’β’β’β’β’β’β’ββββββββββββ 40%
Running 2009.01.01 (108/241) (1.61 s) β’β’β’β’β’β’β’β’β’βββββββββββ 45%
Running 2010.01.01 (120/241) (1.82 s) β’β’β’β’β’β’β’β’β’β’ββββββββββ 50%
Running 2011.01.01 (132/241) (2.01 s) β’β’β’β’β’β’β’β’β’β’β’βββββββββ 55%
Running 2012.01.01 (144/241) (2.22 s) β’β’β’β’β’β’β’β’β’β’β’β’ββββββββ 60%
Running 2013.01.01 (156/241) (2.42 s) β’β’β’β’β’β’β’β’β’β’β’β’β’βββββββ 65%
Running 2014.01.01 (168/241) (2.62 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββββ 70%
Running 2015.01.01 (180/241) (2.82 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββββ 75%
Running 2016.01.01 (192/241) (3.03 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββ 80%
Running 2017.01.01 (204/241) (3.24 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββ 85%
Running 2018.01.01 (216/241) (3.45 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββ 90%
Running 2019.01.01 (228/241) (3.66 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β 95%
Running 2020.01.01 (240/241) (3.87 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ 100%
Defining parameters
Parameters are defined as a dictionary. In FPsim, we categorize our parameters as:
Basic parameters
Age limits
Demographics (urban/rural, wealth)
Durations
Pregnancy outcomes
Fecundity and exposure
Contraceptive use
Education
The most common category of parameters to change in FPsim is the basic category, which includes the geographic location (i.e. Kenya, Senegal, northern India), the starting population, the starting year, and the initial number of agents. We can define these as:
= dict (= 10_000 ,= 'kenya' ,= 2000 , = 2020 ,
Running simulations
Running a simulation is pretty easy. In fact, running a sim with the parameters we defined above is just:
= fp.Sim(pars)
Loading data from files in /home/runner/work/fpsim/fpsim/fpsim/locations/kenya/data...
Applying calibration parameters for kenya...
Initializing sim with 10000 agents
Running 2000.01.01 ( 0/241) (0.00 s) ββββββββββββββββββββ 0%
Running 2001.01.01 (12/241) (0.27 s) β’βββββββββββββββββββ 5%
Running 2002.01.01 (24/241) (0.63 s) β’β’ββββββββββββββββββ 10%
Running 2003.01.01 (36/241) (0.99 s) β’β’β’βββββββββββββββββ 15%
Running 2004.01.01 (48/241) (1.38 s) β’β’β’β’ββββββββββββββββ 20%
Running 2005.01.01 (60/241) (1.77 s) β’β’β’β’β’βββββββββββββββ 25%
Running 2006.01.01 (72/241) (2.17 s) β’β’β’β’β’β’ββββββββββββββ 30%
Running 2007.01.01 (84/241) (2.57 s) β’β’β’β’β’β’β’βββββββββββββ 35%
Running 2008.01.01 (96/241) (2.97 s) β’β’β’β’β’β’β’β’ββββββββββββ 40%
Running 2009.01.01 (108/241) (3.39 s) β’β’β’β’β’β’β’β’β’βββββββββββ 45%
Running 2010.01.01 (120/241) (3.81 s) β’β’β’β’β’β’β’β’β’β’ββββββββββ 50%
Running 2011.01.01 (132/241) (4.23 s) β’β’β’β’β’β’β’β’β’β’β’βββββββββ 55%
Running 2012.01.01 (144/241) (4.66 s) β’β’β’β’β’β’β’β’β’β’β’β’ββββββββ 60%
Running 2013.01.01 (156/241) (5.08 s) β’β’β’β’β’β’β’β’β’β’β’β’β’βββββββ 65%
Running 2014.01.01 (168/241) (5.51 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββββ 70%
Running 2015.01.01 (180/241) (5.96 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββββ 75%
Running 2016.01.01 (192/241) (6.40 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββ 80%
Running 2017.01.01 (204/241) (6.85 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββ 85%
Running 2018.01.01 (216/241) (7.31 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββ 90%
Running 2019.01.01 (228/241) (7.77 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β 95%
Running 2020.01.01 (240/241) (8.23 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ 100%
Sim(n=10000; 2000β2020; demographics=deaths; connectors=contraception, edu, fp)
Inspecting results
Running the simulation will generate a results [dictionary] sim.results. A dictionary is simply collection of items, and you can access the values of results using different βkeyβ words. Almost all of the results relevant for FPsim are stored under the key βfpβ; for example, the number of pregnancies over time can be found using sim.results.fp['pregnancies']. Execute the code below:
'pregnancies' ]
Result(pregnancies):
array([185. 134. 134. 91. 74. 69. 63. 76. 55. 50. 59. 54. 81. 61.
63. 72. 67. 62. 56. 60. 57. 59. 47. 58. 46. 41. 36. 45.
49. 32. 58. 45. 37. 47. 61. 60. 60. 53. 49. 59. 48. 62.
30. 57. 57. 45. 56. 60. 61. 55. 61. 43. 59. 61. 49. 58.
45. 41. 62. 49. 58. 52. 56. 45. 60. 44. 39. 52. 47. 44.
56. 50. 47. 40. 42. 58. 47. 43. 41. 35. 48. 41. 48. 50.
55. 49. 41. 44. 34. 38. 35. 39. 39. 40. 32. 56. 47. 29.
51. 50. 42. 51. 49. 40. 46. 48. 46. 41. 41. 50. 48. 54.
42. 48. 44. 51. 38. 52. 53. 35. 39. 40. 29. 31. 34. 36.
50. 40. 38. 36. 34. 38. 38. 45. 41. 48. 52. 46. 58. 45.
49. 50. 38. 47. 42. 55. 36. 38. 47. 43. 45. 54. 30. 49.
40. 48. 32. 52. 51. 45. 42. 51. 34. 54. 43. 36. 55. 55.
52. 43. 46. 39. 48. 49. 55. 40. 52. 45. 49. 52. 35. 56.
49. 41. 34. 40. 41. 43. 43. 49. 32. 42. 39. 46. 41. 42.
42. 52. 39. 47. 36. 47. 58. 42. 46. 49. 43. 47. 52. 44.
46. 57. 50. 45. 49. 54. 49. 41. 43. 44. 43. 52. 50. 57.
64. 50. 47. 53. 37. 58. 59. 68. 52. 62. 65. 46. 51. 53.
63. 62. 57.])
If you want to see all the βkeysβ that are available in the results dictionary you can use
Result keys:
contraception.acpr
contraception.cpr
contraception.mcpr
contraception.n_at_risk_non_users
contraception.n_at_risk_users
contraception.n_mod_users
contraception.n_non_users
contraception.n_users
cum_deaths
deaths.cmr
deaths.cumulative
deaths.new
edu.mean_attainment
edu.mean_objective
edu.n_completed
edu.n_dropped
edu.n_in_school
edu.n_interrupted
edu.n_started
edu.prop_completed
edu.prop_dropped
edu.prop_in_school
fp.abortions
fp.births
fp.contra_access
fp.ever_used_contra
fp.imr
fp.infant_deaths
fp.maternal_deaths
fp.method_failures
fp.miscarriages
fp.mmr
fp.n_ever_used_contra
fp.n_fecund
fp.n_fertile
fp.n_fertility_intent
fp.n_intent_to_use
fp.n_lactating
fp.n_lam
fp.n_on_contra
fp.n_partnered
fp.n_postpartum
fp.n_pregnant
fp.n_sexual_debut
fp.n_sexually_active
fp.new_users
fp.nonpostpartum
fp.p_short_interval
fp.parity0to1
fp.parity2to3
fp.parity4to5
fp.parity6plus
fp.pp0to5
fp.pp12to23
fp.pp6to11
fp.pregnancies
fp.secondary_births
fp.short_intervals
fp.stillbirths
fp.switchers
fp.tfr
fp.total_births
n_alive
n_female
n_urban
n_wq1
n_wq2
n_wq3
n_wq4
n_wq5
new_deaths
new_emigrants
Slightly different way of defining parameters
You can also specify different parameters by specifyuing them directly as arguments in the simulation object:
= fp.Sim(n_agents= 10e3 , location= 'kenya' , start_year= 2000 , end_year= 2020 )
Loading data from files in /home/runner/work/fpsim/fpsim/fpsim/locations/kenya/data...
Applying calibration parameters for kenya...
Initializing sim with 10000 agents
Running 2000.01.01 ( 0/241) (0.00 s) ββββββββββββββββββββ 0%
Running 2001.01.01 (12/241) (0.27 s) β’βββββββββββββββββββ 5%
Running 2002.01.01 (24/241) (0.64 s) β’β’ββββββββββββββββββ 10%
Running 2003.01.01 (36/241) (1.00 s) β’β’β’βββββββββββββββββ 15%
Running 2004.01.01 (48/241) (1.39 s) β’β’β’β’ββββββββββββββββ 20%
Running 2005.01.01 (60/241) (1.77 s) β’β’β’β’β’βββββββββββββββ 25%
Running 2006.01.01 (72/241) (2.18 s) β’β’β’β’β’β’ββββββββββββββ 30%
Running 2007.01.01 (84/241) (2.57 s) β’β’β’β’β’β’β’βββββββββββββ 35%
Running 2008.01.01 (96/241) (2.98 s) β’β’β’β’β’β’β’β’ββββββββββββ 40%
Running 2009.01.01 (108/241) (3.39 s) β’β’β’β’β’β’β’β’β’βββββββββββ 45%
Running 2010.01.01 (120/241) (3.81 s) β’β’β’β’β’β’β’β’β’β’ββββββββββ 50%
Running 2011.01.01 (132/241) (4.24 s) β’β’β’β’β’β’β’β’β’β’β’βββββββββ 55%
Running 2012.01.01 (144/241) (4.66 s) β’β’β’β’β’β’β’β’β’β’β’β’ββββββββ 60%
Running 2013.01.01 (156/241) (5.09 s) β’β’β’β’β’β’β’β’β’β’β’β’β’βββββββ 65%
Running 2014.01.01 (168/241) (5.52 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββββ 70%
Running 2015.01.01 (180/241) (5.97 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββββ 75%
Running 2016.01.01 (192/241) (6.42 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββ 80%
Running 2017.01.01 (204/241) (6.87 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββ 85%
Running 2018.01.01 (216/241) (7.33 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββ 90%
Running 2019.01.01 (228/241) (7.79 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β 95%
Running 2020.01.01 (240/241) (8.25 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ 100%
Sim(n=10000; 2000β2020; demographics=deaths; connectors=contraception, edu, fp)
You can mix and match too β pass in the parameter dictionary (pars defined above) with some default options, and then include other parameters as arguments to the sim. Doing this overrides the equally named parameters in pars because (keyword) arguments take precedence). For example:
= fp.Sim(pars, n_agents= 100 ) # Use parameters defined above, but overrides the value `n_agents` in pars, and uses instead 100 agents, not 10,000
Loading data from files in /home/runner/work/fpsim/fpsim/fpsim/locations/kenya/data...
Applying calibration parameters for kenya...
Initializing sim with 100 agents
Running 2000.01.01 ( 0/241) (0.00 s) ββββββββββββββββββββ 0%
Running 2001.01.01 (12/241) (0.08 s) β’βββββββββββββββββββ 5%
Running 2002.01.01 (24/241) (0.18 s) β’β’ββββββββββββββββββ 10%
Running 2003.01.01 (36/241) (0.28 s) β’β’β’βββββββββββββββββ 15%
Running 2004.01.01 (48/241) (0.37 s) β’β’β’β’ββββββββββββββββ 20%
Running 2005.01.01 (60/241) (0.48 s) β’β’β’β’β’βββββββββββββββ 25%
Running 2006.01.01 (72/241) (0.58 s) β’β’β’β’β’β’ββββββββββββββ 30%
Running 2007.01.01 (84/241) (0.68 s) β’β’β’β’β’β’β’βββββββββββββ 35%
Running 2008.01.01 (96/241) (0.77 s) β’β’β’β’β’β’β’β’ββββββββββββ 40%
Running 2009.01.01 (108/241) (0.87 s) β’β’β’β’β’β’β’β’β’βββββββββββ 45%
Running 2010.01.01 (120/241) (0.96 s) β’β’β’β’β’β’β’β’β’β’ββββββββββ 50%
Running 2011.01.01 (132/241) (1.06 s) β’β’β’β’β’β’β’β’β’β’β’βββββββββ 55%
Running 2012.01.01 (144/241) (1.16 s) β’β’β’β’β’β’β’β’β’β’β’β’ββββββββ 60%
Running 2013.01.01 (156/241) (1.25 s) β’β’β’β’β’β’β’β’β’β’β’β’β’βββββββ 65%
Running 2014.01.01 (168/241) (1.35 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββββ 70%
Running 2015.01.01 (180/241) (1.45 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββββ 75%
Running 2016.01.01 (192/241) (1.55 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββββ 80%
Running 2017.01.01 (204/241) (1.66 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’βββ 85%
Running 2018.01.01 (216/241) (1.77 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ββ 90%
Running 2019.01.01 (228/241) (1.89 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β 95%
Running 2020.01.01 (240/241) (2.01 s) β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’β’ 100%
Sim(n=100; 2000β2020; demographics=deaths; connectors=contraception, edu, fp)
Now you know how to run a basic simulation in FPsim and change the parameters. Now letβs take a look at the output of the sim.
Explore plotting options for a single simulation
Letβs take a look at the basic suite of plotting options, once weβve run our initial simulation.
The basic plot function will plot births, deaths, and mcpr over the entire simulation.
There are also pre-defined options that combine similar types of output. For instance, βapoβ stands for adverse pregnancy outcomes, and will plot infant deaths, stillbirths, and abortions.
plot() will take any of the following options:
βcprβ will plot three different ways to define contraceptive prevalence - mCPR, CPR (includes traditional), and aCPR (includes traditional and restricts denominator to sexually active non-pregnant women) βapoβ will plot adverse pregnancy outcomes, including abortion and miscarriage βmortalityβ will plot mortality-related outcomes βmethodβ plots the method mix over time
# the default 'cpr' )
In the next tutorial, we will look at some of the new features of FPsim 2.0, including how to define different contraceptive choice options.
