internals.transitions

internals.transitions

States, transitions, and the expressions that drive them.

A model is a set of ss.State objects and the ss.Transition objects between them. A transition can be written with operators or in full, which build the same object:

S >> I @ 0.3 * I                                # Operators
ss.Transition(S, I, rate=0.3 * I)               # In full

The ss.graph.Graph class (in internals/graph.py) collects the states and transitions of one module, names them, fills in defaults (recording each guess), and checks them. The expressions are in ss.expressions, the values that vary (ss.by, ss.timeseries, ss.seasonal) in ss.parameters, how a model is shown in ss.display, and its stratifications in ss.dimensions.

Used with: agents and compartments; declared modules

Classes

Name	Description
State	Something a person can be in, or a count of something that is not people
Transition	A movement between states
lifetable	A life table: how many die at each age, which `ss.death(lifetable=)` and `ss.Deaths(lifetable=)` take as a death rate for each age band (see `hazards()`);
outcome	A reported quantity: a flow worked out from other flows, which moves nobody

State

internals.transitions.State(
    label=None,
    init=None,
    init_n=None,
    people=None,
    rel_sus=1.0,
    rel_trans=1.0,
    infected=False,
    keep_time=False,
    name=None,
    **kwargs,
)

Something a person can be in, or a count of something that is not people

A state is a compartment when the model runs as an ODE and a boolean array over agents when it runs as agents; the declaration is the same.

Parameters

Name	Type	Description	Default
label	`str`	a human-readable name, for plots (e.g. `S = ss.State('Susceptible')`)	`None`
init	`float`	the fraction of people who start in the state (1.0 is everyone); for a state that is not people, its starting amount	`None`
init_n	`int`	instead, the number of people who start in the state	`None`
people	`bool`	whether this state holds people (the default), or is a count of something else (`people=False`: bacteria in the water, mosquitoes); `people=True` says so explicitly, for a group of people that only an inflow fills	`None`
rel_sus	`float`	susceptibility multiplier while in this state (one value; for a value by group, `ss.modify(dis.rel_sus, multiply=ss.by(risk=[...]))`)	`1.0`
rel_trans	`float`	infectiousness multiplier while in this state (likewise)	`1.0`
infected	`bool`	whether the people in it are infected, which the disease otherwise works out from its force of infection (the states people are infected into, and those that infect them: `E` and `I` in `S >> E @ beta*I`); once any state is said to be, the infected states are exactly those said to be. The disease’s infected states give the results `infected`, the number in them, and `prevalence`, their fraction of everyone in its states (unless it defines its own); `infected = E + I`, given to the disease, says the same for several states	`False`
keep_time	`bool`	as agents, keep the time each person entered the state (`ti_<name>`) for code to read, e.g. the years since onset; by default it is kept only if the model reads it (a clock, a scheduled exit), to save memory	`False`
name	`str`	the name, if it is not the variable or keyword the state is given as (which it is taken from); a state that no variable holds takes its label as its name, if that is one word (`ss.Disease(ss.State('S'), ...)`)	`None`

Examples

S, R = ss.states(2)
I = ss.State(init=0.01)     # 1% of people
E = ss.State(init_n=10)     # 10 people
V = ss.State('Vaccinated', rel_sus=0.2)
A = ss.State(keep_time=True) # Code reads mod.ti_A
H = ss.State('Hospitalized', infected=True) # Counted in the results infected and prevalence, though it does not transmit

Attributes

Name	Description
enter	The event of entering this state: for `when=` (or `ss.on()`), or `.uids`
exit	The event of leaving this state
given_init	Whether a starting value is given (`init=` or `init_n=`)
progress	The fraction of the scheduled dwell time in this state that has elapsed, from 0 to 1 (NaN outside it)
time_in	Time since this person last entered the state, in the sim’s unit (NaN outside it)
total	The number in these states in the whole population: in a model with places, in every place, not only the same one as with .n

Transition

internals.transitions.Transition(
    source=None,
    dest=None,
    rate=None,
    dur=None,
    p=notgiven,
    stages=None,
    name=None,
    label=None,
    who=None,
    when=None,
    move=None,
    increment=None,
    min_stay=None,
    noise=None,
    acquisition=None,
    per_strain=False,
)

A movement between states

Usually built with the operators (S >> I @ rate); ss.birth() and ss.death() also return an ss.Transition.

Parameters

