Make a Calibrator — mp_tmb_calibrator • macpan2

Construct an object that can get used to calibrate an object produced by mp_tmb_model_spec or mp_tmb_library, and possibly modified by mp_tmb_insert or mp_tmb_update. Note that the output of this function is not a model that has been calibrated to data, but rather an object that contains a model that can be calibrated. To actually attempt a calibration one needs the mp_optimize function (see examples below).

Usage

mp_tmb_calibrator(
  spec,
  data = empty_trajectory,
  traj = character(),
  par = character(),
  tv = character(),
  outputs = traj,
  default = list(),
  time = NULL,
  save_data = TRUE
)

Arguments

spec: An TMB model spec to fit to data. Such specs can be produced by mp_tmb_model_spec or mp_tmb_library, and possibly modified with mp_tmb_insert and mp_tmb_update.
data: A data frame containing trajectories to fit to and possibly time-varying parameters. The data must be of the same format as that produced by mp_trajectory.
traj: A character vector giving the names of trajectories to fit to data, or a named list of likelihood distributions specified with distribution for each trajectory.
par: A character vector giving the names of parameters, either time-varying or not, to fit using trajectory match.
tv: A character vector giving the names of parameters to make time-varying according to the values in data, or a radial basis function specified with mp_rbf.
outputs: A character vector of outputs that will be generated when mp_trajectory, mp_trajectory_sd, or mp_trajectory_ensemble are called on the optimized calibrator. By default it is just the trajectories listed in traj.
default: A list of default values to use to update the defaults in the spec. By default nothing is updated. Alternatively one could use mp_tmb_update to update the spec outside of the function. Indeed such an approach is necessary if new expressions, in addition to default updates, need to be added to the spec (e.g. seasonally varying transmission).
time: Specify the start and end time of the simulated trajectories, and the time period associated with each time step. The default is NULL, which takes simulation bounds from the data. You can use mp_sim_bounds and mp_sim_offset to be more specific. See the example on the mp_optimize help file for an illustration the use of mp_sim_offset.
save_data: Save a copy of the data in the calibrator object that is returned, so that you do not need to pass the data manually to downstream functions like mp_forecaster. It the resulting calibrator object is so large that it causes you problems, consider not saving the data in the calibrator object and manually passing it to the data argument of mp_forecaster.

Examples

spec = mp_tmb_library("starter_models", "sir", package = "macpan2")
sim = mp_simulator(spec, 50, "infection")
data = mp_trajectory(sim)
cal = mp_tmb_calibrator(
    spec
  , data
  , traj = "infection"
  , par = "beta"
  , default = list(beta = 0.25)
)
mp_optimize(cal)
#> outer mgc:  389.7835 
#> outer mgc:  259.2344 
#> outer mgc:  40.03711 
#> outer mgc:  1.594322 
#> outer mgc:  0.002775624 
#> outer mgc:  8.4447e-09 
#> $par
#> params 
#>    0.2 
#> 
#> $objective
#> [1] 49.74796
#> 
#> $convergence
#> [1] 0
#> 
#> $iterations
#> [1] 5
#> 
#> $evaluations
#> function gradient 
#>        6        6 
#> 
#> $message
#> [1] "relative convergence (4)"
#> 
mp_tmb_coef(cal)  ## requires broom.mixed package
#> outer mgc:  8.4447e-09 
#> outer mgc:  11.74622 
#> outer mgc:  12.05664 
#> outer mgc:  31.01941 
#>     term  mat row col default  type estimate   std.error
#> 1 params beta   0   0    0.25 fixed      0.2 0.009166433