G3 language extensions to R — language • gadget3

Additional meta-functions available for use in G3 formula.

Details

Whilst used as functions, these functions alter the code output of the model, rather than appearing directly.

g3_idx

Adds a - 1 to the supplied expression, but only in C++ (which has 0-based indexes). Under R the expression is passed through unchanged.

Note: This is generally for internal use, as [[ will do this automatically for you.

For example, g3_idx(a) will be replaced with a in R output and a - 1 in C++ output.

g3_param

Reference a scalar parameter by name. Arguments:

name: Variable name for parameter. Required
value: Initial value in model parameter_template. Default 0
optimise: Initial optimise setting in parameter_template. Default TRUE
random: Initial random setting in parameter_template. Default FALSE
lower: Initial lower setting in parameter_template. Default NA
upper: Initial upper setting in parameter_template. Default NA

For example, g3_param("ling.Linf") will register a scalar parameter called ling.Linf, available in the model parameter template, and be replaced by a reference to that parameter.

g3_param("ling.Linf") can be used multiple times, to refer to the same value.

g3_param_vector

Reference a vector parameter by name. Arguments:

name: Variable name for parameter. Required
value: Initial value for use in model paramter_template. Default 0

Same as g3_param, but the parameter will be expected to be a vector. You can then dereference with [[.

For example, g3_param_vector("lingimm.M")[[age - 3 + 1]].

g3_param_table

Reference a lookup-table of parameters.

name: Variable name for parameter. Required
table: A data.frame, one column for each variable to check, one row for possible values. Required
value: Initial value for use in model parameter_template. Default 0
optimise: Initial optimise setting in parameter_template. Default TRUE
random: Initial random setting in parameter_template. Default FALSE
lower: Initial lower setting in parameter_template. Default NA
upper: Initial upper setting in parameter_template. Default NA
ifmissing: Value to return when outside of table bounds. Default NaN with warning if a value is missing

This is similar to providing a vector, but can use values in the model to provide bounds-checking.

The function takes 2 arguments, a prefix for the generated parameters, and a data.frame of variables to possible values. expand.grid can be used to produce a cross product of all provided variables.

Note: The variables referenced will need to be integer variables, most likely iteration variables such as cur_year, age, area...

For example, the following: g3_param_table('lingimm.M', expand.grid(age = seq(ling_imm__minage, ling_imm__maxage))) will generate parameters lingimm.M.3..lingimm.M.10, assuming that ling_imm has ages 3..10.

The call to g3_param_table will be replaced with param[[paste("lingimm.M", age, sep = ".")]], or equivalent code in C++.

g3_with

g3_with(var1 := val1, var2 := val2, { x <- val1 * val2 }) is equivalent to local({var1 <- val1, var2 <- val2, { x <<- val1 * val2 } })

However, we don't make a new environment for the code block in R, only in C++.