Modify a TMB Model Spec — mp_tmb

Insert, update, or delete elements of a TMB model spec, produced using mp_tmb_library or mp_tmb_model_spec, or mp_tmb_delete. The only difference between mp_tmb_insert and mp_tmb_update is that the former shifts the positions of existing expressions to make room for the new expressions, whereas the latter overwrites existing expressions using the new expressions. The treatment of new default values and integers is the same. The examples below clarify this difference. Note that mp_tmb_delete does not contain an expressions argument, because it is not necessary to specify new expressions in the case of deletion.

Usage

mp_tmb_insert(
  model,
  phase = "during",
  at = 1L,
  expressions = list(),
  default = list(),
  integers = list(),
  must_save = character(),
  must_not_save = character(),
  sim_exprs = character()
)

mp_tmb_update(
  model,
  phase = "during",
  at = 1L,
  expressions = list(),
  default = list(),
  integers = list(),
  must_save = character(),
  must_not_save = character(),
  sim_exprs = character()
)

mp_tmb_delete(
  model,
  phase,
  at,
  default = character(),
  integers = character(),
  must_save = character(),
  must_not_save = character(),
  sim_exprs = character()
)

Arguments

model: TMB model spec object produced using mp_tmb_library or mp_tmb_model_spec.
phase: At what phase should expressions be inserted, updated, or deleted.
at: Expression number, which can be identified by printing out model, at which the expressions should be inserted or updated. If inserted then the existing expressions with number at and higher are shifted after the new expressions are added. If updated, then the existing expressions with number from at to at + length(expressions) - 1 are replaced with the new expressions. For mp_tmb_delete, a numeric vector of integers identifying expressions to delete from the model.
expressions: Expressions to insert into the model spec or to replace existing expressions.
default: Named list of objects, each of which can be coerced into a numeric matrix. The names refer to variables that appear in before, during, and after. For mp_tmb_delete, a character vector of such objects to delete from the model.
integers: Named list of vectors that can be coerced to integer vectors. These integer vectors can be used by name in model formulas to provide indexing of matrices and as grouping factors in group_sums. For mp_tmb_delete, a character vector of such objects to delete from the model.
must_save: Character vector of the names of matrices that must have their values stored at every iteration of the simulation loop. For example, a matrix that the user does not want to be returned but that impacts dynamics with a time lag must be saved and therefore in this list.
must_not_save: Character vector of the names of matrices that must not have their values stored at every iteration of the simulation loop. For example, the user may ask to return a very large matrix that would create performance issues if stored at each iteration. The creator of the model can mark such matrices making it impossible for the user of the model to save their full simulation history.
sim_exprs: Character vector of the names of before, during, and after expressions that must only be evaluated when simulations are being produced and not when the objective function is being evaluated. For example, expressions that generate stochasticity should be listed in sim_exprs because TMB objective functions must be continuous.

Value

A new model spec object with updated and/or inserted information.

Details

These modifications do not update the model specification in-place. Instead the output of mp_tmb_insert, mp_tmb_update, and mp_tmb_delete define a new model specification and should be saved if you want to use the new model (e.g., new_model = mp_tmb_insert(model, ...)).

Examples

si = mp_tmb_library("starter_models", "si", package = "macpan2")
print(si)
#> ---------------------
#> Default values:
#> ---------------------
#>  matrix row col value
#>       N         100.0
#>    beta           0.2
#>       I           1.0
#> 
#> ---------------------
#> Before the simulation loop (t = 0):
#> ---------------------
#> 1: S ~ N - 1
#> 
#> ---------------------
#> At every iteration of the simulation loop (t = 1 to T):
#> ---------------------
#> 1: mp_per_capita_flow(from = "S", to = "I", rate = "beta * I / N", 
#>      abs_rate = "infection")
#> 

## Update the mixing process to include 
## optional phenomenological heterogeneity.
## We need mp_tmb_update here so that 
## the previous infection expression is
## overwritten.
mp_tmb_update(si, phase = "during"
  , at = 1
  , expressions = list(infection ~ beta * I * (S/N)^zeta)
  , default = list(zeta = 1)
)
#> ---------------------
#> Default values:
#> ---------------------
#>  matrix row col value
#>       N         100.0
#>    beta           0.2
#>       I           1.0
#>    zeta           1.0
#> 
#> ---------------------
#> Before the simulation loop (t = 0):
#> ---------------------
#> 1: S ~ N - 1
#> 
#> ---------------------
#> At every iteration of the simulation loop (t = 1 to T):
#> ---------------------
#> 1: infection ~ beta * I * (S/N)^zeta
#> 

## Parameterize with log_beta in place of beta.
## We need mp_tmb_insert here so that the
## existing expression for computing the initial
## number of susceptible indiviudals is not
## overwritten.
mp_tmb_insert(si, phase = "before"
  , at = 1
  , expressions = list(beta ~ exp(log_beta))
  , default = list(log_beta = log(0.5))
)
#> ---------------------
#> Default values:
#> ---------------------
#>    matrix row col       value
#>         N         100.0000000
#>      beta           0.2000000
#>         I           1.0000000
#>  log_beta          -0.6931472
#> 
#> ---------------------
#> Before the simulation loop (t = 0):
#> ---------------------
#> 1: beta ~ exp(log_beta)
#> 2: S ~ N - 1
#> 
#> ---------------------
#> At every iteration of the simulation loop (t = 1 to T):
#> ---------------------
#> 1: mp_per_capita_flow(from = "S", to = "I", rate = "beta * I / N", 
#>      abs_rate = "infection")
#>