internals.graph
Not for the user: the graph of one module: its states, transitions, and parameters, collected, named, completed with defaults (each guess recorded), and checked
It exists as the one description of a declared model, which every solver runs and describe() shows, so that a model can be written once.
Used with: agents and compartments; declared modules
Classes
| Name | Description |
|---|---|
| Graph | The states and transitions of one module |
Graph
internals.graph.Graph(
module,
args=None,
members=None,
init_prev=None,
init=None,
init_n=None,
default_state=None,
names=None,
seed_n=False,
)The states and transitions of one module
The graph is built when the module is constructed. It names everything, works out which states are people and which transitions are transmissions (from their rates), turns inline values into named parameters, and checks the result. Every guess is recorded, in graph.guessed and in the guessed of each state and transition.
This class is not usually used directly: see ss.Disease.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| module | ss.Module |
the module the graph belongs to | required |
| args | list |
transitions and outcomes passed positionally | None |
| members | dict |
states, transitions, parameters, results, and functions, by name | None |
| init_prev | float |
the initial prevalence, seeded through the transmission (by default 0.01, unless a state is given an initial value) | None |
| init | dict |
the fraction of people who start in each state, by name | None |
| init_n | dict |
the number of people who start in each state, by name | None |
| seed_n | bool |
whether init_prev is a number of people (given as init_n=10) rather than a fraction |
False |
| default_state | str |
the state people are in unless they are put elsewhere (by default, the one named S or susceptible, else the first made; see resolve_people()) |
None |
| names | dict |
the names of the variables of the code that made the module, by the id of what they hold (see ss.utils.caller_names()), which name the states, transitions, and parameters given without one |
None |
Attributes
| Name | Description |
|---|---|
| acquisitions | The transitions that are an acquisition of the disease: see resolve_acquisition() |
| count_sources | The states whose numbers or fractions drive an acquisition at a rate on counts of them, which are the sources of infection without a transmission: I in S >> I @ beta*I.n (density-dependent), or beta*I.frac |
| infected | The states people carry an infection in, for what needs them (e.g. the states strains are carried in, or the number infected at the start): those |
| infection_sources | The sources of infection: of people by contact (I in beta*I), density-dependent (beta*I.n), or of a count (Ih in a bite rate Ih.n / N of mosquitoes) |
| infectious | The states that are a source of infection |
| marked | The states the model says are infected: marked (ss.State(infected=True)), or in its own result infected if that is a sum or set of its states (infected = E + I, or E \| I) |
| met_counts | The counts in a rate that a contact matrix acts on (see ss.solvers.Mixing.count_terms()): in the rate of an acquisition, the number |
| uninfected | The names of the states people can be in without ever having been infected: those reached from the first state by transitions that are not an acquisition |
Methods
| Name | Description |
|---|---|
| add | Add a named member, checking the name |
| add_flow | Add a birth, death, or migration declared for the whole population (ss.Sim(demographics=[ss.birth(...)])), after the graph is built; see ss.solvers.choose.init_flows() |
| all_pars | Every parameter in the graph, named or inline |
| bad_splits | The groups of branches with constant p= whose fractions do not sum to 1: those that apply to the people at each level named by a move= arrow are summed within that level; returns [(branches, total)] |
| check | Checks that do not need the sim |
| check_counts | Refuse a forgotten people=False: a group of states of people that no transition links to the first state |
| check_read | Refuse a state that an earlier module only read in a rate, so took as a state of its own that nothing fills, e.g. Rb.frac in disease a, declared before the disease b that Rb was meant to belong to |
| collect | Sort the members by what they are, and name them |
| counted | The states of people of this module whose number or fraction a transition reads in its rate, other than its source, if the rate grows with them: |
| counts_in | The counts (I.n, I.frac) in the rate of a transition, other than the total of the people it is divided by, e.g. I.n and not N.n in beta*I.n/N.n |
| dependence | How the rate of a transition grows with the people in other states it counts: ‘density’ (beta*I.n), ‘frequency’ (beta*I.frac, or beta*I.n/N.n), or None (see ss.expressions.dependence()) |
| destination | For the name of one destination of a transition with several, '<transition>.<state>' (e.g. 'progression.C', or 'outcome.dead' and 'outcome.stay' for ss.dead and ss.stay): the transition; otherwise None |
| destinations | The names of the destinations of the transitions with several, as destination() takes them |
| dwell_not_branch | For a multiplier (how, e.g. ‘the modifier “m”’) on a transition with several destinations chosen with p= and a dwell time: a note that it changes the dwell, not a branch, naming the destinations that would; otherwise None |
| fill_people | Fill in what depends on which states are people: the sources of the deaths of everyone (ss.death() with no state), and the people a birth rate is per person of (ss.birth()) |
| leaves | The leaves of the rates and branch probabilities of its transitions |
| linked | The groups of states of people that transitions link, in either direction: one, unless the people are in separate chains of states (e.g. a chain for each host species) |
| modifier_kind | What a modifier on a transition acts on: its probability if it is one branch of several with p= (chosen on entry) or one destination of a transition with several ('recovery.R'), and otherwise its rate |
| resolve_acquisition | Work out which transitions are an acquisition of the disease, which rel_sus, a product’s efficacy against acquisition, and ss.treat act on |
| resolve_attrs | Resolve each attribute: another attribute given by name, the cases of a derived one by state (a state, a sum of states, or a | of them), and its events |
| resolve_derived | Which states are infected, and their results. The infected states are those the model says are infected (marked |
| resolve_exits | Group the transitions out of each state: those with p= split on entry, the rest compete |
| resolve_init_prev | By default, 1% of people start infected, seeded through the transmission (frequency- or density-dependent), unless a state is given a starting value |
| resolve_pars | Turn inline values in the standard slots into named parameters (beta, dur, rate, p) |
| resolve_people | Which states are people: every state, unless it is declared a count (ss.State(people=False), e.g. mosquitoes or |
| resolve_rest | Work out where the people not given an initial state start: the first state, unless it is given an initial value of |
| resolve_starting | Let the starting values (init_prev, and each state’s init= and init_n=) leave levels out of an ss.by by label, which start at 0 (see ss.parameters.starting()); done when the sim is built, after values by name are set and before anything checks or reads them |
| resolve_states | Find the states: the ones declared, and those the transitions use |
| resolve_transitions | Give every transition a name, a source, and a rate or a dwell time |
| set_keywords | A value given as a keyword sets the parameter of that name; there is nothing else for it to be |
| set_slots | Record the kind of value each parameter of a transition is, as par.slot (which describe() uses): |
| spread_pars | The parameters whose value is a distribution across people (e.g. beta=ss.lognormal(0.3, 0.1)), other than dwell times, which are stages or are sampled on entry |
| stratify | Stratify the graph by one or more dimensions; see ss.Disease.stratify() |
| taken | Whether a member of the module has this name |
| transmitted_from | The states of people that transmission (by contact, or at a rate on counts of others) takes people from |
| unit_values | All the typed values (durations and rates) in the graph, used to infer the sim’s unit |
| unset_default_init_prev | Remove the default init_prev |
add
internals.graph.Graph.add(container, name, obj)Add a named member, checking the name
add_flow
internals.graph.Graph.add_flow(tr)Add a birth, death, or migration declared for the whole population (ss.Sim(demographics=[ss.birth(...)])), after the graph is built; see ss.solvers.choose.init_flows()
all_pars
internals.graph.Graph.all_pars()Every parameter in the graph, named or inline
bad_splits
internals.graph.Graph.bad_splits(exits)The groups of branches with constant p= whose fractions do not sum to 1: those that apply to the people at each level named by a move= arrow are summed within that level; returns [(branches, total)]
check
internals.graph.Graph.check()Checks that do not need the sim
check_counts
internals.graph.Graph.check_counts()Refuse a forgotten people=False: a group of states of people that no transition links to the first state and that only an inflow (not a birth) fills, as mosquitoes are, would otherwise silently become agents
check_read
internals.graph.Graph.check_read(state)Refuse a state that an earlier module only read in a rate, so took as a state of its own that nothing fills, e.g. Rb.frac in disease a, declared before the disease b that Rb was meant to belong to
collect
internals.graph.Graph.collect(args, members)Sort the members by what they are, and name them
counted
internals.graph.Graph.counted(tr)The states of people of this module whose number or fraction a transition reads in its rate, other than its source, if the rate grows with them: I in S >> I @ beta*I.n (density-dependent transmission) or S >> I @ beta*I.frac (frequency-dependent, by the fraction of people in I; see dependence()); none for births at a rate on counts (ss.unborn >> N @ b*N.n)
counts_in
internals.graph.Graph.counts_in(tr)The counts (I.n, I.frac) in the rate of a transition, other than the total of the people it is divided by, e.g. I.n and not N.n in beta*I.n/N.n
dependence
internals.graph.Graph.dependence(tr)How the rate of a transition grows with the people in other states it counts: ‘density’ (beta*I.n), ‘frequency’ (beta*I.frac, or beta*I.n/N.n), or None (see ss.expressions.dependence())
destination
internals.graph.Graph.destination(name)For the name of one destination of a transition with several, '<transition>.<state>' (e.g. 'progression.C', or 'outcome.dead' and 'outcome.stay' for ss.dead and ss.stay): the transition; otherwise None
destinations
internals.graph.Graph.destinations()The names of the destinations of the transitions with several, as destination() takes them
dwell_not_branch
internals.graph.Graph.dwell_not_branch(name, how, modname)For a multiplier (how, e.g. ‘the modifier “m”’) on a transition with several destinations chosen with p= and a dwell time: a note that it changes the dwell, not a branch, naming the destinations that would; otherwise None
fill_people
internals.graph.Graph.fill_people(tr)Fill in what depends on which states are people: the sources of the deaths of everyone (ss.death() with no state), and the people a birth rate is per person of (ss.birth())
leaves
internals.graph.Graph.leaves()The leaves of the rates and branch probabilities of its transitions
linked
internals.graph.Graph.linked()The groups of states of people that transitions link, in either direction: one, unless the people are in separate chains of states (e.g. a chain for each host species)
modifier_kind
internals.graph.Graph.modifier_kind(name)What a modifier on a transition acts on: its probability if it is one branch of several with p= (chosen on entry) or one destination of a transition with several ('recovery.R'), and otherwise its rate
resolve_acquisition
internals.graph.Graph.resolve_acquisition()Work out which transitions are an acquisition of the disease, which rel_sus, a product’s efficacy against acquisition, and ss.treat act on
A contact-mediated transition is one. So is any other transition of people out of the first state that is not an outflow, whatever its rate (a bite rate, an EIR, a count of bacteria), unless a transition out of that state is contact-mediated, which is then the acquisition (so S -> V alongside S -> I @ beta * I is a vaccination). acquisition= on the transition says it outright.
resolve_attrs
internals.graph.Graph.resolve_attrs()Resolve each attribute: another attribute given by name, the cases of a derived one by state (a state, a sum of states, or a | of them), and its events
resolve_derived
internals.graph.Graph.resolve_derived()Which states are infected, and their results. The infected states are those the model says are infected (marked ss.State(infected=True), or in its own result infected = E + I), exactly; or, if it says none are, those of a force of infection: the states people are infected into, and the sources (E and I in S >> E @ beta*I). With neither, as in a staged condition such as a cancer, no state is infected. Each state’s infected is set to match, and the infected states give the results infected, the number in them, and prevalence, their fraction of the people in every state, unless the module defines its own of that name, or has a state called infected (whose count has the name: it can define its own prevalence)
resolve_exits
internals.graph.Graph.resolve_exits()Group the transitions out of each state: those with p= split on entry, the rest compete
resolve_init_prev
internals.graph.Graph.resolve_init_prev()By default, 1% of people start infected, seeded through the transmission (frequency- or density-dependent), unless a state is given a starting value
resolve_pars
internals.graph.Graph.resolve_pars()Turn inline values in the standard slots into named parameters (beta, dur, rate, p)
resolve_people
internals.graph.Graph.resolve_people()Which states are people: every state, unless it is declared a count (ss.State(people=False), e.g. mosquitoes or bacteria in the water); and the first state, where people are unless they are put elsewhere: default_state= if given, else the state named S or susceptible (in any case), else the one state transmission infects people from, else the first state of people made (states are kept in the order they were created: see resolve_states()), which describe() shows as a guess. Not the state a birth goes to (ss.birth(NB) says where births go, not where everyone starts), nor the order of the transitions
resolve_rest
internals.graph.Graph.resolve_rest()Work out where the people not given an initial state start: the first state, unless it is given an initial value of its own, which is then kept (init=dict(S=0.1, I=1e-4) starts 10% susceptible). Then it is the one state of people with no initial value, with a note in guessed; with none or several, there is no such state, and the initial values must sum to 1 (see Engine.init_fractions())
resolve_starting
internals.graph.Graph.resolve_starting()Let the starting values (init_prev, and each state’s init= and init_n=) leave levels out of an ss.by by label, which start at 0 (see ss.parameters.starting()); done when the sim is built, after values by name are set and before anything checks or reads them
resolve_states
internals.graph.Graph.resolve_states()Find the states: the ones declared, and those the transitions use
resolve_transitions
internals.graph.Graph.resolve_transitions()Give every transition a name, a source, and a rate or a dwell time
set_keywords
internals.graph.Graph.set_keywords()A value given as a keyword sets the parameter of that name; there is nothing else for it to be
set_slots
internals.graph.Graph.set_slots(tr, density=False)Record the kind of value each parameter of a transition is, as par.slot (which describe() uses): ‘rate’ or ‘dur’, or None for a plain number (e.g. a factor of a rate); returns the standard slots it fills, as (slot name, parameter). density says the transition is a transmission at a rate on the number or fraction of people in a state (beta*I.n, beta*I.frac), whose coefficient is beta too
spread_pars
internals.graph.Graph.spread_pars()The parameters whose value is a distribution across people (e.g. beta=ss.lognormal(0.3, 0.1)), other than dwell times, which are stages or are sampled on entry
stratify
internals.graph.Graph.stratify(**kwargs)Stratify the graph by one or more dimensions; see ss.Disease.stratify()
taken
internals.graph.Graph.taken(name)Whether a member of the module has this name
transmitted_from
internals.graph.Graph.transmitted_from()The states of people that transmission (by contact, or at a rate on counts of others) takes people from
unit_values
internals.graph.Graph.unit_values()All the typed values (durations and rates) in the graph, used to infer the sim’s unit
unset_default_init_prev
internals.graph.Graph.unset_default_init_prev()Remove the default init_prev