sim

sim

Defines the Sim class, the core class of the FP model (FPsim).

Classes

Name	Description
Sim	The Sim class handles the running of the simulation. It extends the Starim Sim class, so all Starsim Sim methods

Sim

sim.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,
)

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

Name	Type	Description	Default
pars	dict	parameters; accepts parameters for all constituent modules of FPsim	None
sim_pars	dict	simulation-specific parameters; see SimPars within parameters.py for details	None
fp_pars	dict	FP-specific parameters; FPPars within parameters.py for details	None
contra_pars	dict	parameters for the contraception module; see make_contra_pars() in parameters.py for details	None
edu_pars	dict	parameters for the education module; see make_edu_pars() in parameters.py for details	None
fp_module	FPmod	the family planning module; defaults to fp.FPmod()	None
contraception_module	ContraceptiveChoice	the contraception choice module; defaults to fp.StandardChoice()	None
education_module	Education	the education module; defaults to fp.Education()	None
people	People	the people object; defaults to fp.People()	None
demographics	list	list of demographics modules; defaults to [ss.Deaths()]	None
diseases	list	list of disease modules (default None)	None
networks	list	list of network modules (default None)	None
interventions	list	list of intervention modules (default None)	None
analyzers	list	list of analyzer modules (default None)	None
connectors	list	list of connector modules (default None, can add empowerment or other examples)	None
dataloader	Dataloader	data loader to use; defaults to the one associated with the location; see data_utils.py	None
copy_inputs	bool	whether to copy input dicts (default True, recommended)	True
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')

Methods

Name	Description
format_method_df	Outputs a dataframe for method mix plotting for either a single year or a timeseries
init	Fully initialize the Sim with modules, people and result storage
init_results	Initialize the results dictionary. This is called at the start of the simulation.
list_available_results	Pretty print availbale results keys, sorted alphabetically
plot	Plot the results – can supply arguments for both the figure and the plots.
plot_age_first_birth	Plot age at first birth
process_pars	Separate the parameters into simulation and fp-specific parameters.
remap_pars	Remap the parameters to the new names. This is useful for backwards compatibility.

format_method_df

sim.Sim.format_method_df(method_list=None, timeseries=False)

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

Parameters

Name	Type	Description	Default
method_list	list	list of proportions where each index is equal to the integer value of the corresponding method	None
timeseries	boolean	if true, provides a dataframe with data from every year, otherwise a method_list is required for the year	False

Returns

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

init

sim.Sim.init(force=False)

Fully initialize the Sim with modules, people and result storage

init_results

sim.Sim.init_results()

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

list_available_results

sim.Sim.list_available_results()

Pretty print availbale results keys, sorted alphabetically

plot

sim.Sim.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,
)

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

Parameters

Name	Type	Description	Default
key	str / dict	Alias for to_plot	None
to_plot	str / dict	What to plot (e.g. ‘default’ or ‘cpr’), or a dictionary of result:label pairs	None
xlims	list / dict	passed to pl.xlim() (use [None, None] for default)	None
ylims	list / dict	passed to pl.ylim()	None
do_save	bool	Whether or not to save the figure. If a string, save to that filename.	None
do_show	bool	Whether to show the plots at the end	True
filename	str	If a figure is saved, use this filename	'fpsim.png'
style	bool	Custom style arguments	None
fig_args	dict	Passed to pl.figure() (plus nrows and ncols for overriding defaults)	None
plot_args	dict	Passed to pl.plot()	None
axis_args	dict	Passed to pl.subplots_adjust()	None
fill_args	dict	Passed to pl.fill_between())	None
label	str	Label to override default	None
new_fig	bool	Whether to create a new figure (true unless part of a multisim)	True
colors	list / dict	Colors for plots with multiple lines	None

plot_age_first_birth

sim.Sim.plot_age_first_birth(
    do_show=None,
    do_save=None,
    fig_args=None,
    filename='first_birth_age.png',
)

Plot age at first birth

Parameters

Name	Type	Description	Default
fig_args	dict	arguments to pass to pl.figure()	None
do_show	bool	whether the user wants to show the output plot (default: true)	None
do_save	bool	whether the user wants to save the plot to filepath (default: false)	None
filename	str	the name of the path to output the plot	'first_birth_age.png'

process_pars

sim.Sim.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,
)

Separate the parameters into simulation and fp-specific parameters.

remap_pars

sim.Sim.remap_pars(pars)

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