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

Bases: BaseSim

The Sim class handles the running of the simulation. 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.

When a Sim is initialized, it triggers the creation of the population. Methods related to creating, initializing, and updating people can be found in the People class.

  • 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 Senegal 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



Fully initialize the Sim with people and result storage


Initialize result storage. Most default results are either arrays or lists; these are all stored in Any other results with different formats can also be added here.


Initialize people by calling the People constructor and initialization methods. See for details of people construction.


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)


Clean up and reset people’s attributes at the end of a time step


Expand people’s size


Update logic of a single time step


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