Name	Type	Description	Default
source	State / `list`	the source state, several states (a list, or a sum `I + R`), or `ss.unborn` (births) or `ss.outside` (arrivals) for an inflow	`None`
dest	State / `dict`	the destination state; several (a split), as a dict of each and its probability (`{D: p_death, R: None}`, None for the rest); or `ss.dead` (deaths) or `ss.outside` (leaving) for an outflow	`None`
rate	`any`	a hazard: a number, `ss.per`, `ss.prob`, an expression of states and parameters, or a function; a transmission is a rate with the source of infection in it (`rate=beta * I`)	`None`
dur	`any`	a dwell time: a duration or a distribution of durations (instead of `rate`)	`None`
p	`float` / `None`	the probability of taking it, for those it applies to (e.g. on an event); a split gives each destination’s in `dest`. With several transitions out of a state, each a branch with its own `p=`, `p=None` marks the one that takes the rest	`notgiven`
stages	`int`	the number of stages a dwell time is split into, in a row (an Erlang distribution), under every solver: more stages make the times in the state vary less around the mean	`None`
who	`Cond` / `func` / `str`	who it applies to: a condition (e.g. `ss.person.age > 30`, or a state by its path, `'sir.I'`), as for `ss.Event(who=)`; for everyone else its rate is 0	`None`
when	Event / `on` / `Cond` / `func` / `str`	what triggers it, instead of a rate (the same as `@ ss.on(...)`): an event moves the people it happens to (`when=preg.delivery`), or `ss.on(event, delay=...)` for a time after it (drawn for each person), as agents; joined to a condition with `&`, those who meet it; a condition moves people as soon as it holds (see `ss.on`); a path (`when='preg.delivery'`, as `ss.ref('preg.delivery')`) stands for whatever is there, found when the sim is initialized	`None`
move	`dict` / `StrainMove`	a change of level in a dimension as well as of state: the dimension, and the level people move to, or a pair of levels (e.g. `move=dict(risk=('low', 'high'))`, which applies only to people at the first); or a change of strains (`move=DS >> (DS, RIF)`, see `ss.strains.Strain`)	`None`
increment	`str` / `dict`	a counter that goes up as well: its name, which adds 1 (`increment='parity'`), or a dict of the amount for each (`increment=dict(parity=2)` for twins, `dict(doses=-1)`); a counter is a dimension with integer levels, whose last level is open-ended	`None`
min_stay	dur	a minimum stay: nobody leaves by this transition until they have been in its source state this long (a rate applies from then on, and a dwell time starts then)	`None`
noise	`float` / par	random variation of the rate from step to step (see below), for data that vary more than chance alone explains; sigma, which can be fitted (`noise=ss.par(0.1, bounds=[0, 0.3])`)	`None`
acquisition	`bool`	whether it is an acquisition of the disease, which `rel_sus`, a product’s efficacy against acquisition, and `ss.treat` act on. If not given: a contact-mediated transition is, and so is any other transition out of the disease’s first state if none out of it is contact-mediated (an infection by a bite rate or an EIR)	`None`
per_strain	`str`	for a disease with strains (`ss.Strains`) in a state they share, an outcome for each strain carried: `'each'` or `'first'` (see below)	`False`
name	`str`	the name; if not given, taken from the keyword or the variable it is assigned to	`None`
label	`str`	a human-readable name	`None`

Noise. noise= is sigma of gamma white noise (Bretó et al. 2009; pomp’s rgammawn): the chain binomial multiplies the rate, in each substep of length h, by a gamma draw with mean 1 and variance sigma²/h, for each group (and each particle of a filter). Sigma is in the square root of the sim’s unit (0.0878 in He et al.’s model, in years). Tau-leaping draws it for each leap (h its length), and agents once a step for each group (h the step); the ODE leaves it out (its mean), and the exact solver ('gillespie') refuses it.

Strains. With per_strain=:

'each': with a split, each strain carried takes the first destination with its own probability (the first destination’s probability times the strain’s value for the transition, or '<value>', the strains’ values of that name, with their values for the transition then multiplying its rate), and anyone left with a strain takes the second (or stays), carrying those left; e.g. cure by treatment
'first': with a rate, each strain carried has its own rate (the rate times its value), and the first to happen moves on as the only strain carried (the others are dropped); e.g. one of two strains progressing

Examples

