Installing and getting started with FPsim is quite simple.
To install, just type pip install fpsim
. 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:
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
sim = fp.Sim()
sim.run()
fig = sim.plot()
Parameters are defined as a dictionary. In FPsim, we categorize our parameters as:
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:
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:
sim = fp.Sim(pars)
sim.run()
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:
sim = fp.Sim(n_agents=10e3, location='senegal', start_year=1960, end_year=2020)
sim.run()
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:
sim = fp.Sim(pars, n_agents=100) # Use parameters defined above, except start with 100 agents instead of 10,000
sim.run()
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.
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:
sim.plot() # the default
sim.plot('cpr')
In the next tutorial, you'll learn how to build intervention scenarios using multiple sims and plot those.