Skip to main content

internals.expressions

internals.expressions

Expressions: the parameters (ss.par), counts, and arithmetic that rates, results, and conditions are made of, and how they are evaluated and printed

They exist so that a rate or result written once can be read by any solver, printed as an equation, and differentiated. They belong to declared models, and a module written as code can also use ss.par and do arithmetic on such values.

Used with: agents and compartments; declared and coded modules

Classes

Name Description
Expr Base class for anything that can appear in a rate or a result: states,
attr A value for each person: drawn at an event, recorded at an event, drawn once when the person is made (a trait), or derived
mother A condition or expression evaluated on each unborn agent’s mother (1/0 for a condition, or its value), and 0 for anyone born, unless include_born=True
par A named parameter with bounds, a prior, and provenance

Expr

internals.expressions.Expr()

Base class for anything that can appear in a rate or a result: states, counts, parameters, and arithmetic on them.

Attributes

Name Description
frac The fraction of the module’s people in these states
leaves All the leaves (parameters, states, and counts) in this expression
n The number in these states, e.g. (S + I + R).n; or a weighted count, each person counted by a value of theirs, e.g. (ss.by(biting=w)*I).n
n_infectious The number in these states, each counted by their infectiousness (rel_trans, with the products and modifiers on it, times the state’s), e.g. what people shed into an environment: shedding*A.n_infectious
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

Methods

Name Description
clip The expression kept between two values (np.clip(x, lo, hi) calls this)
clip
internals.expressions.Expr.clip(min=None, max=None, out=None)

The expression kept between two values (np.clip(x, lo, hi) calls this)

Parameters
Name Type Description Default
min float the lowest value; if None, no lower limit None
max float the highest value; if None, no upper limit None
out None not used; present since np.clip() passes it None

attr

internals.expressions.attr(
    value,
    when=None,
    combine='last',
    init=None,
    name=None,
    label=None,
    **kwargs,
)

A value for each person: drawn at an event, recorded at an event, drawn once when the person is made (a trait), or derived

Which it is depends on value and when=: a distribution with when= is drawn when the event happens to someone; an expression (or the name of another attribute) with when= is recorded then, as it was just before the move; a dict of them by event (a transition, tr.to(B), X.enter, …) records each event’s own value, with no when=; a distribution with no when= is a trait; and an expression, or a dict of one by state (states not listed give NaN), with no when= is derived, worked out when it is read. Attributes set on the same event are set in the order they are declared, and each sees the ones before it. As agents only.

Parameters

Name Type Description Default
value Dist / Expr / str / dict the distribution, the expression, the name of another attribute, a dict of expressions by state (or by a sum of states), or a dict of distributions or expressions by event required
when Event / Transition the event(s) that set it, joined with \|; none for a trait or a derived attribute None
combine str / func how a new value is combined with the one already held: ‘last’ (the default), ‘first’, ‘max’, ‘min’, ‘sum’, or fn(old, new) 'last'
init float / Dist / Expr the value before any event (default NaN, or 0 for combine='sum'): a number, or a distribution or an expression (e.g. of ss.person) drawn or worked out for each person when they are made (at the start, once placed in their states, and at birth) None
name str the name; if not given, taken from the keyword or class attribute it is assigned to None
label str a human-readable name None

Examples

cd4_latent = ss.attr(ss.normal(500, 50), when=infection)                  # Drawn
cd4_preart = ss.attr('cd4', when=start_art)                               # Recorded, just before starting
rel_sev    = ss.attr(ss.normal(1, 0.2))                                 # A trait
cd4        = ss.attr({latent: cd4_latent, falling: cd4_latent*(1 - falling.progress)}) # Derived
dose       = ss.attr({contact: dose_hi, environment: cfu.n/N*frac})        # Recorded, a value for each event
nab        = ss.attr(ss.uniform(0.5, 0.95), when=clearance, combine='max', init=0)
n_inf      = ss.attr(1, when=I.enter, combine='sum', init=ss.poisson(mean=ss.person.age/20)) # Past infections at the start

Attributes

Name Description
default The value before any event, as a number (one drawn for each person, init_value, is NaN, or 0 for combine='sum', until drawn)
init_value The distribution or expression the value before any event is drawn from or worked out from for each person, if it is one
kind ‘drawn’, ‘recorded’, ‘trait’, or ‘derived’ (a dict by event is ‘recorded’, each event’s value drawn or worked out)

Methods

Name Description
combined A new value combined with the one held
combined
internals.expressions.attr.combined(old, new)

A new value combined with the one held

mother

internals.expressions.mother(x, include_born=False)

A condition or expression evaluated on each unborn agent’s mother (1/0 for a condition, or its value), and 0 for anyone born, unless include_born=True

Usable in rates, p=, who=, when=ss.on(), and modifier conditions. Agents only: solver='auto' chooses them, and a compartmental solver stops with a CapabilityError.

With include_born=True it is evaluated on the mother of anyone who has one, born or not, e.g. to reach the newborns of mothers who tested positive. An agent with no mother in the sim gets 0. A mother who has died or left is in none of her states, so a condition on them is false, but what was remembered of her (e.g. anc.positive.since) is still read.

Parameters

Name Type Description Default
x Cond / State / Expr e.g. syph.Pv \| syph.S2, hiv.rel_trans, or preg.P.time_in required
include_born bool also for agents already born, not only the unborn False

Examples

mtct = S >> C @ beta_m2c * ss.mother(Pv | Ph | S2 | EL | LL)
fetal_eff = 0.98 - 0.23*(ss.mother(preg.P.time_in) > ss.weeks(27)) # 0.75 after 27 weeks; a comparison is 1 or 0
newborn = ss.screen(test, who=ss.mother(anc.positive.since <= ss.years(1), include_born=True), when=preg.birth)

par

internals.expressions.par(
    value=None,
    bounds=None,
    prior=None,
    source=None,
    doc=None,
    name=None,
    label=None,
)

A named parameter with bounds, a prior, and provenance

A plain number, typed quantity, or distribution is accepted wherever a parameter is; use ss.par when it needs a name, bounds (so it can be fitted), or a source.

Parameters

Name Type Description Default
value any a number, typed quantity (e.g. ss.perday(0.1)), distribution, or function None
bounds list the lower and upper bounds; a parameter with bounds can be calibrated None
prior ss.Dist the prior distribution, for calibration None
source str where the value came from (shown under the parameter by describe()) None
doc str a description of the parameter (likewise) None
name str the name; if not given, taken from the keyword or variable it is assigned to None
label str a human-readable name None

Examples

beta = ss.par(0.05, bounds=[0.01, 0.5])
S, I, R = ss.states(3)
infection = S >> I @ beta * I

Attributes

Name Description
raw The current value (the module holds this parameter itself, so a value set there is this one)

Methods

Name Description
inline An anonymous value written inline, e.g. the 0.5 in 0.5*A, kept as a number rather than made a parameter of the module; not for the user
merge Take what another parameter gives (its value, bounds, prior, and description), keeping this one’s name and module, e.g. for sir.pars.beta = ss.par(0.1, bounds=[0.05, 1])
inline
internals.expressions.par.inline(value, name=None)

An anonymous value written inline, e.g. the 0.5 in 0.5*A, kept as a number rather than made a parameter of the module; not for the user

merge
internals.expressions.par.merge(other)

Take what another parameter gives (its value, bounds, prior, and description), keeping this one’s name and module, e.g. for sir.pars.beta = ss.par(0.1, bounds=[0.05, 1])

Parameters
Name Type Description Default
other ss.par the parameter to take values from required