S, I, R = ss.states(3)
infection = ss.Transition(S, I, rate=0.05 * I)
cure      = ss.Transition(I, S, rate=0) # A rate of 0: only treatment moves people along it
recovery  = ss.Transition(I, R, dur=ss.days(10))
maturing  = ss.Transition(J, A, rate=ss.perday(1), who=ss.person.age > 1) # Only adults
failure   = ss.Transition(Tx, I, rate=ss.peryear(0.1), move=DS >> (DS, RIF)) # Treatment fails, and the strain acquires resistance (DS, RIF = strains)
twins     = ss.Transition(P, PP, dur=ss.months(9), p=0.02, increment=dict(parity=2)) # Parity goes up by 2
weaning   = ss.Transition(NB, W, rate=ss.perday(0.5), min_stay=ss.days(21)) # At least 21 days old first, as EMULSION's duration
infection = ss.Transition(S, E, rate=beta*I, noise=0.0878) # Infection whose rate varies at random from step to step (He et al. 2010)
postpartum = ss.Transition(PP, NP, when=ss.on(preg.delivery, delay=ss.months(6))) # Six months after each woman's own delivery
importation = ss.Transition(S, I, rate=ss.perday(1e-4), acquisition=True) # An infection from outside, alongside one by contact

Attributes

Name	Description
dies	Whether everyone who takes it dies (`ss.death()`, `I >> ss.dead`); False for a split with `ss.dead` (see `tr.may_die`) and for people leaving alive (`ss.emigration()`)
dur	The dwell time, as a parameter (or None, if the transition has a rate)
ever	Whether each person has gone through this transition, as a condition (agents only), e.g. `who=~tb.diagnosis.ever`
n_times	How many times each person has gone through this transition (agents only), e.g. `who=tb.relapse.n_times >= 2`
p	The branch probabilities, one for each destination (or None)
since	The time since each person last went through this transition (infinite if never; agents only), e.g. `who=tb.diagnosis.since <= ss.years(2)`
uids	The agents who went through this transition, from the moment they moved until the same point in the next step

Methods

