T1 - Getting started¶
Installing and getting started with FPsim is quite simple.
To install, just type pip install -e .. If it worked, you should be able to import FPsim with import fpsim as fp.
The basic design philosophy of FPsim is: common tasks should be simple. For example:
Defining parameters
Running a simulation
Plotting results
This tutorial walks you through how to define paramaters and run the simulation. The next tutorial will show you how to plot the results of a simulation.
Hello world¶
To create, run, and plot a sim with default options is just:
[1]:
import fpsim as fp
sim = fp.Sim()
sim.run()
fig = sim.plot()
/home/docs/checkouts/readthedocs.org/user_builds/institute-for-disease-modeling-fpsim/envs/v0.19.2/lib/python3.9/site-packages/tqdm/auto.py:22: 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
Running 1960 of 2020 ( 0/721) (0.09 s) ———————————————————— 0%
Running 1961 of 2020 (12/721) (0.21 s) ———————————————————— 2%
Running 1962 of 2020 (24/721) (0.35 s) ———————————————————— 3%
Running 1963 of 2020 (36/721) (0.48 s) •——————————————————— 5%
Running 1964 of 2020 (48/721) (0.61 s) •——————————————————— 7%
Running 1965 of 2020 (60/721) (0.74 s) •——————————————————— 8%
Running 1966 of 2020 (72/721) (0.87 s) ••—————————————————— 10%
Running 1967 of 2020 (84/721) (1.00 s) ••—————————————————— 12%
Running 1968 of 2020 (96/721) (1.13 s) ••—————————————————— 13%
Running 1969 of 2020 (108/721) (1.27 s) •••————————————————— 15%
Running 1970 of 2020 (120/721) (1.40 s) •••————————————————— 17%
Running 1971 of 2020 (132/721) (1.53 s) •••————————————————— 18%
Running 1972 of 2020 (144/721) (1.67 s) ••••———————————————— 20%
Running 1973 of 2020 (156/721) (1.80 s) ••••———————————————— 22%
Running 1974 of 2020 (168/721) (1.94 s) ••••———————————————— 23%
Running 1975 of 2020 (180/721) (2.07 s) •••••——————————————— 25%
Running 1976 of 2020 (192/721) (2.21 s) •••••——————————————— 27%
Running 1977 of 2020 (204/721) (2.34 s) •••••——————————————— 28%
Running 1978 of 2020 (216/721) (2.48 s) ••••••—————————————— 30%
Running 1979 of 2020 (228/721) (2.61 s) ••••••—————————————— 32%
Running 1980 of 2020 (240/721) (2.75 s) ••••••—————————————— 33%
Running 1981 of 2020 (252/721) (2.88 s) •••••••————————————— 35%
Running 1982 of 2020 (264/721) (3.02 s) •••••••————————————— 37%
Running 1983 of 2020 (276/721) (3.16 s) •••••••————————————— 38%
Running 1984 of 2020 (288/721) (3.29 s) ••••••••———————————— 40%
Running 1985 of 2020 (300/721) (3.43 s) ••••••••———————————— 42%
Running 1986 of 2020 (312/721) (3.57 s) ••••••••———————————— 43%
Running 1987 of 2020 (324/721) (3.71 s) •••••••••——————————— 45%
Running 1988 of 2020 (336/721) (3.85 s) •••••••••——————————— 47%
Running 1989 of 2020 (348/721) (3.99 s) •••••••••——————————— 48%
Running 1990 of 2020 (360/721) (4.13 s) ••••••••••—————————— 50%
Running 1991 of 2020 (372/721) (4.27 s) ••••••••••—————————— 52%
Running 1992 of 2020 (384/721) (4.41 s) ••••••••••—————————— 53%
Running 1993 of 2020 (396/721) (4.55 s) •••••••••••————————— 55%
Running 1994 of 2020 (408/721) (4.70 s) •••••••••••————————— 57%
Running 1995 of 2020 (420/721) (4.84 s) •••••••••••————————— 58%
Running 1996 of 2020 (432/721) (4.98 s) ••••••••••••———————— 60%
Running 1997 of 2020 (444/721) (5.13 s) ••••••••••••———————— 62%
Running 1998 of 2020 (456/721) (5.27 s) ••••••••••••———————— 63%
Running 1999 of 2020 (468/721) (5.41 s) •••••••••••••——————— 65%
Running 2000 of 2020 (480/721) (5.56 s) •••••••••••••——————— 67%
Running 2001 of 2020 (492/721) (5.71 s) •••••••••••••——————— 68%
Running 2002 of 2020 (504/721) (5.86 s) ••••••••••••••—————— 70%
Running 2003 of 2020 (516/721) (6.01 s) ••••••••••••••—————— 72%
Running 2004 of 2020 (528/721) (6.28 s) ••••••••••••••—————— 73%
Running 2005 of 2020 (540/721) (6.43 s) •••••••••••••••————— 75%
Running 2006 of 2020 (552/721) (6.58 s) •••••••••••••••————— 77%
Running 2007 of 2020 (564/721) (6.73 s) •••••••••••••••————— 78%
Running 2008 of 2020 (576/721) (6.89 s) ••••••••••••••••———— 80%
Running 2009 of 2020 (588/721) (7.04 s) ••••••••••••••••———— 82%
Running 2010 of 2020 (600/721) (7.20 s) ••••••••••••••••———— 83%
Running 2011 of 2020 (612/721) (7.36 s) •••••••••••••••••——— 85%
Running 2012 of 2020 (624/721) (7.53 s) •••••••••••••••••——— 87%
Running 2013 of 2020 (636/721) (7.69 s) •••••••••••••••••——— 88%
Running 2014 of 2020 (648/721) (7.85 s) ••••••••••••••••••—— 90%
Running 2015 of 2020 (660/721) (8.00 s) ••••••••••••••••••—— 92%
Running 2016 of 2020 (672/721) (8.16 s) ••••••••••••••••••—— 93%
Running 2017 of 2020 (684/721) (8.33 s) •••••••••••••••••••— 95%
Running 2018 of 2020 (696/721) (8.49 s) •••••••••••••••••••— 97%
Running 2019 of 2020 (708/721) (8.65 s) •••••••••••••••••••— 98%
Running 2020 of 2020 (720/721) (8.82 s) •••••••••••••••••••• 100%
Final population size: 6139.
Run finished for "None" after 8.8 s
Defining parameters and running simulations¶
Parameters are defined as a dictionary. In FPsim, we categorize our parameters as:
Basic parameters Age limits Durations Pregnancy outcomes Fecundity and exposure MCPR
The most common category of parameters to change in FPsim is the basic category, which includes the location (i.e. Senegal, northern India), the starting population, the starting year, and the initial number of agents. We can define thiese as:
[2]:
pars = dict(
n_agents = 10_000,
location = 'senegal',
start_year = 1960,
end_year = 2020,
)
Running a simulation is pretty easy. In fact, running a sim with the parameters we defined above is just:
[3]:
sim = fp.Sim(pars)
sim.run()
Running 1960 of 2020 ( 0/721) (0.20 s) ———————————————————— 0%
Running 1961 of 2020 (12/721) (0.38 s) ———————————————————— 2%
Running 1962 of 2020 (24/721) (0.57 s) ———————————————————— 3%
Running 1963 of 2020 (36/721) (0.76 s) •——————————————————— 5%
Running 1964 of 2020 (48/721) (0.96 s) •——————————————————— 7%
Running 1965 of 2020 (60/721) (1.16 s) •——————————————————— 8%
Running 1966 of 2020 (72/721) (1.36 s) ••—————————————————— 10%
Running 1967 of 2020 (84/721) (1.56 s) ••—————————————————— 12%
Running 1968 of 2020 (96/721) (1.76 s) ••—————————————————— 13%
Running 1969 of 2020 (108/721) (1.97 s) •••————————————————— 15%
Running 1970 of 2020 (120/721) (2.18 s) •••————————————————— 17%
Running 1971 of 2020 (132/721) (2.40 s) •••————————————————— 18%
Running 1972 of 2020 (144/721) (2.61 s) ••••———————————————— 20%
Running 1973 of 2020 (156/721) (2.83 s) ••••———————————————— 22%
Running 1974 of 2020 (168/721) (3.05 s) ••••———————————————— 23%
Running 1975 of 2020 (180/721) (3.28 s) •••••——————————————— 25%
Running 1976 of 2020 (192/721) (3.50 s) •••••——————————————— 27%
Running 1977 of 2020 (204/721) (3.73 s) •••••——————————————— 28%
Running 1978 of 2020 (216/721) (3.97 s) ••••••—————————————— 30%
Running 1979 of 2020 (228/721) (4.21 s) ••••••—————————————— 32%
Running 1980 of 2020 (240/721) (4.45 s) ••••••—————————————— 33%
Running 1981 of 2020 (252/721) (4.69 s) •••••••————————————— 35%
Running 1982 of 2020 (264/721) (4.94 s) •••••••————————————— 37%
Running 1983 of 2020 (276/721) (5.19 s) •••••••————————————— 38%
Running 1984 of 2020 (288/721) (5.58 s) ••••••••———————————— 40%
Running 1985 of 2020 (300/721) (5.84 s) ••••••••———————————— 42%
Running 1986 of 2020 (312/721) (6.11 s) ••••••••———————————— 43%
Running 1987 of 2020 (324/721) (6.38 s) •••••••••——————————— 45%
Running 1988 of 2020 (336/721) (6.65 s) •••••••••——————————— 47%
Running 1989 of 2020 (348/721) (6.93 s) •••••••••——————————— 48%
Running 1990 of 2020 (360/721) (7.21 s) ••••••••••—————————— 50%
Running 1991 of 2020 (372/721) (7.50 s) ••••••••••—————————— 52%
Running 1992 of 2020 (384/721) (7.79 s) ••••••••••—————————— 53%
Running 1993 of 2020 (396/721) (8.09 s) •••••••••••————————— 55%
Running 1994 of 2020 (408/721) (8.40 s) •••••••••••————————— 57%
Running 1995 of 2020 (420/721) (8.71 s) •••••••••••————————— 58%
Running 1996 of 2020 (432/721) (9.02 s) ••••••••••••———————— 60%
Running 1997 of 2020 (444/721) (9.34 s) ••••••••••••———————— 62%
Running 1998 of 2020 (456/721) (9.67 s) ••••••••••••———————— 63%
Running 1999 of 2020 (468/721) (10.00 s) •••••••••••••——————— 65%
Running 2000 of 2020 (480/721) (10.34 s) •••••••••••••——————— 67%
Running 2001 of 2020 (492/721) (10.69 s) •••••••••••••——————— 68%
Running 2002 of 2020 (504/721) (11.04 s) ••••••••••••••—————— 70%
Running 2003 of 2020 (516/721) (11.40 s) ••••••••••••••—————— 72%
Running 2004 of 2020 (528/721) (11.76 s) ••••••••••••••—————— 73%
Running 2005 of 2020 (540/721) (12.14 s) •••••••••••••••————— 75%
Running 2006 of 2020 (552/721) (12.66 s) •••••••••••••••————— 77%
Running 2007 of 2020 (564/721) (13.05 s) •••••••••••••••————— 78%
Running 2008 of 2020 (576/721) (13.45 s) ••••••••••••••••———— 80%
Running 2009 of 2020 (588/721) (13.86 s) ••••••••••••••••———— 82%
Running 2010 of 2020 (600/721) (14.28 s) ••••••••••••••••———— 83%
Running 2011 of 2020 (612/721) (14.70 s) •••••••••••••••••——— 85%
Running 2012 of 2020 (624/721) (15.13 s) •••••••••••••••••——— 87%
Running 2013 of 2020 (636/721) (15.58 s) •••••••••••••••••——— 88%
Running 2014 of 2020 (648/721) (16.03 s) ••••••••••••••••••—— 90%
Running 2015 of 2020 (660/721) (16.51 s) ••••••••••••••••••—— 92%
Running 2016 of 2020 (672/721) (16.98 s) ••••••••••••••••••—— 93%
Running 2017 of 2020 (684/721) (17.47 s) •••••••••••••••••••— 95%
Running 2018 of 2020 (696/721) (17.97 s) •••••••••••••••••••— 97%
Running 2019 of 2020 (708/721) (18.48 s) •••••••••••••••••••— 98%
Running 2020 of 2020 (720/721) (19.00 s) •••••••••••••••••••• 100%
Final population size: 62232.
Run finished for "None" after 19.2 s
[3]:
Sim(<no label>; n=10000; 1960-2020; results: b=68914 ☠=11805 pop=62232)
This will generate a results dictionary sim.results. For example, the number of pregnancies in the sim can be found using sim.results['pregnancies'].
Rather than creating a parameter dictionary, any valid parameter can also be passed to the sim directly. For example, exactly equivalent to the above is:
[4]:
sim = fp.Sim(n_agents=10e3, location='senegal', start_year=1960, end_year=2020)
sim.run()
Running 1960 of 2020 ( 0/721) (0.25 s) ———————————————————— 0%
Running 1961 of 2020 (12/721) (0.42 s) ———————————————————— 2%
Running 1962 of 2020 (24/721) (0.61 s) ———————————————————— 3%
Running 1963 of 2020 (36/721) (0.80 s) •——————————————————— 5%
Running 1964 of 2020 (48/721) (1.00 s) •——————————————————— 7%
Running 1965 of 2020 (60/721) (1.20 s) •——————————————————— 8%
Running 1966 of 2020 (72/721) (1.40 s) ••—————————————————— 10%
Running 1967 of 2020 (84/721) (1.59 s) ••—————————————————— 12%
Running 1968 of 2020 (96/721) (1.80 s) ••—————————————————— 13%
Running 1969 of 2020 (108/721) (2.01 s) •••————————————————— 15%
Running 1970 of 2020 (120/721) (2.21 s) •••————————————————— 17%
Running 1971 of 2020 (132/721) (2.42 s) •••————————————————— 18%
Running 1972 of 2020 (144/721) (2.64 s) ••••———————————————— 20%
Running 1973 of 2020 (156/721) (2.86 s) ••••———————————————— 22%
Running 1974 of 2020 (168/721) (3.08 s) ••••———————————————— 23%
Running 1975 of 2020 (180/721) (3.30 s) •••••——————————————— 25%
Running 1976 of 2020 (192/721) (3.53 s) •••••——————————————— 27%
Running 1977 of 2020 (204/721) (3.76 s) •••••——————————————— 28%
Running 1978 of 2020 (216/721) (4.00 s) ••••••—————————————— 30%
Running 1979 of 2020 (228/721) (4.24 s) ••••••—————————————— 32%
Running 1980 of 2020 (240/721) (4.47 s) ••••••—————————————— 33%
Running 1981 of 2020 (252/721) (4.72 s) •••••••————————————— 35%
Running 1982 of 2020 (264/721) (4.97 s) •••••••————————————— 37%
Running 1983 of 2020 (276/721) (5.22 s) •••••••————————————— 38%
Running 1984 of 2020 (288/721) (5.47 s) ••••••••———————————— 40%
Running 1985 of 2020 (300/721) (5.73 s) ••••••••———————————— 42%
Running 1986 of 2020 (312/721) (6.00 s) ••••••••———————————— 43%
Running 1987 of 2020 (324/721) (6.27 s) •••••••••——————————— 45%
Running 1988 of 2020 (336/721) (6.54 s) •••••••••——————————— 47%
Running 1989 of 2020 (348/721) (6.82 s) •••••••••——————————— 48%
Running 1990 of 2020 (360/721) (7.10 s) ••••••••••—————————— 50%
Running 1991 of 2020 (372/721) (7.39 s) ••••••••••—————————— 52%
Running 1992 of 2020 (384/721) (7.68 s) ••••••••••—————————— 53%
Running 1993 of 2020 (396/721) (7.98 s) •••••••••••————————— 55%
Running 1994 of 2020 (408/721) (8.28 s) •••••••••••————————— 57%
Running 1995 of 2020 (420/721) (8.59 s) •••••••••••————————— 58%
Running 1996 of 2020 (432/721) (8.90 s) ••••••••••••———————— 60%
Running 1997 of 2020 (444/721) (9.22 s) ••••••••••••———————— 62%
Running 1998 of 2020 (456/721) (9.73 s) ••••••••••••———————— 63%
Running 1999 of 2020 (468/721) (10.06 s) •••••••••••••——————— 65%
Running 2000 of 2020 (480/721) (10.40 s) •••••••••••••——————— 67%
Running 2001 of 2020 (492/721) (10.75 s) •••••••••••••——————— 68%
Running 2002 of 2020 (504/721) (11.10 s) ••••••••••••••—————— 70%
Running 2003 of 2020 (516/721) (11.46 s) ••••••••••••••—————— 72%
Running 2004 of 2020 (528/721) (11.82 s) ••••••••••••••—————— 73%
Running 2005 of 2020 (540/721) (12.20 s) •••••••••••••••————— 75%
Running 2006 of 2020 (552/721) (12.58 s) •••••••••••••••————— 77%
Running 2007 of 2020 (564/721) (12.97 s) •••••••••••••••————— 78%
Running 2008 of 2020 (576/721) (13.37 s) ••••••••••••••••———— 80%
Running 2009 of 2020 (588/721) (13.78 s) ••••••••••••••••———— 82%
Running 2010 of 2020 (600/721) (14.20 s) ••••••••••••••••———— 83%
Running 2011 of 2020 (612/721) (14.62 s) •••••••••••••••••——— 85%
Running 2012 of 2020 (624/721) (15.05 s) •••••••••••••••••——— 87%
Running 2013 of 2020 (636/721) (15.50 s) •••••••••••••••••——— 88%
Running 2014 of 2020 (648/721) (15.96 s) ••••••••••••••••••—— 90%
Running 2015 of 2020 (660/721) (16.43 s) ••••••••••••••••••—— 92%
Running 2016 of 2020 (672/721) (16.90 s) ••••••••••••••••••—— 93%
Running 2017 of 2020 (684/721) (17.39 s) •••••••••••••••••••— 95%
Running 2018 of 2020 (696/721) (17.88 s) •••••••••••••••••••— 97%
Running 2019 of 2020 (708/721) (18.39 s) •••••••••••••••••••— 98%
Running 2020 of 2020 (720/721) (18.91 s) •••••••••••••••••••• 100%
Final population size: 62232.
Run finished for "None" after 19.1 s
[4]:
Sim(<no label>; n=10000; 1960-2020; results: b=68914 ☠=11805 pop=62232)
You can mix and match too – pass in a parameter dictionary with default options, and then include other parameters as keywords (including overrides; keyword arguments take precedence). For example:
[5]:
sim = fp.Sim(pars, n_agents=100) # Use parameters defined above, except start with 100 agents instead of 10,000
sim.run()
Running 1960 of 2020 ( 0/721) (0.05 s) ———————————————————— 0%
Running 1961 of 2020 (12/721) (0.17 s) ———————————————————— 2%
Running 1962 of 2020 (24/721) (0.28 s) ———————————————————— 3%
Running 1963 of 2020 (36/721) (0.40 s) •——————————————————— 5%
Running 1964 of 2020 (48/721) (0.52 s) •——————————————————— 7%
Running 1965 of 2020 (60/721) (0.64 s) •——————————————————— 8%
Running 1966 of 2020 (72/721) (0.76 s) ••—————————————————— 10%
Running 1967 of 2020 (84/721) (0.88 s) ••—————————————————— 12%
Running 1968 of 2020 (96/721) (1.00 s) ••—————————————————— 13%
Running 1969 of 2020 (108/721) (1.12 s) •••————————————————— 15%
Running 1970 of 2020 (120/721) (1.24 s) •••————————————————— 17%
Running 1971 of 2020 (132/721) (1.36 s) •••————————————————— 18%
Running 1972 of 2020 (144/721) (1.48 s) ••••———————————————— 20%
Running 1973 of 2020 (156/721) (1.60 s) ••••———————————————— 22%
Running 1974 of 2020 (168/721) (1.72 s) ••••———————————————— 23%
Running 1975 of 2020 (180/721) (1.84 s) •••••——————————————— 25%
Running 1976 of 2020 (192/721) (1.97 s) •••••——————————————— 27%
Running 1977 of 2020 (204/721) (2.09 s) •••••——————————————— 28%
Running 1978 of 2020 (216/721) (2.21 s) ••••••—————————————— 30%
Running 1979 of 2020 (228/721) (2.33 s) ••••••—————————————— 32%
Running 1980 of 2020 (240/721) (2.45 s) ••••••—————————————— 33%
Running 1981 of 2020 (252/721) (2.58 s) •••••••————————————— 35%
Running 1982 of 2020 (264/721) (2.70 s) •••••••————————————— 37%
Running 1983 of 2020 (276/721) (2.82 s) •••••••————————————— 38%
Running 1984 of 2020 (288/721) (2.95 s) ••••••••———————————— 40%
Running 1985 of 2020 (300/721) (3.07 s) ••••••••———————————— 42%
Running 1986 of 2020 (312/721) (3.19 s) ••••••••———————————— 43%
Running 1987 of 2020 (324/721) (3.31 s) •••••••••——————————— 45%
Running 1988 of 2020 (336/721) (3.43 s) •••••••••——————————— 47%
Running 1989 of 2020 (348/721) (3.55 s) •••••••••——————————— 48%
Running 1990 of 2020 (360/721) (3.68 s) ••••••••••—————————— 50%
Running 1991 of 2020 (372/721) (3.80 s) ••••••••••—————————— 52%
Running 1992 of 2020 (384/721) (3.92 s) ••••••••••—————————— 53%
Running 1993 of 2020 (396/721) (4.04 s) •••••••••••————————— 55%
Running 1994 of 2020 (408/721) (4.17 s) •••••••••••————————— 57%
Running 1995 of 2020 (420/721) (4.29 s) •••••••••••————————— 58%
Running 1996 of 2020 (432/721) (4.41 s) ••••••••••••———————— 60%
Running 1997 of 2020 (444/721) (4.53 s) ••••••••••••———————— 62%
Running 1998 of 2020 (456/721) (4.66 s) ••••••••••••———————— 63%
Running 1999 of 2020 (468/721) (4.78 s) •••••••••••••——————— 65%
Running 2000 of 2020 (480/721) (4.90 s) •••••••••••••——————— 67%
Running 2001 of 2020 (492/721) (5.03 s) •••••••••••••——————— 68%
Running 2002 of 2020 (504/721) (5.15 s) ••••••••••••••—————— 70%
Running 2003 of 2020 (516/721) (5.28 s) ••••••••••••••—————— 72%
Running 2004 of 2020 (528/721) (5.41 s) ••••••••••••••—————— 73%
Running 2005 of 2020 (540/721) (5.53 s) •••••••••••••••————— 75%
Running 2006 of 2020 (552/721) (5.66 s) •••••••••••••••————— 77%
Running 2007 of 2020 (564/721) (5.78 s) •••••••••••••••————— 78%
Running 2008 of 2020 (576/721) (5.91 s) ••••••••••••••••———— 80%
Running 2009 of 2020 (588/721) (6.03 s) ••••••••••••••••———— 82%
Running 2010 of 2020 (600/721) (6.16 s) ••••••••••••••••———— 83%
Running 2011 of 2020 (612/721) (6.28 s) •••••••••••••••••——— 85%
Running 2012 of 2020 (624/721) (6.41 s) •••••••••••••••••——— 87%
Running 2013 of 2020 (636/721) (6.53 s) •••••••••••••••••——— 88%
Running 2014 of 2020 (648/721) (6.66 s) ••••••••••••••••••—— 90%
Running 2015 of 2020 (660/721) (6.78 s) ••••••••••••••••••—— 92%
Running 2016 of 2020 (672/721) (6.91 s) ••••••••••••••••••—— 93%
Running 2017 of 2020 (684/721) (7.03 s) •••••••••••••••••••— 95%
Running 2018 of 2020 (696/721) (7.16 s) •••••••••••••••••••— 97%
Running 2019 of 2020 (708/721) (7.28 s) •••••••••••••••••••— 98%
Running 2020 of 2020 (720/721) (7.41 s) •••••••••••••••••••• 100%
Final population size: 597.
Run finished for "None" after 7.4 s
[5]:
Sim(<no label>; n=100; 1960-2020; results: b=672 ☠=126 pop=597)
Now you know how to set up an initial sim using FPsim. In the next tutorial, we will explore plotting options.