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: object

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

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	Return the current time, i.e. the time vector at the current timestep.

Methods

property now

Return the current time, i.e. the time vector at the current timestep

property modules

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

init(**kwargs)

Perform all initializations for the sim; most heavy lifting is done by the parameters

init_time_attrs()

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

Initialize the distributions

init_vals()

Initialize the states and other objects with values

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

disp()

Print a full version of the sim

shrink(skip_attrs=None, in_place=True)

“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:

• skip_attrs (list) – a list of attributes to skip (remove) in order to perform the shrinking; default “people”

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

Returns:

a Sim object with the listed attributes removed

Return type:

shrunken (Sim)

to_df(sep='_')

Export results as a Pandas dataframe

save(filename=None, keep_people=None, skip_attrs=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

• keep_people (bool or None) – whether to keep the people

• skip_attrs (list) – attributes to skip saving

• 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

static load(filename, *args, **kwargs)

Load from disk from a gzipped pickle

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, 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

• 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