Sim

class Sim(pars=None, location=None, label=None, track_children=False, **kwargs)

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.

Parameters:

• 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()

Examples:

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

Attributes

n
npts	Count the number of points in timesteps between the starting year and the ending year.
tvec	Create a time vector array at intervals of the timestep in years

Methods

initialize(force=False)

Fully initialize the Sim with people and result storage

init_results()

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

init_people()

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

update_methods()

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_mortality()

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.

update_mothers()

Add link between newly added individuals and their mothers

apply_interventions()

Apply each intervention in the model

apply_analyzers()

Apply each analyzer in the model

finalize_interventions()

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

finalize_analyzers()

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

finalize_people()

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

grow_population(new_ppl)

Expand people’s size

step()

Update logic of a single time step

run(verbose=None)

Run the simulation

store_postpartum()

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

to_df(include_range=False)

Export all sim results to a dataframe

Parameters:

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)

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

Parameters:

• 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')

Plot age at first birth

Parameters:

• 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

compute_method_usage()

Computes method mix proportions from a sim object

Returns:

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)

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

Parameters:

• 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

Returns:

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