Name	Description
hazard	In a running sim, as agents: the current rate of the transition for some agents, with its modifiers (e.g. a treatment’s
incidence	A condition on how many go through the transition: the number over the last `over`, as a fraction of the people at the same level of `by`
to	The event of taking one branch of this transition, e.g. `precin.to(S)`: for `when=` (or `ss.on()`), or `.uids`

hazard

internals.transitions.Transition.hazard(uids)

In a running sim, as agents: the current rate of the transition for some agents, with its modifiers (e.g. a treatment’s efficacy, ss.modify()), per unit of the sim’s time, e.g. to weight a death requested from code (people.request_death(uids, hazard=...))

It is the rate those agents would face if they were in its source state now (0 for a transition with no rate).

Parameters

Name	Type	Description	Default
uids	`array`	the agents	required

Example

h = tb.death.hazard(uids) # The hazard of death from TB for each of these agents

incidence

internals.transitions.Transition.incidence(over=None, by=None)

A condition on how many go through the transition: the number over the last over, as a fraction of the people at the same level of by

Parameters

Name	Type	Description	Default
over	dur	the window (default, one step); a bare number is in the sim’s unit	`None`
by	`str`	a stratification, e.g. `'patch'`, so that each place is compared on its own (default: the whole population)	`None`

Examples

npi = ss.modify(sir.pars.beta, multiply=0.6, who=sir.infection.incidence(over=ss.days(7), by='patch') > 200e-5, until=ss.days(14))

to

internals.transitions.Transition.to(dst)

The event of taking one branch of this transition, e.g. precin.to(S): for when= (or ss.on()), or .uids

Parameters

Name	Type	Description	Default
dst	State	the state the branch leads to	required

lifetable

internals.transitions.lifetable(ages, deaths)

A life table: how many die at each age, which ss.death(lifetable=) and ss.Deaths(lifetable=) take as a death rate for each age band (see hazards()); as agents, ss.death(lifetable=) draws each person’s age at death once from those rates (see draw()), which is the same model

Parameters

Name	Type	Description	Default
ages	`list`	the start of each age band, in years (the last band is as wide as the one before)	required
deaths	`list`	the number, or fraction, of a cohort who die in each band (a life table’s d(x))	required

Examples

table = ss.lifetable(ages=np.arange(101), deaths=dx) # dx from a national life table
deaths = ss.death(lifetable=table)

Methods

Name	Description
draw	The age at death of people of some ages, from uniform random numbers, at the death rate of each age band (see `hazards()`): the age at
hazards	The death rate per year in each of some age groups (given by their lower edges; the last is open), as a compartmental run takes it
survive	The fraction of a cohort alive at each age

draw

internals.transitions.lifetable.draw(age, u)

The age at death of people of some ages, from uniform random numbers, at the death rate of each age band (see hazards()): the age at which the deaths they face from their age on add up to -log(1 - u)

Parameters

Name	Type	Description	Default
age	`array`	the ages of the people	required
u	`array`	uniform random numbers, one for each person	required

hazards

internals.transitions.lifetable.hazards(edges)

The death rate per year in each of some age groups (given by their lower edges; the last is open), as a compartmental run takes it

Parameters

Name	Type	Description	Default
edges	`array`	the lower edge of each age group	required

survive

internals.transitions.lifetable.survive(age)

The fraction of a cohort alive at each age

Parameters

Name	Type	Description	Default
age	`float` / `array`	the age or ages	required

outcome

internals.transitions.outcome(
    source,
    delay=None,
    dur=None,
    likelihood=None,
    name=None,
    label=None,
    **kwargs,
)

A reported quantity: a flow worked out from other flows, which moves nobody

Parameters

Name	Type	Description	Default
source	Transition / outcome / `list`	a transition, one branch of one (`cin.to(CA)`), another outcome, or a weighted sum of them, e.g. `0.5 * infection`	required
delay	`any`	the time from the source event to this one: a duration or a distribution	`None`
dur	`any`	how long each event counted stays in the outcome (e.g. a hospital stay), as a duration or a distribution; if given, also produces `n_<name>`: the number currently in it	`None`
likelihood	`ss.Dist`/func	optional likelihood, for calibration: a distribution, or a function `fn(observed, model)` returning the log-likelihood of each value (see `ss.fitting.logpdf()`)	`None`
name	`str`	the name; if not given, taken from the keyword or the variable it is assigned to	`None`
label	`str`	a human-readable name	`None`

Examples

cases = ss.outcome(0.5 * infection, delay=ss.days(5))
hosp  = ss.outcome(0.05 * infection, delay=ss.days(7), dur=ss.days(10))

Data reported by week (or any period) is compared with the outcome’s total over each period automatically; to see the weekly series, use res.cases.resample('week').

Attributes

Name	Description
flows	The flows it is worked out from, each with its weight: (transition, outcome, or name; weight)
likelihood_pars	The parameters of its likelihood: a distribution’s, or none for a function or no likelihood
weights	The weights of its sources that are expressions, e.g. the rho in rho * infection

Methods

Name	Description
source_str	The flows it is worked out from, as text, e.g. “rho * infection”

source_str

internals.transitions.outcome.source_str()

The flows it is worked out from, as text, e.g. “rho * infection”

Functions

Name	Description
birth	An inflow of people: at a crude (per-person) birth rate, e.g. `ss.birth(S, rate=ss.peryear(0.02))`; or driven by a
death	An outflow of people, e.g. `ss.death(I, rate=ss.peryear(0.1))`
emigration	People leaving the population, e.g. `ss.emigration(rate=ss.peryear(0.01))`
immigration	People arriving from outside the population, e.g. `ss.immigration(S, n=ss.peryear(100))`: a number of people per unit time
lifelong	Mark a function of the agents as giving each person a value that stays the same for life, so a run as agents works it out once for each person rather than at each step
migration	Net migration of everyone, at a rate per person of either sign: arrivals less departures, as the UN gives it, e.g. `ss.migration(rate='Albania')`
move	Move people between states of a declared disease from code, the same way under every solver
pars	Create several parameters at once, from defaults and the values given, as a class’s declared parameters are made
states	Create several states at once

birth

internals.transitions.birth(
    state=None,
    rate=None,
    when=None,
    children=1,
    p_female=None,
    name=None,
    label=None,
    **kwargs,
)

An inflow of people: at a crude (per-person) birth rate, e.g. ss.birth(S, rate=ss.peryear(0.02)); or driven by a flow, e.g. ss.birth(NP, when=preg.delivery, children=2), children for each person who goes through the transition

With when=, as agents the children are made by the module that owns the transition, with parent set to the person who went through it, and placed in each declared module’s state given by its own ss.birth(when=...) of the same transition, or else its first state. Agents only, for now.

Births of the whole population go in ss.Sim(demographics=[...]), where they are declared once for every disease’s people and run under every solver; births into one disease’s state go in the disease.

Parameters

Name	Type	Description	Default
state	State	the state people are born into (default: the disease’s first state; in `demographics=`, each disease’s)	`None`
rate	`any`	the birth rate per person per unit time, e.g. `ss.peryear(0.03)`; for the births of everyone (no `state`), it is read as `ss.Births` reads a rate: a bare number (per year) or a typed rate is per 1,000 people if above 1 per year, else per person (`30` and `ss.peryear(30)` are `ss.peryear(0.03)`) (a time series by the median of its values); a place by name is `ss.Births(birth_rate=place)`, its UN rates as agents (e.g. `rate='Kenya'`); into a state, a bare number is in the model’s unit, as any bare number in a disease	`None`
when	Transition	instead of a rate, the transition whose flow drives the births	`None`
children	`int` / Dist	the number of children each time: a number, or a distribution (drawn for each parent)	`1`
p_female	`float` / Dist	the chance a child is female (default: as for anyone added)	`None`
name	`str`	the name of the transition	`None`
label	`str`	a human-readable name	`None`

Examples

ss.Sim(sir, demographics=[ss.birth(rate=ss.peryear(0.02)), ss.death(rate=ss.peryear(0.01))])
ss.Sim(sir, demographics=[ss.birth(rate=20), ss.death(rate=10)]) # The same: above 1 per year, so per 1,000 people
ss.Sim(sir, demographics=[ss.birth(rate='Kenya'), ss.death(rate='Kenya')]) # Kenya's UN rates (as ss.Births and ss.Deaths, agents only)

death

internals.transitions.death(
    state=None,
    rate=None,
    dur=None,
    lifetable=None,
    name=None,
    label=None,
    **kwargs,
)

An outflow of people, e.g. ss.death(I, rate=ss.peryear(0.1))

Parameters

Name	Type	Description	Default
state	State / `list`	the state people die from, or several (`[E, I]`); if not given, every state that is people	`None`
rate	`any`	the death rate per person per unit time; with no state (the deaths of everyone), it is read as `ss.Deaths` reads a rate: a bare number (per year) or a typed rate is per 1,000 people if above 1 per year, else per person (`10` and `ss.peryear(10)` are `ss.peryear(0.01)`) (a time series by the median of its values); a place by name is `ss.Deaths(death_rate=place)`, its UN rates by year, sex, and age, as agents (e.g. `rate='Kenya'`)	`None`
dur	`any`	the mean time to death (instead of `rate`)	`None`
lifetable	`ss.lifetable`	instead of a rate, a life table, as a death rate for each of its age bands, by each person’s age, as `ss.Deaths(lifetable=)` takes it (which also takes one for each sex and year); as agents, each person’s age at death is drawn once from those rates, so they cannot be modified during a run (for that, give the rates by age: `rate=ss.by(age=...)`); in a compartmental run, which needs a stratification by age, it is a death rate for each age group of the model	`None`
name	`str`	the name of the transition	`None`
label	`str`	a human-readable name	`None`

emigration

internals.transitions.emigration(
    state=None,
    rate=None,
    dur=None,
    name=None,
    label=None,
)

People leaving the population, e.g. ss.emigration(rate=ss.peryear(0.01))

As ss.death(), but as agents they are recorded as having left (results.emigrated) rather than as having died.

Parameters

Name	Type	Description	Default
state	State / `list`	the state people leave from, or several; if not given, every state that is people	`None`
rate	`any`	the rate of leaving per person per unit time	`None`
dur	`any`	the mean time until leaving (instead of `rate`)	`None`
name	`str`	the name of the transition	`None`
label	`str`	a human-readable name	`None`

immigration

internals.transitions.immigration(
    state=None,
    n=None,
    name=None,
    label=None,
    **kwargs,
)

People arriving from outside the population, e.g. ss.immigration(S, n=ss.peryear(100)): a number of people per unit time

As agents they arrive at ages drawn from the population’s age distribution rather than as newborns. For arrivals at a rate per person (or net migration of either sign), use ss.migration(rate=).

Parameters

Name	Type	Description	Default
state	State	the state people arrive in (default: the disease’s first state; in `demographics=`, each disease’s)	`None`
n	`any`	the number arriving per unit time, e.g. `ss.peryear(100)`	`None`
name	`str`	the name of the transition	`None`
label	`str`	a human-readable name	`None`

lifelong

internals.transitions.lifelong(func)

Mark a function of the agents as giving each person a value that stays the same for life, so a run as agents works it out once for each person rather than at each step

For a p=, who=, or rate= that reads only what never changes for a person once they are in the sim: their sex, or an array whose value is given at birth (e.g. ss.FloatArr('stable', default=ss.choice([1, 3], p=[0.4, 0.6]))). The value is worked out as each person is first needed, and kept: one read before its array is set would be kept for life.

Parameters

Name	Type	Description	Default
func	`callable`	a function of any of `self`, `sim`, and `uids`, by name (see `ss.utils.fn_args()`): without `uids` (e.g. `fn(sim)`), giving a value for everyone; with them (`fn(sim, uids)`), for those agents	required

Returns

Name	Type	Description
		A copy of the function, marked (the function given is not changed)

Example

recover = ss.Transition(C3, C1, dur=ss.weeks(8), who=ss.lifelong(lambda sim: sim.diseases.bv.stable == 1))

migration

internals.transitions.migration(rate=None, rate_per=None, name=None)

Net migration of everyone, at a rate per person of either sign: arrivals less departures, as the UN gives it, e.g. ss.migration(rate='Albania')

A positive rate is arrivals, in proportion to the population (as agents, at the population’s ages: ss.immigration()); a negative one is departures (ss.emigration()). Both go in ss.Sim(demographics=[...]), and run under every solver. Since the rates are net, they say nothing about who migrates: as agents, those who leave are chosen at random.

The rates are read as those of ss.Births and ss.Deaths are (see ss.demographics.rate_per_of()): a bare number (per year) or a typed rate is per 1,000 people if it is above 1 per year (the median of the sizes, for a time series), else per person; rate_per= says which. A place’s UN rates are per 1,000.

Parameters

Name	Type	Description	Default
rate	`str` / `float` / `rate` / timeseries	a place by name, for its UN crude net migration rates (by year, every ten years, linearly interpolated); a bare number per year or a typed rate (e.g. `-5` or `ss.peryear(-5)` per 1,000, or `ss.peryear(-0.005)` per person), or a time series of either	`None`
rate_per	`float`	how many people the rates are per: 1000 or 1 (per person); by default, read from their size	`None`
name	`str`	the name of the transitions (by default `immigration` and `emigration`)	`None`

Returns

Name	Type	Description
		A list of the transitions: the arrivals, the departures, or both (if the rate changes sign)

Examples

ss.Sim(demographics=[ss.Births(birth_rate='Albania'), ss.Deaths(death_rate='Albania'), ss.migration(rate='Albania')])
ss.Sim(demographics=[ss.birth(rate=20), ss.death(rate=10), ss.migration(rate=3)]) # 3 more people per 1,000 a year
ss.migration(rate=-0.5, rate_per=1000) # 0.5 fewer per 1,000 a year: below 1, so rate_per= says it is per 1,000

move

internals.transitions.move(*args, p=None, n=None, uids=None, who=None)

Move people between states of a declared disease from code, the same way under every solver

A one-off move along no transition (as ss.Event(I >> R) is for a declared one). People can also be moved into the model and out of it: to ss.dead (they die) or ss.outside (they leave), and from ss.unborn (they are born) or ss.outside (they arrive), with n=. Every disease has the same people, so people who die or leave leave every disease, and people added are in each other disease’s first state, under every solver: as agents, they are agents who die or are made (a death happens at the end of the step, as people.request_death() does); in a compartmental run, the diseases tracked jointly lose and gain the same people, and a disease run apart loses them from its states in proportion, in each group, as it has them (it runs apart since its states do not depend on the others’). People added are placed in groups as declared births (ss.unborn) or arrivals (ss.outside) are. A count that is not people (ss.State(people=False), e.g. mosquitoes) moves the same way. Also disease.move(...), the same with the disease given.

Parameters

Name	Type	Description	Default
args		in any order, told apart by what they are: a move written with the states (`sir.I >> sir.R`), or the state (or a list of states) to move people from and the state to move them to, as the code sees them at run time (`sir.I`) or by name (`'I'`), the source first; the disease, which is enough to say where they come from (any of its states of people); and the agents to move (`ss.uids`), as `uids=`
p	`float`	the fraction of the people in the source to move, in each group (by default, everyone)	`None`
n	`float`	instead, the number of people to move, shared among the groups and states in proportion to who is in them	`None`
uids	uids	only these agents (those of them in the source), which needs agents; with `p=` or `n=`, a fraction or number of them	`None`
who	`Cond` / State / `func` / `str`	only the people for whom a condition holds (e.g. `ss.person.age < 15`, a group, or a state by its path, `'sir.I'`), under every solver; with `p=` or `n=`, a fraction or number of them	`None`

Returns

Name	Type	Description
		The number of people moved

Examples

ss.move(sir.I, sir.R, p=0.5) # Cure half of those infectious
ss.move(sir.I >> sir.R, p=0.5) # The same, written as a move, as for ss.Event()
ss.move(sir.S, sir.I, n=5) # Five susceptible people become infectious
ss.move(sir.S, sir.R, p=0.8, who=ss.person.age < 5) # Protect 80% of the susceptible children under 5
sir.move(uids, sir.R) # These agents, from wherever they are (also ss.move(sir, uids, sir.R), or sir.move(uids, 'R'))
self.move(self.I, self.R, uids=uids) # In a disease's own code: these agents, if they are infectious
ss.move(sir.I, ss.dead, p=0.1) # A tenth of those infectious die
ss.move(ss.outside, sir.I, n=20) # Twenty people arrive infectious
sir.move(uids, ss.dead) # These agents die, whatever their state
ss.move(mosq.Sv, ss.dead, p=0.1) # A tenth of the mosquitoes die

pars

internals.transitions.pars(defaults, **kwargs)

Create several parameters at once, from defaults and the values given, as a class’s declared parameters are made

For a disease whose states and transitions depend on its options, and so are made in __init__() rather than declared on the class (e.g. beta = ss.par(...), as ss.SIR does). Each parameter is an ss.par named after its key, so it can be fitted or set by name (ss.Sim(pars=...)). A value given takes the default’s bounds and description unless it has its own; a bare number for a typed default keeps its unit (e.g. 2 for a default of ss.peryear(1) is 2 per year); a default of None is an optional parameter, None unless given. A name that is not a default is an error.

Parameters

Name	Type	Description	Default
defaults	`dict`	the default of each parameter: a value, or an `ss.par` (with bounds, say)	required
kwargs	`dict`	the values given, e.g. the keywords of the disease’s `__init__()`

Returns an sc.obj of the parameters, by name.

Examples

defaults = dict(beta=ss.par(ss.peryear(2), bounds=[ss.peryear(0.5), ss.peryear(5)]), dur=ss.years(2), relapse=None)
p = ss.pars(defaults, beta=3) # beta is 3 per year, with the default's bounds
S, I, R = ss.states('S I R')
transitions = [S >> I @ p.beta*I, I >> R @ p.dur] + ([R >> I @ p.relapse] if p.relapse is not None else [])

states

internals.transitions.states(
    arg=None,
    infected=False,
    include_sum=False,
    **kwargs,
)

Create several states at once

Parameters

Name	Type	Description	Default
arg	`int` / `str`	the number of states, which take their names from the variables they are assigned to; or a string of names (e.g. `'S I R'`), which are used directly	`None`
infected	`bool` / `str` / `list`	which of them are infected (see `ss.State`): all of them (`True`); some, by name, with names given up front (`'E I'`); or some, by position, with a number of states (`[1, 2]`, or `range(1, 6)`)	`False`
include_sum	`bool`	also return the sum of the states, after them: the total of the people in them, often called `N`, for rates written with it: `betaI/N`, the fraction of people in `I`, which is `betaI.frac`; or the whole flow, `betaSI/N`, the same	`False`
kwargs	`dict`	instead of `arg`, the states by name, with the fraction of people who start in each (`S=0.9, I=0.1, R=0`); and any of the arguments of `ss.State`, passed to each, e.g. `people=False`

Examples

S, I, R = ss.states(3)
S, I, R = ss.states('S I R') # The same, with the names given up front
S, I, R = ss.states(S=0.99, I=0.01, R=0) # With the fraction of people who start in each
Sv, Ev, Iv = ss.states(3, people=False) # Mosquitoes: counts, not people
S, E, I, H, R = ss.states('S E I H R', infected='E I H') # H does not transmit, so is not infected unless said
S, E, I, H, R = ss.states(5, infected=range(1, 4)) # The same, by position
S, I, R, N = ss.states('S I R', include_sum=True) # N = S + I + R, the total, e.g. for S >> I @ beta*I/N