converters

converters

Import models from other frameworks, and export sims to them

ss.import_from(filename, format=...) reads another framework’s model into a sim, and ss.export_to(sim, format) writes a sim in another framework’s format; see docs/design/16-interop.md in the lingua_franca repo. Each importer reads its format into an ss.converters.Source, and ss.converters.build() writes that as Starsim code by the same rules for every format (ss.converters.write()) and runs the code to make the sim: the code is kept in sim.imported.code, how each rate was read is printed, and what could not be translated is listed as ss.errors.ImportIncomplete and kept in sim.imported.

Used with: agents and compartments; declared and coded modules

Classes

Name	Description
Code	Python to write as it is, for a value an importer gives that code_value() does not write, e.g. a network
Source	A model read from another framework, before it is built into a sim

Code

converters.Code()

Python to write as it is, for a value an importer gives that code_value() does not write, e.g. a network

It exists so that an importer can pass on what has no plain value.

Source

converters.Source(name, format, file=None)

A model read from another framework, before it is built into a sim

An importer fills this in from the source, then build() writes it as Starsim code (write()) and runs the code to make the sim. Every rate is an expression in Python syntax, in which a state’s name means the number of people in it.

Parameters

Name	Type	Description	Default
name	str	the model’s name	required
format	str	the format it was read from, e.g. ‘emulsion’	required
file	str	the file it was read from, if any	None

Methods

Name	Description
add_flow	A flow between states
add_outcome	A reported quantity: a fraction of a flow, or of another outcome, with a delay (see ss.outcome)
add_par	A parameter: a number in the sim’s unit, maybe with bounds and a prior (ss.Dist) for calibration
add_state	A state; init is a number of people
skip	Something in the source that was not translated: listed once, however often its code is written (write() writes each disease twice, the first time for the names it takes)
stratify	A stratification of the disease, as the arguments to ss.Disease.stratify()

add_flow

converters.Source.add_flow(
    src,
    dst,
    rate=None,
    per='person',
    dur=None,
    name=None,
    label=None,
    p=None,
    min_stay=None,
    noise=None,
)

A flow between states

Parameters

Name	Type	Description	Default
src	str	the state people leave, or None for an inflow	required
dst	str	the state they enter, or None for an outflow	required
rate	str / float	the rate, as an expression of states and parameters	None
per	str	‘person’ if the rate is for each person in src, ‘total’ if it is the whole flow (gamma * I out of I)	'person'
dur	any	a dwell time instead of a rate, as a duration or a distribution of durations	None
name	str	the name in the source, if it has one	None
label	str	a description	None
p	list	for a branch (dst a list of states), the probability of each destination, as expressions of parameters (None for the rest)	None
min_stay	dur	a minimum stay in src before the flow can happen (see ss.Transition)	None
noise	str / float	sigma of gamma white noise on the rate, as an expression of parameters, in the square root of the model’s unit of time (see ss.Transition)	None

add_outcome

converters.Source.add_outcome(
    name,
    source,
    p=None,
    delay=None,
    dur=None,
    doc=None,
    likelihood=None,
)

A reported quantity: a fraction of a flow, or of another outcome, with a delay (see ss.outcome)

Parameters

Name	Type	Description	Default
name	str	the outcome’s name	required
source	str / list	the name of a flow (from add_flow()), several to add together, or another outcome	required
p	float / str	the fraction of the source, as a number (a parameter named p_) or the name of a parameter	None
delay	any	the time from the source event, as a duration or a distribution	None
dur	any	how long each stays in the outcome, if the number in it is wanted	None
doc	str	a description of the fraction, for its parameter	None
likelihood	func	a function of the parameters (by name) that gives the likelihood, e.g. lambda pars: ss.nbinom(n=pars.k)	None

add_par

converters.Source.add_par(name, value, doc=None, bounds=None, prior=None)

A parameter: a number in the sim’s unit, maybe with bounds and a prior (ss.Dist) for calibration

Parameters

Name	Type	Description	Default
name	str	the name of the parameter	required
value	float	its value	required
doc	str	what it is	None
bounds	tuple	its bounds, for calibration	None
prior	ss.Dist	its prior, for calibration	None

add_state

converters.Source.add_state(name, init=None, people=True, label=None)

A state; init is a number of people

Parameters

Name	Type	Description	Default
name	str	the name of the state	required
init	float	the initial number of people	None
people	bool	whether the state counts people	True
label	str	the label of the state	None

skip

converters.Source.skip(name, why)

Something in the source that was not translated: listed once, however often its code is written (write() writes each disease twice, the first time for the names it takes)

Parameters

Name	Type	Description	Default
name	str	the name of what was not translated	required
why	str	why not	required

stratify

converters.Source.stratify(**kwargs)

A stratification of the disease, as the arguments to ss.Disease.stratify()

Parameters

Name	Type	Description	Default
**kwargs	dict	passed to ss.Disease.stratify()

Functions

Name	Description
build	Build a sim from one or more models read from another framework, by running the code write() gives
convert	Read another framework’s model, as import_from() does, and save the Starsim code for it: read the model once, then run the code (which takes a fraction of the time)
export_to	Write a sim in another format (sim.save() and ss.save() write Starsim’s own, a gzipped pickle that ss.load() reads)
import_from	Read another framework’s model into a sim, e.g. ss.import_from('workbook.xlsx')
sniff	The format of a file of another framework’s model, if it can be told from the file (else None)
to_hub	The runs of a MultiSim as a submission to a hub (in the hubverse format): each target, by scenario, location, and period
write	The Starsim code of one or more models read from another framework

build

