Skip to contents

Specify Flow Between Compartments

Source: R/formula_list_generators.R
mp_per_capita_flow.Rd

Specify different kinds of flows between compartments.

Usage

mp_per_capita_flow(from, to, rate, flow_name = NULL, abs_rate = NULL)

mp_per_capita_inflow(from, to, rate, flow_name = NULL, abs_rate = NULL)

mp_inflow(to, rate, rate_name = NULL)

mp_outflow(from, rate, abs_rate = NULL)

mp_per_capita_outflow(from, rate, flow_name = NULL, abs_rate = NULL)

Arguments

from

String giving the name of the compartment from which the flow originates.

to

String giving the name of the compartment to which the flow is going.

rate

String giving the expression for the per-capita flow rate. Alternatively, and for back compatibility, a two-sided formula with the left-hand-side giving the name of the absolute flow rate per time-step and the right-hand-side giving an expression for the per-capita rate of flow from from to to.

flow_name

String giving the name for the absolute flow rate per time-step. By default, during simulations, the absolute flow rate will be computed as from * rate. This default behaviour will simulate the compartmental model as discrete difference equations, but this can be changed to use other approaches such as ordinary differential equations or stochastic models (see state_updates). If a formula is passed to rate (not recommended for better readability), then this flow_rate argument will be ignored.

abs_rate

Deprecated synonym for flow_name. Please use flow_name in all future work.

rate_name

String giving the name of the rate

Details

The examples below can be mixed and matched in mp_tmb_model_spec() to produce compartmental models. The symbols used below must be used in an appropriate context (e.g., if N is used for total population size, then there must be an expression like N ~ S + I + R somewhere in the model or for models with constant population size there must be a default variable, N, with a numerical value).

Functions

  • mp_per_capita_inflow(): Only flow into the to compartment, and do not flow out of the from compartment. The from compartment can even be a function of a set of compartments, because it will not be updated. A common construction is mp_per_capita_inflow("N", "S", "birth_rate", "birth") for adding a birth process, which involves the total population size, N, rather than a single compartment.

  • mp_inflow(): Only flow into the to compartment For adding a birth or immigration process

  • mp_outflow(): Only flow into the to compartment For adding an absolute removal process that goes to 'nowhere': dangerous!

  • mp_per_capita_outflow(): Only flow out of the from compartment, without going anywhere. This is useful for removing individuals from the system (e.g., death). To keep track of the total number of dead individuals one can use mp_per_capita_flow and set to to be a compartment for these individuals (e.g., to = "D").

See also

mp_absolute_flow()

Examples


# infection by mass action
# https://github.com/canmod/macpan2/blob/main/inst/starter_models/si
mp_per_capita_flow("S", "I", "beta * I / N", "infection")
#> From: S
#> To: I
#> Per-capita rate expression: beta * I/N
#> Absolute rate symbol: infection

# recovery
# https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir
mp_per_capita_flow("I", "R", "gamma", "recovery")
#> From: I
#> To: R
#> Per-capita rate expression: gamma
#> Absolute rate symbol: recovery

# disease progression with different severity
# https://github.com/canmod/macpan2/blob/main/inst/starter_models/macpan_base
mp_per_capita_flow("E", "I_mild", "alpha * phi"      , "progression_mild")
#> From: E
#> To: I_mild
#> Per-capita rate expression: alpha * phi
#> Absolute rate symbol: progression_mild
mp_per_capita_flow("E", "I_sev" , "alpha * (1 - phi)", "progression_sev")
#> From: E
#> To: I_sev
#> Per-capita rate expression: alpha * (1 - phi)
#> Absolute rate symbol: progression_sev

# birth
# https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir_demog
mp_per_capita_inflow("N", "S", "nu", "birth")
#> From: N
#> To: S
#> Per-capita rate expression: nu
#> Absolute rate symbol: birth

# death
# https://github.com/canmod/macpan2/blob/main/inst/starter_models/sir_demog
mp_per_capita_outflow("S", "mu", "death_S")
#> From: S
#> Per-capita rate expression: mu
#> Absolute rate symbol: death_S
mp_per_capita_outflow("I", "mu", "death_I")
#> From: I
#> Per-capita rate expression: mu
#> Absolute rate symbol: death_I
mp_per_capita_outflow("R", "mu", "death_R")
#> From: R
#> Per-capita rate expression: mu
#> Absolute rate symbol: death_R

# vaccination 
# https://github.com/canmod/macpan2/blob/main/inst/starter_models/shiver
mp_per_capita_flow("S", "V", "((a * S)/(b + S))/S",  "vaccination")
#> From: S
#> To: V
#> Per-capita rate expression: ((a * S)/(b + S))/S
#> Absolute rate symbol: vaccination

# importation (experimental)
# mp_absolute_inflow("I", "delta", "importation")