Sim#

class Sim(pars=None, sim_pars=None, people_pars=None, fp_pars=None, contra_pars=None, edu_pars=None, death_pars=None, fp_module=None, contraception_module=None, education_module=None, label=None, people=None, demographics=None, diseases=None, networks=None, interventions=None, analyzers=None, connectors=None, dataloader=None, copy_inputs=True, **kwargs)[source]#

Bases: Sim

The Sim class handles the running of the simulation. It extends the Starim Sim class, so all Starsim Sim methods are available to FPsims.

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; accepts parameters for all constituent modules of FPsim

  • sim_pars (dict) – simulation-specific parameters; see SimPars within parameters.py for details

  • fp_pars (dict) – FP-specific parameters; FPPars within parameters.py for details

  • contra_pars (dict) – parameters for the contraception module; see make_contra_pars() in parameters.py for details

  • edu_pars (dict) – parameters for the education module; see make_edu_pars() in parameters.py for details

  • fp_module (FPmod) – the family planning module; defaults to fp.FPmod()

  • contraception_module (ContraceptiveChoice) – the contraception choice module; defaults to fp.StandardChoice()

  • education_module (Education) – the education module; defaults to fp.Education()

  • people (People) – the people object; defaults to fp.People()

  • demographics (list) – list of demographics modules; defaults to [ss.Deaths()]

  • diseases (list) – list of disease modules (default None)

  • networks (list) – list of network modules (default None)

  • interventions (list) – list of intervention modules (default None)

  • analyzers (list) – list of analyzer modules (default None)

  • connectors (list) – list of connector modules (default None, can add empowerment or other examples)

  • dataloader (Dataloader) – data loader to use; defaults to the one associated with the location; see data_utils.py

  • copy_inputs (bool) – whether to copy input dicts (default True, recommended)

  • kwargs (dict) – additional parameters belonging to any constituent module

Examples:

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

Attributes

dt

Get the current module timestep

label

Get the sim label from the parameters, if available.

module_dict

Return a dictionary of all Module instances; see sim.module_list for the list version

module_list

Return a list of all Module instances (stored in standard places) in the Sim; see sim.module_dict for the dict version

now

Shortcut to self.t.now()

ti

Get the current module timestep

timevec

Shortcut to self.t.timevec

Methods

static remap_pars(pars)[source]#

Remap the parameters to the new names. This is useful for backwards compatibility.

process_pars(pars=None, sim_pars=None, people_pars=None, fp_pars=None, contra_pars=None, edu_pars=None, death_pars=None, sim_kwargs=None, **kwargs)[source]#

Separate the parameters into simulation and fp-specific parameters.

init(force=False)[source]#

Fully initialize the Sim with modules, people and result storage

init_results()[source]#

Initialize the results dictionary. This is called at the start of the simulation.

plot(key=None, to_plot=None, xlims=None, ylims=None, do_save=None, do_show=True, filename='fpsim.png', style=None, fig=None, fig_args=None, fig_kw=None, plot_kw=None, alpha=None, is_jupyter=False, 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.

Parameters:

  • key (str/dict) – Alias for to_plot

  • 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

Parameters:

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

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

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

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

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

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

list_available_results()[source]#

Pretty print availbale results keys, sorted alphabetically