internals.conditions
Conditions: who something applies to
A condition is written against the attributes of the people and modules in the sim, e.g. (ppl.age > 65) & ~sir.vaccinated. Written before the sim exists, it is lazy: an expression that is evaluated each time it is needed during a run, on agents in an agent-based run and on groups in a compartmental one. A function of the sim does the same job, for anything the operators cannot say.
Used with: agents and compartments; declared and coded modules
Classes
| Name | Description |
|---|---|
| Cond | A lazy condition: an unevaluated expression over the arrays of the people and modules in a sim |
| Event | Something that happens to people at a moment: going through a transition (tr), one branch of it |
Cond
internals.conditions.Cond(op, *args)A lazy condition: an unevaluated expression over the arrays of the people and modules in a sim
Conditions are not usually created directly: they are what comparisons and logical operators give when used on arrays that have not been initialized yet, on declared states, and on stratifications.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| op | str |
the operation: a leaf (‘people’, ‘state’, ‘dim’, ‘kind’, ‘array’, ‘incidence’, ‘event’, ‘memory’, ‘move’), an operator, ‘~’, or ‘isin’ | required |
| args | list |
the operands |
Examples
ppl = ss.People(n_agents=10_000)
S, I, R = ss.states(3)
sir = ss.Disease(infection=S >> I @ 0.3*I, recovery=ss.Transition(I, R, dur=10))
eligible = (ppl.age > 65) & sir.SAttributes
| Name | Description |
|---|---|
| args | The operands; a dimension given as a product (vx.held) is named when it is read, since a product can be named after the condition is written |
| enter | For a set of states (A \| B): the event of entering it from outside it (moves within the set are not entering it) |
| ever | For an event (e.g. screening.positive): whether it has happened to each person, as a condition |
| exit | For a set of states (A \| B): the event of leaving it for a state outside it |
| frac | For a set of states ((E \| I).frac, the same as (E + I).frac), the fraction of the module’s people in them: in a rate, as an |
| n | The number of people the condition holds for: in a rate, for a set of states ((hiv.L \| hiv.A).n, the same as (hiv.L + hiv.A).n); |
| n_times | For an event: how many times it has happened to each person, e.g. screening.n_times >= 2 |
| since | For an event: the time since it last happened to each person (infinite if never), e.g. cytology.since >= ss.years(5) |
| time_in | For a set of states (A \| B): the time since entering it from outside it, in the sim’s unit (moves within the set do not reset it; NaN outside it) |
| total | For a set of states ((E \| I).total, the same as (E + I).total), the number in them in the whole population |
| uids | The agents the condition holds for now, in a sim that is running or has run (agents only): e.g. sim.interventions.screening.ever.uids, everyone ever screened (the sim’s copy of the delivery, not the one given, which the sim copies) |
| values | In a running sim, as agents: the condition’s value for each agent alive, in the order of sim.people.auids (as ss.Arr.values) |
Methods
| Name | Description |
|---|---|
| arith | Arithmetic on a condition: with an expression (a parameter, a state’s count), a typed value (ss.peryear(0.02)), or a value by level or in time (ss.by, ss.timeseries), it is an expression for a rate, e.g. bss.person.age; otherwise a condition. A set of states (Ia | Is) is their sum, so 0.3(Ia | Is) is 0.3*(Ia + Is) |
| as_states | The states a condition is a set of, for a count of them (see n) |
| clip | The value kept between two values, as an expression for a rate (np.clip(0.5*ss.person.age, 0, 1) calls this) |
| compare | A comparison: with an expression (e.g. a fitted ss.par), an expression that is 1 or 0, for a rate; otherwise a condition |
| eval | Evaluate the condition; ctx supplies the value of each leaf (see Selector) |
| evaluate_in | For cond[uids] and cond.values: the value for each agent (by UID), in the sim of a module the condition reads |
| isin | Whether the value is one of some values, as a condition, e.g. ppl.age.isin([1, 2]) |
arith
internals.conditions.Cond.arith(op, a, b)Arithmetic on a condition: with an expression (a parameter, a state’s count), a typed value (ss.peryear(0.02)), or a value by level or in time (ss.by, ss.timeseries), it is an expression for a rate, e.g. bss.person.age; otherwise a condition. A set of states (Ia | Is) is their sum, so 0.3(Ia | Is) is 0.3*(Ia + Is)
as_states
internals.conditions.Cond.as_states(kind)The states a condition is a set of, for a count of them (see n)
clip
internals.conditions.Cond.clip(min=None, max=None, out=None)The value kept between two values, as an expression for a rate (np.clip(0.5*ss.person.age, 0, 1) 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 |
compare
internals.conditions.Cond.compare(op, other)A comparison: with an expression (e.g. a fitted ss.par), an expression that is 1 or 0, for a rate; otherwise a condition
eval
internals.conditions.Cond.eval(ctx)Evaluate the condition; ctx supplies the value of each leaf (see Selector)
evaluate_in
internals.conditions.Cond.evaluate_in(sim_only=False)For cond[uids] and cond.values: the value for each agent (by UID), in the sim of a module the condition reads
isin
internals.conditions.Cond.isin(values)Whether the value is one of some values, as a condition, e.g. ppl.age.isin([1, 2])
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| values | list |
the values | required |
Event
internals.conditions.Event(kind, obj, dst=None)Something that happens to people at a moment: going through a transition (tr), one branch of it (tr.to(B)), or entering or leaving a state or a set of states (X.enter, (A | B).exit), where entering a set means arriving from outside it
An event is a condition, true for the agents it happened to from the moment they moved until the same point in the next step; it can be given to when= or ss.on(); it remembers, per person, whether (.ever), how often (.n_times), and how long ago (.since) it happened (agents only); and in a running sim, .uids are those agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kind | str |
‘tr’, ‘to’, ‘enter’, or ‘exit’ | required |
| obj | Transition / list |
the transition; or the states, as ss.States or (module, name) pairs |
required |
| dst | State | for ‘to’, the destination | None |
Attributes
| Name | Description |
|---|---|
| memory_key | The name its memory is kept under in its module (see ss.solvers.Agents.record()): the transition’s, or e.g. infection_to_I, I_enter |
| names | For entering or leaving: the names of the states |
| uids | The agents the event happened to, in a running sim |
Methods
| Name | Description |
|---|---|
| spec | What the engine is asked for: see ss.solvers.Agents.event_uids() |
spec
internals.conditions.Event.spec()What the engine is asked for: see ss.solvers.Agents.event_uids()
Functions
| Name | Description |
|---|---|
| ref | A reference to a state or transition of a module by its path, resolved when the sim is initialized: for a module made before the others exist |
ref
internals.conditions.ref(path)A reference to a state or transition of a module by its path, resolved when the sim is initialized: for a module made before the others exist
It stands for whatever is at the path: a state is a condition (the people in it), with .enter and .exit its events, as for a declared state; a transition ('ng.cure') is its event, the people who went through it. A path as a string, wherever a keyword takes a condition or an event (who='sir.I', when='sir.infection'), is the same as ss.ref() of it.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| path | str |
the module and the state or transition, e.g. 'hpv18.X' |
required |
Examples
canceled = (S + P + C + L) >> Z @ ss.on(ss.ref('hpv18.X') | ss.ref('hpv31.X'))
seek = ss.treat(drug, when=ss.ref('ng.C').enter) # For a module made from a string
test = ss.screen(dx, when=ss.ref('ng.infection')) # The same as when='ng.infection'