Sim

class Sim(pars=None, label=None, people=None, demographics=None, diseases=None, networks=None, interventions=None, analyzers=None, connectors=None, copy_inputs=True, data=None, **kwargs)

Bases: Base

The Sim object

All Starsim simulations run via the Sim class. It is responsible for initializing and running all modules and generating results.

Parameters:

• pars (SimPars/dict) – either an ss.SimPars object, or a nested dictionary; can include all other arguments

• label (str) – the human-readable name of the simulation

• people (People) – if provided, use this ss.People object

• demographics (str/Demographics/list) – a string naming the demographics module to use, the module itself, or a list

• diseases (str/Disease/list) – as above, for diseases

• networks (str/Network/list) – as above, for networks

• interventions (str/Intervention/list) – as above, for interventions

• analyzers (str/Analyzer/list) – as above, for analyzers

• connectors (str/Connector/list) – as above, for connectors

• copy_inputs (bool) – if True, copy modules as they’re inserted into the sim (allowing reuse in other sims, but meaning they won’t be updated)

• data (df) – a dataframe (or dict) of data, with a column “time” plus data of the form “module.result”, e.g. “hiv.new_infections” (used for plotting only)

• kwargs (dict) – merged with pars; see ss.SimPars for all parameter values

Examples:

sim = ss.Sim(diseases='sir', networks='random') # Simplest Starsim sim; equivalent to ss.demo()
sim = ss.Sim(diseases=ss.SIR(), networks=ss.RandomNet()) # Equivalent using objects instead of strings
sim = ss.Sim(diseases=['sir', ss.SIS()], networks=['random', 'mf']) # Example using list inputs; can mix and match types

Attributes

modules	Return iterator over all Module instances (stored in standard places) in the Sim
now	Shortcut to self.t.now()
ti	Get the current module timestep
timevec	Shortcut to self.t.timevec

Methods

property modules

Return iterator over all Module instances (stored in standard places) in the Sim

init(force=False, **kwargs)

Perform all initializations for the sim

Parameters:

• force (bool) – whether to overwrite sim attributes even if they already exist

• kwargs (dict) – passed to ss.People()

init_time()

Time indexing; derived values live in the sim rather than in the pars

init_people(verbose=None, **kwargs)

Initialize people within the sim Sometimes the people are provided, in which case this just adds a few sim properties to them. Other time people are not provided and this method makes them.

Parameters:

• verbose (int) – detail to print

• kwargs (dict) – passed to ss.make_people()

init_sim_attrs(force=False)

Move initialized modules to the sim

init_mods_pre()

Initialize all the modules with the sim

init_dists()

Initialize the distributions

init_people_vals()

Initialize the People states with actual values

init_mod_vals()

Initialize values in other modules, including networks and time parameters

reset_time_pars(force=True)

Reset the time parameters in the modules; used for imposing the sim’s timestep on the modules

init_results()

Create initial results that are present in all simulations

init_data(data=None)

Initialize or add data to the sim

start_step()

Start the step – only print progress; all actual changes happen in the modules

finish_step()

Finish the simulation timestep

run_one_step(verbose=None)

Run a single sim step; only used for debugging purposes.

Note: sim.run_one_step() runs a single simulation timestep, which involves multiple function calls. In contrast, loop.run_one_step() runs a single function call.

Note: the verbose here is only for the Loop object, not the sim.

run(until=None, verbose=None)

Run the model once

finalize()

Compute final results

summarize(how='default')

Provide a quick summary of the sim; returns the last entry for count and cumulative results, and the mean otherwise.

Parameters:

how (str) – how to summarize: can be ‘mean’, ‘median’, ‘last’, or a mapping of result keys to those

shrink(inplace=True, size_limit=1.0)

“Shrinks” the simulation by removing the people and other memory-intensive attributes (e.g., some interventions and analyzers), and returns a copy of the “shrunken” simulation. Used to reduce the memory required for RAM or for saved files.

Parameters:

• inplace (bool) – whether to perform the shrinking in place (default), or return a shrunken copy instead

• size_limit (float) – print a warning if any module is larger than this size limit (set to None to disable)

Returns:

a Sim object with the listed attributes removed

Return type:

shrunken (Sim)

check_results_ready(errormsg=None)

Check that results are ready

to_df(sep='_')

Export results as a Pandas dataframe

save(filename=None, shrink=None, **kwargs)

Save to disk as a gzipped pickle.

Parameters:

• filename (str or None) – the name or path of the file to save to; if None, uses stored

• shrink (bool or None) – whether to shrink the sim prior to saving (reduces size by ~99%)

• kwargs – passed to sc.makefilepath()

Returns:

the validated absolute path to the saved file

Return type:

filename (str)

Example:

sim.save() # Saves to a .sim file

to_json(filename=None, keys=None, tostring=False, indent=2, verbose=False, **kwargs)

Export results and parameters as JSON.

Parameters:

• filename (str) – if None, return string; else, write to file

• keys (str/list) – attributes to write to json (choices: ‘pars’ and/or ‘summary’)

• verbose (bool) – detail to print

• kwargs (dict) – passed to sc.jsonify()

Returns:

A dictionary representation of the parameters and/or summary results (or write that dictionary to a file)

Examples:

json = sim.to_json()
sim.to_json('results.json')
sim.to_json('summary.json', keys='summary')

plot(key=None, fig=None, style='fancy', show_data=True, show_skipped=False, show_module=26, show_label=False, fig_kw=None, plot_kw=None, scatter_kw=None)

Plot all results in the Sim object

Parameters:

• key (str/list) – the results key to plot (by default, all); if a list, plot exactly those keys

• fig (Figure) – if provided, plot results into an existing figure

• style (str) – the plotting style to use (default “fancy”; other options are “simple”, None, or any Matplotlib style)

• show_data (bool) – plot the data, if available

• show_skipped (bool) – show even results that are skipped by default

• show_module (bool) – whether to show the module as well as the result name; if an int, show if the label is less than that length; if -1, use a newline

• show_label (str) – if ‘fig’, reset the fignum; if ‘title’, set the figure suptitle

• fig_kw (dict) – passed to plt.subplots()

• plot_kw (dict) – passed to plt.plot()

• scatter_kw (dict) – passed to plt.scatter(), for plotting the data