sim

sim

User API for creating an STI simulation

Classes

Name	Description
Sim	A subclass of starsim.Sim that is specifically designed for STI simulations.

Sim

sim.Sim(
    pars=None,
    sim_pars=None,
    sti_pars=None,
    nw_pars=None,
    dem_pars=None,
    label=None,
    people=None,
    demographics=None,
    diseases=None,
    networks=None,
    interventions=None,
    analyzers=None,
    connectors=None,
    custom=None,
    datafolder=None,
    data=None,
    **kwargs,
)

A subclass of starsim.Sim that is specifically designed for STI simulations. It initializes with a structured sexual network and includes STI-specific analyzers.

Parameters

Name	Type	Description	Default
pars	dict	Parameters for the simulation	None
label	str	A label for the simulation.	None
people	ss.People	People object containing the agents in the simulation.	None
demographics	(ss.Demographics, list)	Demographic modules to include.	None
diseases	(ss.Disease, list)	Disease modules to include.	None
networks	(ss.Network, list)	Network modules to include.	None
interventions	(ss.Intervention, list)	Intervention modules to include.	None
analyzers	(ss.Analyzer, list)	Analyzer modules to include.	None
connectors	bool or list	If True, use default connectors; otherwise, provide a list of connectors.	None
copy_inputs	bool	Whether to copy input parameters or not.	required
data		Additional data to be used in the simulation.	None
e.g.			required
Example usage			required
# demographics, and connectors. If you want to specify parameters for the diseases, you can do so like this			required
You can also pass in custom parameters for the default modules, such as networks or demographics, like this			required
These are all in addition to the standard starsim input style using module instances directly, e.g.			required
and in the kwargs), the order of precedence is as follows			required

Methods

Name	Description
init	Perform all initializations for the sim
plot	Plot sim results. If key is the name of a disease in the sim (e.g. ‘hiv’),
process_connectors	Auto-add coinfection connectors for disease pairs that have a registered
process_demographics	Process the location to create people and demographics if not provided.
process_networks	Process the network parameters to create network module.
process_stis	Look up a disease by its name and return the corresponding module.
remap_pars	Remap any parameter names to match the expected format for STIs and networks.
separate_pars	Sort all incoming pars into per-category dicts (sim, sti, nw, dem,

init

sim.Sim.init(force=False, **kwargs)

Perform all initializations for the sim

plot

sim.Sim.plot(key=None, **kwargs)

Plot sim results. If key is the name of a disease in the sim (e.g. ‘hiv’), shows a curated panel for that disease. Otherwise falls back to the standard starsim plot.

Parameters

Name	Type	Description	Default
key	str / list	Result key(s) to plot, or a disease name for curated plots	None
**kwargs		Passed to ss.Sim.plot()	{}

Returns

Name	Type	Description
		matplotlib.figure.Figure

process_connectors

sim.Sim.process_connectors()

Auto-add coinfection connectors for disease pairs that have a registered sti.<d1>_<d2> class (e.g. hiv_syph, hiv_ng). Skipped if the user already supplied any connectors — pass your own list to take full control. Connector module pars (e.g. rel_sus_hiv_syph=3.5) passed as kwargs to sti.Sim are routed to whichever auto-added connector accepts them.

Auto-routing of kwargs only resolves against the default connector classes (sti.merged_connector_pars). Custom connectors supplied via connectors=[...] are not introspected — pass their pars to the constructor directly: connectors=[MyConn(rel_sus_hiv_syph=3.5)]. Mixing connectors=[...] with kwargs that match default-connector pars raises rather than silently dropping them.

process_demographics

sim.Sim.process_demographics()

Process the location to create people and demographics if not provided.

process_networks

sim.Sim.process_networks()

Process the network parameters to create network module. If networks are provided, they will be used; otherwise, use default networks (usual case)

process_stis

sim.Sim.process_stis()

Look up a disease by its name and return the corresponding module.

remap_pars

sim.Sim.remap_pars(pars)

Remap any parameter names to match the expected format for STIs and networks. This is useful for ensuring that parameters are correctly interpreted by the modules.

separate_pars

sim.Sim.separate_pars(
    pars=None,
    sim_pars=None,
    sti_pars=None,
    nw_pars=None,
    dem_pars=None,
    sim_kwargs=None,
    verbose=True,
    **kwargs,
)

Sort all incoming pars into per-category dicts (sim, sti, nw, dem, connector). Most of the work is delegated to sti.route_pars; this method handles sti.Sim-specific bits: legacy renames, nested per-module dicts (hiv=dict(...)), defaults, and stashing user-supplied pars (_user_sti_pars, _user_nw_pars, _user_dem_pars, _user_connector_pars) for the two-phase init’s XOR checks.

Parameters

Name	Type	Description	Default
verbose	bool	If True, route_pars prints one line per cross-category broadcast. See sti.route_pars for design.	True