class Sim(pars=None, location=None, label=None, track_children=False, **kwargs)[source]#

Bases: BaseSim

The Sim class handles the running of the simulation: the creation of the population and the dynamics of the epidemic. This class handles the mechanics of the actual simulation, while BaseSim takes care of housekeeping (saving, loading, exporting, etc.). Please see the BaseSim class for additional methods.

  • pars (dict) – parameters to modify from their default values

  • location (str) – name of the location (country) to look for data file to load

  • label (str) – the name of the simulation (useful to distinguish in batch runs)

  • track_children (bool) – whether to track links between mothers and their children (slow, so disabled by default)

  • kwargs (dict) – additional parameters; passed to fp.make_pars()


sim = fp.Sim()
sim = fp.Sim(n_agents=10e3, location='senegal', label='My small Seneagl sim')




Count the number of points in timesteps between the starting year and the ending year.


Create a time vector array at intervals of the timestep in years



For an ex nihilo person, figure out if they are male and female, and how old

initialize_urban(n, urban_prop)[source]#

Get initial distribution of urban

initialize_empowerment(n, ages, sexes)[source]#

Get initial distribution of women’s empowerment metrics/attributes

initialize_education(n, ages, sexes, urban)[source]#

Get initial distribution of education goal, attainment and whether a woman has reached their education goal

initialize_partnered(n, ages, sexes)[source]#

Get initial distribution of age at first partnership

make_people(n=1, age=None, sex=None, method=None, debut_age=None)[source]#

Set up each person

init_people(output=False, **kwargs)[source]#

Create the people


Update all contraceptive method matrices to have probabilities that follow a trend closest to the year the sim is on based on mCPR in that year


Update infant and maternal mortality for the sim’s current year. Update general mortality trend as this uses a spline interpolation instead of an array


Add link between newly added individuals and their mothers


Apply each intervention in the model


Apply each analyzer in the model


Make any final updates to interventions (e.g. to shrink)


Make any final updates to analyzers (e.g. to shrink)


Run the simulation


Stores snapshot of who is currently pregnant, their parity, and various postpartum states in final step of model for use in calibration


Export all sim results to a dataframe


include_range (bool) – if True, and if the sim results have best, high, and low, then export all of them; else just best

plot(to_plot=None, xlims=None, ylims=None, do_save=None, do_show=True, filename='fpsim.png', style=None, fig_args=None, plot_args=None, axis_args=None, fill_args=None, label=None, new_fig=True, colors=None)[source]#

Plot the results – can supply arguments for both the figure and the plots.

  • to_plot (str/dict) – What to plot (e.g. ‘default’ or ‘cpr’), or a dictionary of result:label pairs

  • xlims (list/dict) – passed to pl.xlim() (use [None, None] for default)

  • ylims (list/dict) – passed to pl.ylim()

  • do_save (bool) – Whether or not to save the figure. If a string, save to that filename.

  • do_show (bool) – Whether to show the plots at the end

  • filename (str) – If a figure is saved, use this filename

  • style (bool) – Custom style arguments

  • fig_args (dict) – Passed to pl.figure() (plus nrows and ncols for overriding defaults)

  • plot_args (dict) – Passed to pl.plot()

  • axis_args (dict) – Passed to pl.subplots_adjust()

  • fill_args (dict) – Passed to pl.fill_between())

  • label (str) – Label to override default

  • new_fig (bool) – Whether to create a new figure (true unless part of a multisim)

  • colors (list/dict) – Colors for plots with multiple lines

plot_age_first_birth(do_show=None, do_save=None, fig_args=None, filename='first_birth_age.png')[source]#

Plot age at first birth

  • fig_args (dict) – arguments to pass to pl.figure()

  • do_show (bool) – whether or not the user wants to show the output plot (default: true)

  • do_save (bool) – whether or not the user wants to save the plot to filepath (default: false)

  • filename (str) – the name of the path to output the plot


Computes method mix proportions from a sim object


list of lists where list[years_after_start][method_index] == proportion of fecundity aged women using that method on that year

format_method_df(method_list=None, timeseries=False)[source]#

Outputs a dataframe for method mix plotting for either a single year or a timeseries

  • method_list (list) – list of proportions where each index is equal to the integer value of the corresponding method

  • timeseries (boolean) – if true, provides a dataframe with data from every year, otherwise a method_list is required for the year


pandas.DataFrame with columns [“Percentage”, “Method”, “Sim”, “Seed”] and optionally “Year” if timeseries