8 Other Variables
So far the only types of variables that we have discussed are parameters and state variables. In this chapter we cover all of the other kinds of variables.
There are two basic kinds of other variables: (1) Intermediate Results and (2) Additional Variables in the Simulation History. The main difference between the two types is that the former can be used for more purposes than the latter. In particular, intermediate results can be used in expressions that define rate matrices whereas additional variables in the simulation history cannot. Conversely, all intermediate results get added to the simulation history.
8.1 Intermediate Results
Sometimes the expression giving the rate of flow between two compartments is quite complex, or even just impossible to express in terms of just parameters and state variables given the restrictions described in the chapter on [Flows Between States]. In these cases, it is often convenient or even necessary to store intermediate combinations of parameters and state variables and then use these combinations in subsequent expressions for flow rates. There are three basic kinds of intermediate results: (1) sums of state variables and parameters, (2) more general expressions, called factrs, that combine state variables, parameters, and their sums, and (3) power laws involving any of these variables as base, exponent, and constant.
8.1.1 Sums of State Variables and Parameters
One may save any sum of state variables and/or parameters to the model. In our SIR model for example, we specified the total population size in the parameter vector as N. However, we could compute this population size using the add_state_param_sum function.
sir_with_sums = (flexmodel(
params = c(beta = 0.1, gamma = 0.01),
state = c(S = 99, I = 1, R = 0),
start_date = "2020-03-11",
end_date = "2020-12-01"
)
%>% add_state_param_sum("N", "S|I|R")
%>% add_rate("S", "I", ~ (I) * (beta) * (1/N))
%>% add_rate("I", "R", ~ (gamma))
)The first argument to the add_state_param_sum is just a name for the sum. Note that this name is used in the add_rate function that defines the flows from S to I. The second argument to the add_state_param_sum is a regular expression that is matched agains all parameter names and state variable names. Here we match any state variable with "S|I|R", which tells McMasterPandemic to add up all state variables and save the result in the variable called "N".
See the Erlang SEIR example that uses a sum to save the total number of infected individuals across all I compartments in an Erlang-chain. See the BC Covid Omicron example that uses a sum to save the total number of individuals infected with different COVID strains.
8.1.2 Factrs
First off, I’m sorry about the name factr. It is not a typo, I just don’t have the energy to change it to something better right now.
factrs are simply a saved expression that follows the same rules for rates of [Flows Between States]. These factrs are named and can subsequently be used in rate expressions.
The SIR model is not really complex enough to justify using factrs, but if we wanted to we could store the proportion of individuals that are in the I box as a factr and then use that factr in the expression for the rate from S to I.
sir_with_factrs = (flexmodel(
params = c(beta = 0.1, gamma = 0.01),
state = c(S = 99, I = 1, R = 0),
start_date = "2020-03-11",
end_date = "2020-12-01"
)
%>% add_state_param_sum("N", "S|I|R")
%>% add_factr("Iprop", ~ (I) * (1/N))
%>% add_rate("S", "I", ~ (Iprop) * (beta))
%>% add_rate("I", "R", ~ (gamma))
)See also the SI model example for a use of factrs that computes the equilibrium populations in each compartment.
8.1.3 Power Laws
Intermediate results of the following functional form can be specified.
\[ y = y_0x^b \] where \(y\) is the new intermediate result, and \(y_0\), \(x\), and \(b\) are parameters, state variables, sums/factrs of state variables and parameters, or other powers that have previously been specified.
This HIV mode provides an example of the usage of power laws.
8.1.3.1 Phenomenological heterogeneity
Without heterogeneity the force of infection might look like this.
\[ \text{rate(S to E)} = \beta \left(\frac{1}{N}\right)I \]
Adding heterogeneity we might do this.
\[ \text{rate(S to E)} = \beta \left(\frac{1}{N}\right)^{1+\zeta}S^\zeta I \]
When \(\zeta = 0\) we recover the model without heterogeneity. We can then multiply this rate by \(S\) to get the flow.
\[ \text{flow(S to E)} = S \beta \left(\frac{1}{N}\right)^{1+\zeta}S^\zeta I = \beta \left(\frac{S}{N}\right)^{1+\zeta} I \]
8.2 Additional Variables in the Simulation History
The simulation_history function returns a data frame containing many of the variables in the model, with each row giving each time step in the simulation. This simulation_history function is introduced in the chapter on Simulation. This simulation history table is used for two purposes: (1) to return to the user as simulation output and (2) to compare with observed time series in in the process of Calibration.
The simulation history contains the following variables in the following order:
- State variables
- Flow rates that vary in simulation time (constant rates are omitted)
- Sums of state variables and parameters
factrs- Expressions following the rules in [Flows Between States] of any of the variables in 1-4 above
- Lagged differenced versions of 1-5
- Convolutions of 1-5
Items 5-7 consitute the additional variables in the simulation history. In the next sections we illustrate how to add such variables to the SIR model.