converters.build(sources, verbose=None, **kwargs)

Build a sim from one or more models read from another framework, by running the code write() gives

Each source becomes a disease. Prints how each flow was read and, as ss.errors.ImportIncomplete, what could not be translated; both are kept in sim.imported, with the code (sim.imported.code), which is the user’s to keep and change (e.g. sc.savetext('model.py', sim.imported.code)).

Parameters

Name	Type	Description	Default
sources	Source / list	the model, as read by an importer, or several (e.g. one for each state machine)	required
verbose	bool	whether to print how each flow was read (default: ss.options.verbose)	None
kwargs	dict	passed to ss.Sim(), after each source’s config

Returns

Name	Type	Description
		An ss.Sim (not yet initialized)

convert

converters.convert(source, filename=None, format=None, **kwargs)

Read another framework’s model, as import_from() does, and save the Starsim code for it: read the model once, then run the code (which takes a fraction of the time)

Parameters

Name	Type	Description	Default
source	str / any	the file (or, for some formats, the model object)	required
filename	str	where to save the code (default: beside the source, with its name and .py)	None
format	str	the framework (see import_from())	None
kwargs	dict	passed to the importer

Returns

Name	Type	Description
		The ss.Sim, as import_from() gives it, with sim.imported.filename the file the code was saved to

Example

sim = ss.converters.convert('tb_framework.xlsx', format='atomica', databook='IND.xlsx', filename='tb_india.py')
sim.run() # Or later: python tb_india.py, or runpy.run_path('tb_india.py')['sim']

export_to

converters.export_to(sim, format, filename=None, verbose=None)

Write a sim in another format (sim.save() and ss.save() write Starsim’s own, a gzipped pickle that ss.load() reads)

What the format cannot carry is listed as ss.errors.LossyExport; the export still writes everything it can.

Parameters

Name	Type	Description	Default
sim	ss.Sim	the sim, with declared diseases	required
format	str	one of ss.converters.exporters (e.g. ‘sbml’, ‘odin’, ‘epimodel’, ‘summer2’)	required
filename	str	the file to write, if any	None
verbose	bool	whether to print what was exported (by default, unless something was lost)	None

Returns

Name	Type	Description
		The text of the export (bytes for Atomica’s workbook; for flepiMoP, a dict of its files by name, the config first)

Examples

ss.export_to(sim, 'sbml', filename='sir.xml')
print(ss.export_to(sim, 'odin'))

import_from

converters.import_from(source, format=None, **kwargs)

Read another framework’s model into a sim, e.g. ss.import_from('workbook.xlsx')

Use it to run, check, or extend a model built elsewhere without rewriting it by hand. Check sim.imported for anything that was not translated; to keep the Starsim code for the model (faster to run again, and editable), use ss.converters.convert().

Parameters

Name	Type	Description	Default
source	str / any	the file (or, for some formats, the model object)	required
format	str	the framework, one of ss.converters.importers; if not given, told from the file or object (see sniff())	None
kwargs	dict	passed to the importer

Returns

Name	Type	Description
		An ss.Sim, with sim.imported saying how it was read and what was not translated

sniff

converters.sniff(source)

The format of a file of another framework’s model, if it can be told from the file (else None)

to_hub

converters.to_hub(
    msim,
    targets,
    origin_date=None,
    by=None,
    every='week',
    output_type='quantile',
    quantiles=hub_quantiles,
    location=None,
)

The runs of a MultiSim as a submission to a hub (in the hubverse format): each target, by scenario, location, and period

Each scenario (the label of its sim) is its own scenario_id, and the periods are counted from origin_date. A target’s name says what it is: one starting “cum” is the total since the origin date, one starting “peak size” is the largest value of a period (with no horizon), and any other is a flow’s total over each period, or a count at its end.

Parameters

Name	Type	Description	Default
msim	ss.MultiSim	the runs	required
targets	dict	the hub’s name (or a list of names) for each result, e.g. dict(incidHosp=['inc hosp', 'cum hosp', 'peak size hosp'])	required
origin_date	date	the date the periods are counted from (default: the start of the runs); for runs without dates, a time, which the origin_date column then holds	None
by	str	the dimension whose levels are the locations (default: one location, the total)	None
every	str	the period: ‘day’ or ‘week’ (of the sim’s steps, which must then be days)	'week'
output_type	str / list	‘quantile’ (of the runs of each scenario), ‘sample’ (each run, by its position in its scenario), or both	'quantile'
quantiles	list	the quantiles (default: the 23 that the US hubs ask for)	hub_quantiles
location	str	the name of the single location, if by is not given	None

Returns a long dataframe with columns origin_date, scenario_id, location, target, horizon, output_type, output_type_id, and value.

Example

msim = ss.parallel({'baseline': s1, 'lockdown': s2}, n_runs=20)
hub = ss.converters.to_hub(msim, targets=dict(infection=['inc inf', 'cum inf']), origin_date='2020-03-01', by='patch')

write

converters.write(sources, **kwargs)

The Starsim code of one or more models read from another framework

Each source becomes a declared disease (ss.Disease), with its parameters, states, and transitions as variables; the code ends with the sim (sim = ss.Sim(...)). It says where the model came from, how each rate was read, and what was not translated. This is the code build() runs, kept as sim.imported.code.

Parameters

Name	Type	Description	Default
sources	Source / list	the model, as read by an importer, or several (e.g. one for each state machine)	required
kwargs	dict	passed to ss.Sim(), after each source’s config

Returns

Name	Type	Description
		An sc.obj of the code, how each flow was read (choices, a line each), and what was guessed about each transition (guessed, by disease and transition)